Advice on edits to git-rebase man page

Advice on edits to git-rebase man page

[Matthew Brett]

Hi,

Sorry for the rather open-ended email, but I am interested to whether
you would be interested in patches for git-rebase man page, based on a
tutorial page I wrote some ago:

http://matthew-brett.github.io/pydagogue/rebase_without_tears.html

The reason I ask, is because I have found the git-rebase man page
particularly difficult to read for an overview of what it is intended
for.   A colleague recently wrote to me asking if I would consider
proposing merging my page with the git man page.

Obviously my page as it is now is very different in tone from the
git-rebase page, but I think there are some aspects that could be
fruitfully merged.   Would you be interested in patches of this sort,
or does the page seem too far from the intention of the man page?

Best,

Matthew

Re: Advice on edits to git-rebase man page

[Matthieu Moy]

Matthew Brett <matthew.brett@gmail.com> writes:

> Obviously my page as it is now is very different in tone from the
> git-rebase page, but I think there are some aspects that could be
> fruitfully merged.   Would you be interested in patches of this sort,
> or does the page seem too far from the intention of the man page?

I think it is deliberate that manpages are not written as tutorial, but
as more advanced technical documentation. Just like learning Unix can
hardly be done by reading "man ls", "man cd", ... the best entry point
to learn Git is not the manpages. OTOH, I usually like Git's manpages
when I know what I'm looking for.

All that being said, there's a lot of room for improvement in our
manpages, event remaining in a technical-style. I'm not a good juge
because I already learnt how rebase works long ago, but the git rebase
man page does seem terrible for bare mortals:

  NAME
       git-rebase - Forward-port local commits to the updated upstream head

=> Quite technical already.

  DESCRIPTION
       If <branch> is specified, git rebase will perform an automatic
       git checkout <branch> before doing anything else. Otherwise it
       remains on the current branch.

=> Ouch, do we really want to start a documentation like this?

So, the DESCRIPTION part can definitely be improved IMHO. Your notation
<graft-point>, <exclude-from> and <include-from> may be an improvement
already.

Some concrete examples may help too, like "I started developing against
origin/foo, on local branch bar, and now want to rebase my work on top
of origin/boz".

My 2 cents,

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Advice on edits to git-rebase man page

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

>   NAME
>        git-rebase - Forward-port local commits to the updated upstream head
>
> => Quite technical already.

Very much true, and I would say the description is "technically
correct" in the sense that "it is not wrong per-se".  There are a
few points that this fails to state and some that this overspecifies.

 - Rebase is about changing the base of an existing branch, but the
   description does not even mention the word "branch" [*1*].

 - There is nothing "forward" about it.  I often see myself applying
   (tentatively) incoming patches on top of whatever commit I happen
   to have checked out, review it and then rebasing it to apply to
   older maintenance track if the topic is about fixing an old bug.

 - There is no point stressing "local" commits; all the operations
   you do to munge commits are local.

Perhaps something like this instead?

    git-rebase - Rebuild a branch on top of a different commit


>   DESCRIPTION
>        If <branch> is specified, git rebase will perform an automatic
>        git checkout <branch> before doing anything else. Otherwise it
>        remains on the current branch.
>
> => Ouch, do we really want to start a documentation like this?

No.  We should say what the command does and what the command is for
in more general terms first and then describe how arguments can be
used to affect it.

> So, the DESCRIPTION part can definitely be improved IMHO. Your notation
> <graft-point>, <exclude-from> and <include-from> may be an improvement
> already.

<graft-point>, <exclude-from> and <include-from> aren't technically
wrong per-se, but I do not think bulk-replacing the words currently
used in the manual page with these is an improvement at all, unless
the mental picture the explanation draws is also updated to match
these new words.

reBASE is about changing the base of the affected branch, and the
mental picture the current documentation draws is "there is a plant,
from which you cut a branch, scion. Then you graft the scion onto
understock".  It calls the original tree (that the branch being
transplanted is part of) the "old-base", and the understock (that
the scion is going to be grafted onto) the "new-base".  The word
"graft" in "graft point" may better convey that we are doing a
transplanting than the current wording, but the word "point" makes
it unclear to the readers if it refers to the "point" where the
scion was cut from or where it is going to transplanted to, I am
afraid.

Also <exclude-from> and <include-from> is probably too operational,
and describing the command with only these two words would miss the
point that the command is about transplanting a branch.  It is true
that in order to transplant a branch, you first need to figure out
the set of commits whose effects are to be replayed, you would need
<exclude-from>..<include-from> range computation, but it is an
lower-level implemention detail.

> Some concrete examples may help too, like "I started developing against
> origin/foo, on local branch bar, and now want to rebase my work on top
> of origin/boz".

