threads / discuss / 48735

Re: want <reason> option to git-rebase

Subject: Re: want <reason> option to git-rebase

## tl;dr

5 messages between Jun 19, 2018 and Jun 20, 2018.

replies: 4people: 3as markdown or json

Jonathan Nieder· Jun 19, 2018, 01:06 UTC · lore
Hi,
Ian Jackson wrote[1]:
Show 20 quoted lines
> git-rebase leaves entries like this in the reflog:
>
>   c15f4d5391 HEAD@{33}: rebase: checkout c15f4d5391ff07a718431aca68a73e672fe8870e
>
> It would be nice if there were an option to control this message.
> Particularly, when another tool invokes git-rebase, the other tool may
> specify an interesting --onto, and there is no way to record any
> information about that --onto commit.
>
> git-rebase already has a -m option, so I suggest
>   --reason=<reason>
>
> It doesn't matter much exactly how the provided string is used.
> Any of the following would be good IMO:
>   <reason>
>   rebase start: <reason>
>
> I think:
>   rebase: checkout c15f4d5391ff07a718431aca68a73e672fe8870e <reason>
> would be rather cumbersome.
From git(1):
 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.
"git rebase" sets this itself, so it doesn't solve your problem.

Can you say more about what your tool does? I'm wondering if it would make sense for it to use lower-level commands where GIT_REFLOG_ACTION applies, instead of the more user-facing git rebase.

Thanks, Jonathan

[1] https://bugs.debian.org/901805
Ian Jackson· Jun 19, 2018, 10:19 UTC · re: Jonathan Nieder · lore
Jonathan Nieder writes ("Re: want <reason> option to git-rebase"):
> Ian Jackson wrote[1]:
> > git-rebase leaves entries like this in the reflog:
> >
> >   c15f4d5391 HEAD@{33}: rebase: checkout c15f4d5391ff07a718431aca68a73e672fe8870e
...
Show 11 quoted lines
>  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.
> 
> "git rebase" sets this itself, so it doesn't solve your problem.
Hrm.
> Can you say more about what your tool does?  I'm wondering if it would
> make sense for it to use lower-level commands where GIT_REFLOG_ACTION
> applies, instead of the more user-facing git rebase.
Sure.
http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git-manpage/dgit.git/git-debrebase.1
See the description of git-rebase new-upstream.  It does a lot of
complicated work, synthesising a new pair of commits using plumbing
etc., and then does
  git rebase --onto <thing it made> <user's previous base>
If the user says git rebase --abort, everything should be undone.

Another alternative solution would be to be able to make git reflog entries without actually updating any ref.

Ian.
-- 
Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
Johannes Sixt· Jun 19, 2018, 18:31 UTC · re: Jonathan Nieder · lore
Am 19.06.2018 um 03:06 schrieb Jonathan Nieder:
Show 31 quoted lines
> Ian Jackson wrote[1]:
>> git-rebase leaves entries like this in the reflog:
>>
>>    c15f4d5391 HEAD@{33}: rebase: checkout c15f4d5391ff07a718431aca68a73e672fe8870e
>>
>> It would be nice if there were an option to control this message.
>> Particularly, when another tool invokes git-rebase, the other tool may
>> specify an interesting --onto, and there is no way to record any
>> information about that --onto commit.
>>
>> git-rebase already has a -m option, so I suggest
>>    --reason=<reason>
>>
>> It doesn't matter much exactly how the provided string is used.
>> Any of the following would be good IMO:
>>    <reason>
>>    rebase start: <reason>
> 
>  From git(1):
> 
>   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.
> 
> "git rebase" sets this itself, so it doesn't solve your problem.

If it does so unconditionally, then that is a bug. If a script wants to set GIT_REFLOG_ACTION, but finds that it is already set, then it must not change the value. set_reflog_action in git-sh-setup does the right thing.

So, if there is another script or application around git-rebase, then it should just set GIT_REFLOG_ACTION (if it is not already set) and export the environment variable to git-rebase.

