On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Matthieu Moy <Matthieu.Moy@xxxxxxxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html