Re: [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 18, 2013, 02:23 UTC
Message-ID: <7v621qe4xc.fsf@alter.siamese.dyndns.org>
In-Reply-To: <31c45d95acaf062428f171c33c4c164d80b4becb.1361146398.git.wking@tremily.us>

"W. Trevor King" <wking@tremily.us> writes:

Show 40 quoted lines

> From: "W. Trevor King" <wking@tremily.us>
>
> I think this interface is often more convenient than extended cherry
> picking or using 'git format-patch'.  In fact, I removed the
> cherry-pick section entirely.  The entry-level suggestions for
> rerolling are now:
>
> 1. git commit --amend
> 2. git format-patch origin
>    git reset --hard origin
>    ...edit and reorder patches...
>    git am *.patch
> 3. git rebase -i origin
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 110 ++++++++++++++++++++++++------------------
>  1 file changed, 63 insertions(+), 47 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a060eb6..dbffd0a 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2538,6 +2538,12 @@ return mywork to the state it had before you started the rebase:
>  $ git rebase --abort
>  -------------------------------------------------
>  
> +If you need to reorder or edit a number of commits in a branch, it may
> +be easier to use `git rebase -i`, which allows you to reorder and
> +squash commits, as well as marking them for individual editing during
> +the rebase.  See <<interactive-rebase>> for details, and
> +<<reordering-patch-series>> for alternatives.
> +
>  [[rewriting-one-commit]]
>  Rewriting a single commit
>  -------------------------
> @@ -2552,71 +2558,81 @@ $ git commit --amend
>  which will replace the old commit by a new commit incorporating your
>  changes, giving you a chance to edit the old commit message first.
>

... A lot of lines removed here ...

> +[[reordering-patch-series]]

This change makes the [[rewriting-one-commit]] section say "We already saw you can do 'commit --amend'" and nothing else. It makes me wonder if the remaining section is worth keeping if we go this route.

Show 19 quoted lines

> +[[reordering-patch-series]]
> +Reordering or selecting from a patch series
> +-------------------------------------------
>  
> +Sometimes you want to edit a commit deeper in your history.  One
> +approach is to use `git format-patch` to create a series of patches,
> +then reset the state to before the patches:
>  
>  -------------------------------------------------
> +$ git format-patch origin
> +$ git reset --hard origin
>  -------------------------------------------------
>  
> +Then modify, reorder, or eliminate patches as preferred before applying
> +them again with linkgit:git-am[1]:
>  
>  -------------------------------------------------
> +$ git am *.patch
>  -------------------------------------------------

It may be just me, but s/preferred/needed/, perhaps?

Show 22 quoted lines

> +This will open your editor with a list of the commits you're rebasing
>  
>  -------------------------------------------------
> +pick deadbee The oneline of this commit
> +pick fa1afe1 The oneline of the next commit
> +...
>  
> +# Rebase c0ffeee..deadbee onto c0ffeee
> +#
> +# Commands:
> ...
> +# Note that empty commits are commented out
> +-------------------------------------------------
> +
> +As explained in the comments, you can reorder commits, squash them
> +together, edit commit messages, etc. by editing the list.  Once you
> +are satisfied, save the list and close your editor, and the rebase
> +will begin.
> +
> +The rebase will stop when `pick` has been replaced with `edit` or when
> +a command fails due to merge errors. When you are done editing and/or
> +resolving conflicts...

I am afraid that "due to merge errors" and "resolving conflicts" do not look corresponding to each other for a new reader. Also here we say "when a command fails", but the explanation before this part never says "list of commands". Besides, "command" itself is not a very good word to use as "pick" is not really a "command" (we do not have "git pick" or "git squash"---that is why I almost always call this "insn sheet" myself, by the way).

A way to reword the above to reduce possible confusion may be to start with:

	This will open your editor with a list of steps to be taken
        to perform your rebase.

and then say

	... with `edit` or when a step in the list fails to
	mechanically resolve conflicts and needs your help.  When
	you are done editing ...

or something.