Merge branch 'jc/reflog-doc'

Document rules to use GIT_REFLOG_ACTION variable in the scripted
Porcelain.  git-rebase--interactive locally violates them, but it
is a leaf user that does not call out to or dot-source other
scripts, so it does not urgently need to be fixed.

* jc/reflog-doc:
setup_reflog_action: document the rules for using GIT_REFLOG_ACTION

diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index 5d709d02c39e10ac946c3870a10d959a4c12a5d4..4f67c4cde679cf03e8cc43ac0630a45b5e68aa2d 100644 (file)
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -41,9 +41,11 @@ usage::
        die with the usage message.
 
 set_reflog_action::
-       set the message that will be recorded to describe the
-       end-user action in the reflog, when the script updates a
-       ref.
+       Set GIT_REFLOG_ACTION environment to a given string (typically
+       the name of the program) unless it is already set.  Whenever
+       the script runs a `git` command that updates refs, a reflog
+       entry is created using the value of this string to leave the
+       record of what command updated the ref.
 
 git_editor::
        runs an editor of user's choice (GIT_EDITOR, core.editor, VISUAL or

diff --git a/Documentation/git.txt b/Documentation/git.txt
index da7be1fdf4d9654d962984d3b25f655439237e30..4f7e07f2e0f4f6317c81467f7f880b4113b12de1 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -909,6 +909,16 @@ GIT_ICASE_PATHSPECS::
        Setting this variable to `1` will cause Git to treat all
        pathspecs as case-insensitive.
 
+'GIT_REFLOG_ACTION'::
+       When a ref is updated, reflog entries are created to keep
+       track of the reason why the ref was updated (which is
+       typically the name of the high-level command that updated
+       the ref), in addition to the old and new values of the ref.
+       A scripted Porcelain command can use set_reflog_action
+       helper function in `git-sh-setup` to set its name to this
+       variable when it is invoked as the top level command by the
+       end user, to be recorded in the body of the reflog.
+
 
 Discussion[[Discussion]]
 ------------------------

diff --git a/git-sh-setup.sh b/git-sh-setup.sh
index e15be516369e5e5a9096bb957966938e134e616c..ebfe8f7a4d0697422a826d7878855bf9e92d0060 100644 (file)
--- a/git-sh-setup.sh
+++ b/git-sh-setup.sh
@@ -103,6 +103,40 @@ $LONG_USAGE"
        esac
 fi
 
+# Set the name of the end-user facing command in the reflog when the
+# script may update refs.  When GIT_REFLOG_ACTION is already set, this
+# will not overwrite it, so that a scripted Porcelain (e.g. "git
+# rebase") can set it to its own name (e.g. "rebase") and then call
+# another scripted Porcelain (e.g. "git am") and a call to this
+# function in the latter will keep the name of the end-user facing
+# program (e.g. "rebase") in GIT_REFLOG_ACTION, ensuring whatever it
+# does will be record as actions done as part of the end-user facing
+# operation (e.g. "rebase").
+#
+# NOTE NOTE NOTE: consequently, after assigning a specific message to
+# GIT_REFLOG_ACTION when calling a "git" command to record a custom
+# reflog message, do not leave that custom value in GIT_REFLOG_ACTION,
+# after you are done.  Other callers of "git" commands that rely on
+# writing the default "program name" in reflog expect the variable to
+# contain the value set by this function.
+#
+# To use a custom reflog message, do either one of these three:
+#
+# (a) use a single-shot export form:
+#     GIT_REFLOG_ACTION="$GIT_REFLOG_ACTION: preparing frotz" \
+#         git command-that-updates-a-ref
+#
+# (b) save the original away and restore:
+#     SAVED_ACTION=$GIT_REFLOG_ACTION
+#     GIT_REFLOG_ACTION="$GIT_REFLOG_ACTION: preparing frotz"
+#     git command-that-updates-a-ref
+#     GIT_REFLOG_ACITON=$SAVED_ACTION
+#
+# (c) assign the variable in a subshell:
+#     (
+#         GIT_REFLOG_ACTION="$GIT_REFLOG_ACTION: preparing frotz"
+#         git command-that-updates-a-ref
+#     )
 set_reflog_action() {
        if [ -z "${GIT_REFLOG_ACTION:+set}" ]
        then