Re: want <reason> option to git-rebase

Re: want <reason> option to git-rebase

[Jonathan Nieder]

Hi,

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

Re: want <reason> option to git-rebase

[Ian Jackson]

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

Re: want <reason> option to git-rebase

[Johannes Sixt]

Am 19.06.2018 um 03:06 schrieb Jonathan Nieder:
> 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

Re: want <reason> option to git-rebase

[Jonathan Nieder]

Johannes Sixt wrote:
> Am 19.06.2018 um 03:06 schrieb Jonathan Nieder:
>> 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,
[...]
>>  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

Re: want <reason> option to git-rebase

[Ian Jackson]

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:

> >> "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.