From 9a51e591a683e3d9914c203a046016a921541a3e Mon Sep 17 00:00:00 2001
From: Stephen Haberman <stephen@exigencecorp.com>
Date: Wed, 12 Nov 2008 01:30:22 -0600
Subject: [PATCH] Add documentation for the scripts.

---
 scripts/checkout         |  8 ++++++++
 scripts/create-gitconfig | 10 ++++++++++
 scripts/create-stable    |  5 +++++
 scripts/pull             | 12 ++++++++++++
 scripts/push             |  3 +++
 5 files changed, 38 insertions(+)

diff --git a/scripts/checkout b/scripts/checkout
index e326b38..8576a70 100644
--- 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
--- 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
--- 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
--- 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
--- 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
-- 
2.39.5