"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
route.
> +[[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
