diff options
| -rw-r--r-- | Documentation/git-sh-setup.txt | 8 | ||||
| -rw-r--r-- | Documentation/git.txt | 10 | ||||
| -rw-r--r-- | git-sh-setup.sh | 34 |
3 files changed, 49 insertions, 3 deletions
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 6a9f66d1d9..79a88b9205 100644 --- 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 9e302b0a60..78db385fb7 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -841,6 +841,16 @@ GIT_LITERAL_PATHSPECS:: literal paths to Git (e.g., paths previously given to you by `git ls-tree`, `--raw` diff output, etc). +'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 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 |