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

> From: "W. Trevor King" <wk...@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 <wk...@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

> +[[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?

> +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.

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

Reply via email to