global/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2026-03-26 08:30:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

setup_reflog_action: document the rules for using GIT_REFLOG_ACTION

Browse Source 
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>
This commit is contained in:
Junio C Hamano
2013-06-19 10:54:00 -07:00
parent b3b8ceb48b
commit c3e2d18996
3 changed files with 49 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
Documentation/git-sh-setup.txt
View File

@@ -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

10
Documentation/git.txt
View File

@@ -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]]
------------------------