* Advice on edits to git-rebase man page @ 2015-02-04 20:21 Matthew Brett 2015-02-05 10:44 ` Matthieu Moy 0 siblings, 1 reply; 7+ messages in thread From: Matthew Brett @ 2015-02-04 20:21 UTC (permalink / raw) To: Git Mailing List; +Cc: Reuben Thomas 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-04 20:21 Advice on edits to git-rebase man page Matthew Brett @ 2015-02-05 10:44 ` Matthieu Moy 2015-02-05 18:58 ` Junio C Hamano 0 siblings, 1 reply; 7+ messages in thread From: Matthieu Moy @ 2015-02-05 10:44 UTC (permalink / raw) To: Matthew Brett; +Cc: Git Mailing List, Reuben Thomas 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-05 10:44 ` Matthieu Moy @ 2015-02-05 18:58 ` Junio C Hamano 2015-02-05 21:20 ` Matthieu Moy 2015-02-18 18:59 ` Matthew Brett 0 siblings, 2 replies; 7+ messages in thread From: Junio C Hamano @ 2015-02-05 18:58 UTC (permalink / raw) To: Matthieu Moy; +Cc: Matthew Brett, Git Mailing List, Reuben Thomas 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-05 18:58 ` Junio C Hamano @ 2015-02-05 21:20 ` Matthieu Moy 2015-02-05 21:29 ` Junio C Hamano 2015-02-18 18:59 ` Matthew Brett 1 sibling, 1 reply; 7+ messages in thread From: Matthieu Moy @ 2015-02-05 21:20 UTC (permalink / raw) To: Junio C Hamano; +Cc: Matthew Brett, Git Mailing List, Reuben Thomas 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-05 21:20 ` Matthieu Moy @ 2015-02-05 21:29 ` Junio C Hamano 0 siblings, 0 replies; 7+ messages in thread From: Junio C Hamano @ 2015-02-05 21:29 UTC (permalink / raw) To: Matthieu Moy; +Cc: Matthew Brett, Git Mailing List, Reuben Thomas 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). ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-05 18:58 ` Junio C Hamano 2015-02-05 21:20 ` Matthieu Moy @ 2015-02-18 18:59 ` Matthew Brett 2015-02-23 18:24 ` Matthew Brett 1 sibling, 1 reply; 7+ messages in thread From: Matthew Brett @ 2015-02-18 18:59 UTC (permalink / raw) To: Junio C Hamano; +Cc: Matthieu Moy, Git Mailing List, Reuben Thomas 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Advice on edits to git-rebase man page 2015-02-18 18:59 ` Matthew Brett @ 2015-02-23 18:24 ` Matthew Brett 0 siblings, 0 replies; 7+ messages in thread From: Matthew Brett @ 2015-02-23 18:24 UTC (permalink / raw) To: Junio C Hamano; +Cc: Matthieu Moy, Git Mailing List, Reuben Thomas 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2015-02-23 18:25 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2015-02-04 20:21 Advice on edits to git-rebase man page Matthew Brett 2015-02-05 10:44 ` Matthieu Moy 2015-02-05 18:58 ` Junio C Hamano 2015-02-05 21:20 ` Matthieu Moy 2015-02-05 21:29 ` Junio C Hamano 2015-02-18 18:59 ` Matthew Brett 2015-02-23 18:24 ` Matthew Brett
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.