Add documentation for the scripts.

diff --git a/scripts/checkout b/scripts/checkout
index e326b38..8576a70 100644 (file)
--- a/scripts/checkout
+++ b/scripts/checkout
@@ -1,4 +1,12 @@
 #!/bin/sh
+#
+# Makes checkout "just work" in terms of checking out the branch whether or not
+# it exists locally or remotely.
+#
+# If the branch exists locally (e.g. foo), then just check it out
+# If the branch exists remotely (e.g. origin/foo), then create a new local branch
+# If the branch does not exist remote, then make a new local branch and push it
+#
 
 branch_name=$1
 

diff --git a/scripts/create-gitconfig b/scripts/create-gitconfig
index 5556038..12cfeae 100644 (file)
--- a/scripts/create-gitconfig
+++ b/scripts/create-gitconfig
@@ -1,4 +1,14 @@
 #!/bin/sh
+#
+# Creates a separate DAG in your repo for git config files.
+#
+# This allows you to checkout/modify/push the config/hooks for your repo
+# locally. Then, with the help of post-receive-gitconfig, have your changes be
+# automatically updated on the server.
+#
+# Also, it keeps all of your repo-specific information in your repo instead of
+# leaking out into potentiallyshared hook scripts.
+#
 
 # Create an empty file object
 empty_file_hash=$(git hash-object -w --stdin <<FOO

diff --git a/scripts/create-stable b/scripts/create-stable
index 89d39be..3ee7503 100644 (file)
--- a/scripts/create-stable
+++ b/scripts/create-stable
@@ -1,4 +1,9 @@
 #!/bin/sh
+#
+# Creates a separate DAG in the repo to merge stable into.
+#
+# See the other docs about why this is a good idea.
+#
 
 # Make a root directory tree with no files in it
 config_tree_hash=$(git mktree <<FOO

diff --git a/scripts/pull b/scripts/pull
index 64de460..c8bcbdd 100644 (file)
--- a/scripts/pull
+++ b/scripts/pull
@@ -1,4 +1,16 @@
 #!/bin/sh
+#
+# Makes pull "just work" by correctly rebasing of local commits on top of new
+# incoming commits.
+#
+# This avoids the "same-branch" merges that the default "git pull" creates of
+# your local branch foo being merged into the remote branch origin/foo.
+#
+# Also, even though "git pull" has a branch.<name>.rebase flag, it will replay
+# commits if you have local merges of other branches that are being rebased--the
+# "-p" parameter to git rebase prevents this reply but is not available from the
+# "git pull" command line or config options--hence this script.
+#
 
 branch_name=$(git symbolic-ref --quiet HEAD)
 if [[ $? -ne 0 ]] ; then

diff --git a/scripts/push b/scripts/push
index 7583ce6..ac9151d 100644 (file)
--- a/scripts/push
+++ b/scripts/push
@@ -1,4 +1,7 @@
 #!/bin/sh
+#
+# Makes push "just work" by only pushing the current branch to origin.
+#
 
 branch_name=$(git symbolic-ref --quiet HEAD)
 if [[ $? -ne 0 ]] ; then