-- Hannes
Jonathan Nieder· Jun 20, 2018, 01:49 UTC · re: Johannes Sixt · lore
Johannes Sixt wrote:
> Am 19.06.2018 um 03:06 schrieb Jonathan Nieder:
>> Ian Jackson wrote[1]:
Show 6 quoted lines
>>> git-rebase leaves entries like this in the reflog:
>>>
>>>    c15f4d5391 HEAD@{33}: rebase: checkout c15f4d5391ff07a718431aca68a73e672fe8870e
>>>
>>> It would be nice if there were an option to control this message.
>>> Particularly, when another tool invokes git-rebase,
[...]
Show 21 quoted lines
>>  From git(1):
>>
>>   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.
>>
>> "git rebase" sets this itself, so it doesn't solve your problem.
>
> If it does so unconditionally, then that is a bug. If a script wants to set
> GIT_REFLOG_ACTION, but finds that it is already set, then it must not change
> the value. set_reflog_action in git-sh-setup does the right thing.
>
> So, if there is another script or application around git-rebase, then it
> should just set GIT_REFLOG_ACTION (if it is not already set) and export the
> environment variable to git-rebase.

Oh, good catch. "git rebase" already generally does the right thing when GIT_REFLOG_ACTION is set (by only appending to it and never replacing it).

Ian, does that work well for you? If so, any ideas where it should go in the documentation to be more discoverable for next time?

Footnotes:
- git-rebase--interactive.sh has the following snippet:
	case "$orig_reflog_action" in
	''|rebase*)
		GIT_REFLOG_ACTION="rebase -i ($1)"
  This is a little too aggressive, since it's possible for a
  user-specified reflog action to start with "rebase" and
  contain additional information that shouldn't be removed.
- likewise in git-rebase--preserve-merges.sh.

Thanks, Jonathan

Ian Jackson· Jun 20, 2018, 10:43 UTC · re: Jonathan Nieder · lore
Jonathan Nieder writes ("Re: want <reason> option to git-rebase"):
> Oh, good catch.  "git rebase" already generally does the right thing
> when GIT_REFLOG_ACTION is set (by only appending to it and never
> replacing it).
Great.  I indeed did not know about this.
> Ian, does that work well for you?  If so, any ideas where it should go
> in the documentation to be more discoverable for next time?
Thanks for asking exactly the right question :-).

I didn't make a record of exactly where I looked but I'm pretty sure I looked at the manpages for git-reflog and git-rebase. I think I probably also looked at git-update-ref; I have read git-update-ref a number of times.

Right now in Debian unstable I see that none of these places document this convention.

I think git-reflog ought to mention it, so that it says where the information it provides comes from.

It also ought to be mentioned in git-update-ref, because all callers of git-update-ref need to implement it !

Indeed, because I didn't know about this convention, dgit and git-debrebase do not honour it. At least in my case, if it had been in git-update-ref I would have implemented it myself and then I would obviously have thought of making use of it myself.

Also, I have to say, the documentation for GIT_REFLOG_ACTION
in git(1) is very obscure.  It sort of generally waffles around what
it is for, but it does not say:
 * what does this variable contain
 * who can and should set it
 * who should consume it
 * what the rules are for modifying it

I don't think simply adding a cross-reference to GIT_REFLOG_ACTION in git(1) would be sufficient, without also improving this part.

The explanations provided by you and Johannes, here in these emails, are much much better:

Show 14 quoted lines
> >> "git rebase" sets this itself, so it doesn't solve your problem.
> >
> > If it does so unconditionally, then that is a bug. If a script
> > wants to set GIT_REFLOG_ACTION, but finds that it is already set,
> > then it must not change the value. set_reflog_action in
> > git-sh-setup does the right thing.
> >
> > So, if there is another script or application around git-rebase, then it
> > should just set GIT_REFLOG_ACTION (if it is not already set) and export the
> > environment variable to git-rebase.
> 
> Oh, good catch.  "git rebase" already generally does the right thing
> when GIT_REFLOG_ACTION is set (by only appending to it and never
> replacing it).

Maybe some of this prose, which explains things quite well, could be reworked into a form suitable for the git docs. (Even though there seems to be disagreement about whether a subcommand may *append* to GIT_REFLOG_ACTION; which, ISTM, is a practice which ought to be encouraged rather than discouraged.)

Regards, Ian.

-- 
Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

← back to recent threads