Re: [PATCH] docs: Clarify what git-rebase's "--preserve-merges" does
- From
Sebastian Schuberth <sschuberth@gmail.com>
- Date
- Mar 30, 2015, 09:29 UTC
- Message-ID
- <5519178A.6080408@gmail.com>
- In-Reply-To
- <xmqqd23vzkon.fsf@gitster.dls.corp.google.com>
On 3/26/2015 19:18, Junio C Hamano wrote:
> Although I fully agree that the new text is better than the original, > I think the new text fails to point out one major aspect by not > mentioning "linear" or "flatten" anywhere. The point of "git rebase" > without "-p" is not just to replay but to flatten
I think it's a bit odd to say that "-p" does not flatten if the whole current rebase docs do not use the terms flattening / linearize at all. If we say that that "-p" does not flatten, we should say that a "standard" rebase wihtout "-p" does. I plan to send a patch for that later.
> Instead of flattening the history by replaying each > non-merge commit to be rebased, preserve the shape of the > rebased history by recreating merge commits as well.
Personally, I like "positive logic" better here, i.e. start with saying what the option does, not what it does not do.
So how about:
[PATCH] docs: Clarify what git-rebase's "-p" / "--preserve-merges" does
Ignoring a merge sounds like ignoring the changes a merge commit introduces altogether, as if the merge commit was skipped or dropped from history. But that is not what happens if "-p" is not specified.
Instead, what happens is that the individual commits a merge commit introduces are replayed in order, and only any possible merge conflict resolutions or manual amendments to the merge commit are ignored. Get this straight in the docs.
Also, do not say that merge commits are *tried* to be recreated. As that is true almost everywhere it is better left unsaid.
Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com> --- Documentation/git-rebase.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index d728030..47984e8 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -362,7 +362,9 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. -p:: --preserve-merges:: - Instead of ignoring merges, try to recreate them. + Recreate merge commits instead of flattening the history by replaying + commits a merge commit introduces. Merge conflict resolutions or manual + amendments to merge commits are not preserved. + This uses the `--interactive` machinery internally, but combining it with the `--interactive` option explicitly is generally not a good
-- 1.9.5.msysgit.1