rebase -i: Document how temporary files are used

Add documentation, inferred by reverse-engineering, about how
git-rebase--interactive.sh uses many of its temporary files.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/git-rebase--interactive.sh b/git-rebase--interactive.sh
index efd5749973dc156db07a338435263f22fa1d7168..acc92c439d8e9998a5bca1079493d05157fe12ef 100755 (executable)
--- a/git-rebase--interactive.sh
+++ b/git-rebase--interactive.sh
@@ -34,11 +34,45 @@ root               rebase all reachable commmits up to the root(s)
 require_work_tree
 
 DOTEST="$GIT_DIR/rebase-merge"
+
+# The file containing rebase commands, comments, and empty lines.
+# This file is created by "git rebase -i" then edited by the user.  As
+# the lines are processed, they are removed from the front of this
+# file and written to the tail of $DONE.
 TODO="$DOTEST"/git-rebase-todo
+
+# The rebase command lines that have already been processed.  A line
+# is moved here when it is first handled, before any associated user
+# actions.
 DONE="$DOTEST"/done
+
+# The commit message that is planned to be used for any changes that
+# need to be committed following a user interaction.
 MSG="$DOTEST"/message
+
+# The file into which is accumulated the suggested commit message for
+# squash/fixup commands.  When the first of a series of squash/fixups
+# is seen, the file is created and the commit message from the
+# previous commit and from the first squash/fixup commit are written
+# to it.  The commit message for each subsequent squash/fixup commit
+# is appended to the file as it is processed.
+#
+# The first line of the file is of the form
+#     # This is a combination of $COUNT commits.
+# where $COUNT is the number of commits whose messages have been
+# written to the file so far (including the initial "pick" commit).
+# Each time that a commit message is processed, this line is read and
+# updated.  It is deleted just before the combined commit is made.
 SQUASH_MSG="$DOTEST"/message-squash
+
+# $REWRITTEN is the name of a directory containing files for each
+# commit that is reachable by at least one merge base of $HEAD and
+# $UPSTREAM. They are not necessarily rewritten, but their children
+# might be.  This ensures that commits on merged, but otherwise
+# unrelated side branches are left alone. (Think "X" in the man page's
+# example.)
 REWRITTEN="$DOTEST"/rewritten
+
 DROPPED="$DOTEST"/dropped
 PRESERVE_MERGES=
 STRATEGY=
@@ -683,13 +717,6 @@ first and then run 'git rebase --continue' again."
                test t = "$VERBOSE" && : > "$DOTEST"/verbose
                if test t = "$PRESERVE_MERGES"
                then
-                       # $REWRITTEN contains files for each commit that is
-                       # reachable by at least one merge base of $HEAD and
-                       # $UPSTREAM. They are not necessarily rewritten, but
-                       # their children might be.
-                       # This ensures that commits on merged, but otherwise
-                       # unrelated side branches are left alone. (Think "X"
-                       # in the man page's example.)
                        if test -z "$REBASE_ROOT"
                        then
                                mkdir "$REWRITTEN" &&