Re: Advice on edits to git-rebase man page
On Wed, Feb 18, 2015 at 10:59 AM, Matthew Brett wrote: > On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano wrote: >> Matthieu Moy 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 is specified, git rebase will perform an automatic >>>git checkout 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 >>> , and may be an improvement >>> already. >> >> , and 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. and 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 and 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 >> .. range computation, but it is an >> lower-level implemention detail. > > First - the current docs have for and > for . 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 and > 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Advice on edits to git-rebase man page
On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano wrote: > Matthieu Moy 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 is specified, git rebase will perform an automatic >>git checkout 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 >> , and may be an improvement >> already. > > , and 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. and 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 and 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 > .. range computation, but it is an > lower-level implemention detail. First - the current docs have for and for . 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 and for selecting commits is a lower-level implementation detail. Is there some higher-level explanation for how these parameters select revisions? Thanks, Matthew -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Advice on edits to git-rebase man page
Matthieu Moy writes: > Junio C Hamano 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). -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Advice on edits to git-rebase man page
Junio C Hamano 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/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Advice on edits to git-rebase man page
Matthieu Moy 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 is specified, git rebase will perform an automatic >git checkout 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 > , and may be an improvement > already. , and 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 and 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 .. 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Advice on edits to git-rebase man page
Matthew Brett 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 is specified, git rebase will perform an automatic git checkout 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 , and 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/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html