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
