summaryrefslogtreecommitdiff
path: root/git-sh-setup.sh
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2013-06-19 10:54:00 -0700
committerJunio C Hamano <gitster@pobox.com>2013-06-19 10:54:00 -0700
commitc3e2d18996e4ef92f37bf56b2fefe2124d26659e (patch)
tree91b0fe91d2ffc0686f5f4bb17ba8b6a161cb560d /git-sh-setup.sh
parentb3b8ceb48b7d75631a8638f1dc6ccdf7f1b53888 (diff)
downloadgit-c3e2d18996e4ef92f37bf56b2fefe2124d26659e.tar.gz
setup_reflog_action: document the rules for using GIT_REFLOG_ACTIONjc/reflog-doc
The set_reflog_action helper (in git-sh-setup) is designed to be used once at the very top of a program, like this in "git am", for example: set_reflog_action am The helper function sets the given string to GIT_REFLOG_ACTION only when GIT_REFLOG_ACTION is not yet set. Thanks to this, "git am", when run as the top-level program, will use "am" in GIT_REFLOG_ACTION and the reflog entries made by whatever it does will record the updates of refs done by "am". Because of the conditional assignment, when "git am" is run as a subprogram (i.e. an implementation detail) of "git rebase" that already sets GIT_REFLOG_ACTION to its own name, the call in "git am" to the helper function at the beginning will *not* have any effect. So "git rebase" can do this: set_reflog_action rebase ... do its own preparation, like checking out "onto" commit ... decide to do "format-patch" to "am" pipeline git format-patch --stdout >mbox git am mbox and the reflog entries made inside "git am" invocation will say "rebase", not "am". Calls to "git" commands that update refs would use GIT_REFLOG_ACTION to record who did that update. Most such calls in scripted Porcelains do not define custom reflog message and rely on GIT_REFLOG_ACTION to contain its (or its caller's, when it is called as a subprogram) name. If a scripted Porcelain wants to record a custom reflog message for a single invocation of "git" command (e.g. when "git rebase" uses "git checkout" to detach HEAD at the commit a series is to be replayed on), it needs to set GIT_REFLOG_ACTION to the custom message and export it while calling the "git" command, but such an assignment must be restricted to that single "git" invocation and should not be left behind to affect later codepath. Document the rules to avoid future confusion. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'git-sh-setup.sh')
-rw-r--r--git-sh-setup.sh34
1 files changed, 34 insertions, 0 deletions
diff --git a/git-sh-setup.sh b/git-sh-setup.sh
index 9cfbe7f143..53ab0684f2 100644
--- 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