Very much so, but I wonder if it would be better to just refer to
examples in the tutorial (and if we do not have good examples there,
we should add some).

[Footnote]

 *1* Yes, "git rebase $newbase $commit^0" form can be used to
     transplant a part of history leading to the $commit that does
     not sit at the tip of a branch (nor repoint a branch to point
     at the result at the end) as if $commit^0 were at the tip of
     some branch, but the key word here is "as if".  The user is
     allowed to use the command pretending something that is not a
     branch is a branch, but what it tells us is that the command
     *is* about a branch.

Re: Advice on edits to git-rebase man page

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> Perhaps something like this instead?
>
>     git-rebase - Rebuild a branch on top of a different commit

I would say "Replay history on top of a different commit" instead.
"Rebuild" may be misleading (it's not "build" as in "compile & link"),
and the rebased history does not technically have to be a branch.

But both are far better than what we have IMHO.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Advice on edits to git-rebase man page

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Perhaps something like this instead?
>>
>>     git-rebase - Rebuild a branch on top of a different commit
>
> I would say "Replay history on top of a different commit" instead.
> "Rebuild" may be misleading (it's not "build" as in "compile & link"),
> and the rebased history does not technically have to be a branch.

I am fine if the description were "replay history and repoint the
branch tip to the result"; the fact that branch tip moves is an
important part of the semantics of the command.

Otherwise, you cannot cleanly capture why we have rebase and
cherry-pick (which can do ranges these days).

Re: Advice on edits to git-rebase man page

[Matthew Brett]

On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>
>>   NAME
>>        git-rebase - Forward-port local commits to the updated upstream head
>>
>> => Quite technical already.
>
> Very much true, and I would say the description is "technically
> correct" in the sense that "it is not wrong per-se".  There are a
> few points that this fails to state and some that this overspecifies.
>
>  - Rebase is about changing the base of an existing branch, but the
>    description does not even mention the word "branch" [*1*].
>
>  - There is nothing "forward" about it.  I often see myself applying
>    (tentatively) incoming patches on top of whatever commit I happen
>    to have checked out, review it and then rebasing it to apply to
>    older maintenance track if the topic is about fixing an old bug.
>
>  - There is no point stressing "local" commits; all the operations
>    you do to munge commits are local.
>
> Perhaps something like this instead?
>
>     git-rebase - Rebuild a branch on top of a different commit
>
>
>>   DESCRIPTION
>>        If <branch> is specified, git rebase will perform an automatic
>>        git checkout <branch> before doing anything else. Otherwise it
>>        remains on the current branch.
>>
>> => Ouch, do we really want to start a documentation like this?
>
> No.  We should say what the command does and what the command is for
> in more general terms first and then describe how arguments can be
> used to affect it.
>
>> So, the DESCRIPTION part can definitely be improved IMHO. Your notation
>> <graft-point>, <exclude-from> and <include-from> may be an improvement
>> already.
>
> <graft-point>, <exclude-from> and <include-from> aren't technically
> wrong per-se, but I do not think bulk-replacing the words currently
> used in the manual page with these is an improvement at all, unless
> the mental picture the explanation draws is also updated to match
> these new words.
>
> reBASE is about changing the base of the affected branch, and the
> mental picture the current documentation draws is "there is a plant,
> from which you cut a branch, scion. Then you graft the scion onto
> understock".  It calls the original tree (that the branch being
> transplanted is part of) the "old-base", and the understock (that
> the scion is going to be grafted onto) the "new-base".  The word
> "graft" in "graft point" may better convey that we are doing a
> transplanting than the current wording, but the word "point" makes
> it unclear to the readers if it refers to the "point" where the
> scion was cut from or where it is going to transplanted to, I am
> afraid.

Thanks for the detailed feedback, sorry to be slow to reply.

For 'graft-point' - I agree that it is not immediately clear whether
this is the start of the commits that will be moved or the place that
they will be moved to.  <newbase> and <oldbase> are really not too bad
in the current docs.  After all, the command is called reBASE.  On the
other hand, the term 'graft' gives the impression of moving part of a
tree from one origin (base) to another, which I think is correct,
whereas the 'base' terminology doesn't allow an obvious name for the
'shoot' or 'scion'.  For example, I don't think there is such a term
in the current docs, other than 'set of commits'.

> Also <exclude-from> and <include-from> is probably too operational,
> and describing the command with only these two words would miss the
> point that the command is about transplanting a branch.  It is true
> that in order to transplant a branch, you first need to figure out
> the set of commits whose effects are to be replayed, you would need
> <exclude-from>..<include-from> range computation, but it is an
> lower-level implemention detail.

First - the current docs have <upstream> for <exclude-from> and
<branch> for <include-from>.  I find both of these confusing and hard
to read:

* upstream - it isn't part of the semantics of rebase that the exclude
point should be something "upstream", that is only one of the common
uses.  I think this is related to the point you made about "forward"
in the one-line description.
* branch - too generic - does not convey the point that this is the
included end point of the selected history.

Second - I don't understand why the actual use of <upstream> and
<branch> for selecting commits is a lower-level implementation detail.
Is there some higher-level explanation for how these parameters select
revisions?

Thanks,

Matthew

Re: Advice on edits to git-rebase man page

[Matthew Brett]

On Wed, Feb 18, 2015 at 10:59 AM, Matthew Brett <matthew.brett@gmail.com> wrote:
> On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>>
>>>   NAME
>>>        git-rebase - Forward-port local commits to the updated upstream head
>>>
>>> => Quite technical already.
>>
>> Very much true, and I would say the description is "technically
>> correct" in the sense that "it is not wrong per-se".  There are a
>> few points that this fails to state and some that this overspecifies.
>>
>>  - Rebase is about changing the base of an existing branch, but the
>>    description does not even mention the word "branch" [*1*].
>>
>>  - There is nothing "forward" about it.  I often see myself applying
>>    (tentatively) incoming patches on top of whatever commit I happen
>>    to have checked out, review it and then rebasing it to apply to
>>    older maintenance track if the topic is about fixing an old bug.
>>
>>  - There is no point stressing "local" commits; all the operations
>>    you do to munge commits are local.
>>
>> Perhaps something like this instead?
>>
>>     git-rebase - Rebuild a branch on top of a different commit
>>
>>
>>>   DESCRIPTION
>>>        If <branch> is specified, git rebase will perform an automatic
>>>        git checkout <branch> before doing anything else. Otherwise it
>>>        remains on the current branch.
>>>
>>> => Ouch, do we really want to start a documentation like this?
>>
>> No.  We should say what the command does and what the command is for
>> in more general terms first and then describe how arguments can be
>> used to affect it.
>>
>>> So, the DESCRIPTION part can definitely be improved IMHO. Your notation
>>> <graft-point>, <exclude-from> and <include-from> may be an improvement
>>> already.
>>
>> <graft-point>, <exclude-from> and <include-from> aren't technically
>> wrong per-se, but I do not think bulk-replacing the words currently
>> used in the manual page with these is an improvement at all, unless
>> the mental picture the explanation draws is also updated to match
>> these new words.
>>
>> reBASE is about changing the base of the affected branch, and the
>> mental picture the current documentation draws is "there is a plant,
>> from which you cut a branch, scion. Then you graft the scion onto
>> understock".  It calls the original tree (that the branch being
>> transplanted is part of) the "old-base", and the understock (that
>> the scion is going to be grafted onto) the "new-base".  The word
>> "graft" in "graft point" may better convey that we are doing a
>> transplanting than the current wording, but the word "point" makes
>> it unclear to the readers if it refers to the "point" where the
>> scion was cut from or where it is going to transplanted to, I am
>> afraid.
>
> Thanks for the detailed feedback, sorry to be slow to reply.
>
> For 'graft-point' - I agree that it is not immediately clear whether
> this is the start of the commits that will be moved or the place that
> they will be moved to.  <newbase> and <oldbase> are really not too bad
> in the current docs.  After all, the command is called reBASE.  On the
> other hand, the term 'graft' gives the impression of moving part of a
> tree from one origin (base) to another, which I think is correct,
> whereas the 'base' terminology doesn't allow an obvious name for the
> 'shoot' or 'scion'.  For example, I don't think there is such a term
> in the current docs, other than 'set of commits'.
>
>> Also <exclude-from> and <include-from> is probably too operational,
>> and describing the command with only these two words would miss the
>> point that the command is about transplanting a branch.  It is true
>> that in order to transplant a branch, you first need to figure out
>> the set of commits whose effects are to be replayed, you would need
>> <exclude-from>..<include-from> range computation, but it is an
>> lower-level implemention detail.
>
> First - the current docs have <upstream> for <exclude-from> and
> <branch> for <include-from>.  I find both of these confusing and hard
> to read:
>
> * upstream - it isn't part of the semantics of rebase that the exclude
> point should be something "upstream", that is only one of the common
> uses.  I think this is related to the point you made about "forward"
> in the one-line description.
> * branch - too generic - does not convey the point that this is the
> included end point of the selected history.
>
> Second - I don't understand why the actual use of <upstream> and
> <branch> for selecting commits is a lower-level implementation detail.
> Is there some higher-level explanation for how these parameters select
> revisions?

Perhaps this email was not well-directed, or there is not much
appetite for a git-rebase rewrite at the moment.  In any case, I'll
unsubscribe for now, but if you think I can help, please do email me.

Cheers,

Matthew