Add documentation for the scripts.

diff --git a/scripts/checkout b/scripts/checkout
index e326b38e99f5cff52d0071e84010cf4744df9ee9..8576a7022fa39e290e12684c703206d262f79596 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 555603822c01ca317821feaa26e9608f3aad983c..12cfeae89fb271fd2b9b5c6885d592f2699a849b 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 89d39bec480ac03a6699c7b82ba4399e69c74492..3ee75036f014b63cf3e8f9d705be98e3b779f0b9 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 64de460a9fdca06c966abbeba3e83984736bf102..c8bcbdd42183373089c13ddee4084ef5710d730a 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 7583ce607030d28990a1e52f7ea8c613fe87291a..ac9151da692def1925a92f7f47bb9d1389f9d2d3 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