Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 20, 2013, 22:29 UTC
- Message-ID
- <7vwqqtthe6.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <2F59222ECBA14673815BF42E6A7CE5A5@PhilipOakley>
"Philip Oakley" <philipoakley@iee.org> writes:
Show 20 quoted lines
> From: "Junio C Hamano" <gitster@pobox.com> > Sent: Monday, May 20, 2013 5:43 AM >> Jonathan Nieder <jrnieder@gmail.com> writes: >> >>> Philip Oakley wrote: >>> >>>> Describe rebase in the description section. >>> >>> It already does that. :) I think you mean "start with a summary", >>> which is a valuable improvement. >> >> It indeed is a good idea to give the "high-level introduction" at >> the very beginning, but I do not think it should describe only one >> of the three major modes of "git rebase" (i.e. no -m, no -i), like >> the proposed patch text does. We should instead say what it is used >> for and why the user would want to use it that is common across >> these modes at a very high level. > > That would repeat the NAME issue (of trying too hard to be exact & > precise). This introductory text is that "summary".
If that is "summary", it should never talk about "skips merges", which only applies to the mode without -m, no?
The highest level view of what the command is for (the motivation why the user would want to consider learning how to use the command) is "You have a history built on top of some commit, and you want to rebuild the history on top of another commit, e.g. you earlier built on the tip of a branch that has some other work, and you want to rebuild the history on top of the updated tip of that other branch".
The details of how the history is "rebuilt" can differ while using various modes of operation. Some may skip merges, some may try to preserve the topology, some may even let you insert new commits by letting you tell it to stop in the middle. That is not "summary" but is part of mode specific description.