Re: [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i'
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:56:10
"W. Trevor King" [off-list ref] writes:
quoted hunk
From: "W. Trevor King" <redacted> 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 <redacted> --- 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.