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 | 115 +-
1 file changed, 69 insertions(+), 46 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 52c8523..a4dbd9e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2556,6 +2556,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
-
@@ -2569,72 +2575,89 @@ $ 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.
+This is useful for fixing typos in your last commit, or for adjusting
+the patch contents of a poorly staged commit.
-You can also use a combination of this and linkgit:git-rebase[1] to
-replace a commit further back in your history and recreate the
-intervening changes on top of it. First, tag the problematic commit
-with
-
--
-$ git tag bad mywork~5
--
+If you need to amend commits from deeper in your history, you should
+use interactive-rebase,interactive rebase's `edit` instruction.
-(Either gitk or `git log` may be useful for finding the commit.)
+[[reordering-patch-series]]
+Reordering or selecting from a patch series
+---
-Then check out that commit, edit it, and rebase the rest of the series
-on top of it (note that we could check out the commit on a temporary
-branch, but instead we're using a detached-head,detached head):
+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 checkout bad
-$ # make changes here and update the index
-$ git commit --amend
-$ git rebase --onto HEAD bad mywork
+$ git format-patch origin
+$ git reset --hard origin
-
-When you're done, you'll be left with mywork checked out, with the top
-patches on mywork reapplied on top of your modified commit. You can
-then clean up with
+Then modify, reorder, or eliminate patches as needed before applying
+them again with linkgit:git-am[1]:
-
-$ git tag -d bad
+$ git am *.patch
-
-Note that the immutable nature of git history means that you haven't really
-modified existing commits; instead, you have replaced the old commits with
-new commits having new object names.
+[[interactive-rebase]]
+Using interactive rebases
+-
-[[reordering-patch-series]]
-Reordering or selecting from a patch series
+You can also edit a patch series with an interactive rebase. This is
+the same as reordering-patch-series,reordering a patch series using
+`format-patch`, so use whichever interface you like best.
-Given one existing commit, the linkgit:git-cherry-pick[1] command
-allows you to apply the change introduced by that commit and create a
-new commit that records it. So, for example, if mywork points to a
-series of patches on top of origin, you might do something like:
+Rebase your current HEAD on the last commit you want to retain as-is.
+For example, if you want to reorder the last 5 commits, use:
-
-$ git checkout -b mywork-new origin
-$ gitk origin..mywork
+$ git rebase -i HEAD~5
-
-and browse through the list of patches in the mywork branch using gitk,
-applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `git commit --amend`.
-The linkgit:git-gui[1] command may also help as it allows you to
-individually select diff hunks for inclusion in the index (by
-right-clicking on the diff hunk and choosing Stage Hunk for Commit).
-
-Another technique is to
