Skip to content

Commit 6c26bf4

Browse files
wkinggitster
authored andcommitted
user-manual: Reorganize the reroll sections, adding 'git rebase -i'
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 <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent 7ed1690 commit 6c26bf4

File tree

1 file changed

+69
-46
lines changed

1 file changed

+69
-46
lines changed

Documentation/user-manual.txt

Lines changed: 69 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2556,6 +2556,12 @@ return mywork to the state it had before you started the rebase:
25562556
$ git rebase --abort
25572557
-------------------------------------------------
25582558

2559+
If you need to reorder or edit a number of commits in a branch, it may
2560+
be easier to use `git rebase -i`, which allows you to reorder and
2561+
squash commits, as well as marking them for individual editing during
2562+
the rebase. See <<interactive-rebase>> for details, and
2563+
<<reordering-patch-series>> for alternatives.
2564+
25592565
[[rewriting-one-commit]]
25602566
Rewriting a single commit
25612567
-------------------------
@@ -2569,72 +2575,89 @@ $ git commit --amend
25692575

25702576
which will replace the old commit by a new commit incorporating your
25712577
changes, giving you a chance to edit the old commit message first.
2578+
This is useful for fixing typos in your last commit, or for adjusting
2579+
the patch contents of a poorly staged commit.
25722580

2573-
You can also use a combination of this and linkgit:git-rebase[1] to
2574-
replace a commit further back in your history and recreate the
2575-
intervening changes on top of it. First, tag the problematic commit
2576-
with
2577-
2578-
-------------------------------------------------
2579-
$ git tag bad mywork~5
2580-
-------------------------------------------------
2581+
If you need to amend commits from deeper in your history, you can
2582+
use <<interactive-rebase,interactive rebase's `edit` instruction>>.
25812583

2582-
(Either gitk or `git log` may be useful for finding the commit.)
2584+
[[reordering-patch-series]]
2585+
Reordering or selecting from a patch series
2586+
-------------------------------------------
25832587

2584-
Then check out that commit, edit it, and rebase the rest of the series
2585-
on top of it (note that we could check out the commit on a temporary
2586-
branch, but instead we're using a <<detached-head,detached head>>):
2588+
Sometimes you want to edit a commit deeper in your history. One
2589+
approach is to use `git format-patch` to create a series of patches
2590+
and then reset the state to before the patches:
25872591

25882592
-------------------------------------------------
2589-
$ git checkout bad
2590-
$ # make changes here and update the index
2591-
$ git commit --amend
2592-
$ git rebase --onto HEAD bad mywork
2593+
$ git format-patch origin
2594+
$ git reset --hard origin
25932595
-------------------------------------------------
25942596

2595-
When you're done, you'll be left with mywork checked out, with the top
2596-
patches on mywork reapplied on top of your modified commit. You can
2597-
then clean up with
2597+
Then modify, reorder, or eliminate patches as needed before applying
2598+
them again with linkgit:git-am[1]:
25982599

25992600
-------------------------------------------------
2600-
$ git tag -d bad
2601+
$ git am *.patch
26012602
-------------------------------------------------
26022603

2603-
Note that the immutable nature of git history means that you haven't really
2604-
"modified" existing commits; instead, you have replaced the old commits with
2605-
new commits having new object names.
2604+
[[interactive-rebase]]
2605+
Using interactive rebases
2606+
-------------------------
26062607

2607-
[[reordering-patch-series]]
2608-
Reordering or selecting from a patch series
2609-
-------------------------------------------
2608+
You can also edit a patch series with an interactive rebase. This is
2609+
the same as <<reordering-patch-series,reordering a patch series using
2610+
`format-patch`>>, so use whichever interface you like best.
26102611

2611-
Given one existing commit, the linkgit:git-cherry-pick[1] command
2612-
allows you to apply the change introduced by that commit and create a
2613-
new commit that records it. So, for example, if "mywork" points to a
2614-
series of patches on top of "origin", you might do something like:
2612+
Rebase your current HEAD on the last commit you want to retain as-is.
2613+
For example, if you want to reorder the last 5 commits, use:
26152614

26162615
-------------------------------------------------
2617-
$ git checkout -b mywork-new origin
2618-
$ gitk origin..mywork &
2616+
$ git rebase -i HEAD~5
26192617
-------------------------------------------------
26202618

2621-
and browse through the list of patches in the mywork branch using gitk,
2622-
applying them (possibly in a different order) to mywork-new using
2623-
cherry-pick, and possibly modifying them as you go using `git commit --amend`.
2624-
The linkgit:git-gui[1] command may also help as it allows you to
2625-
individually select diff hunks for inclusion in the index (by
2626-
right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
2627-
2628-
Another technique is to use `git format-patch` to create a series of
2629-
patches, then reset the state to before the patches:
2619+
This will open your editor with a list of steps to be taken to perform
2620+
your rebase.
26302621

26312622
-------------------------------------------------
2632-
$ git format-patch origin
2633-
$ git reset --hard origin
2634-
-------------------------------------------------
2623+
pick deadbee The oneline of this commit
2624+
pick fa1afe1 The oneline of the next commit
2625+
...
26352626

2636-
Then modify, reorder, or eliminate patches as preferred before applying
2637-
them again with linkgit:git-am[1].
2627+
# Rebase c0ffeee..deadbee onto c0ffeee
2628+
#
2629+
# Commands:
2630+
# p, pick = use commit
2631+
# r, reword = use commit, but edit the commit message
2632+
# e, edit = use commit, but stop for amending
2633+
# s, squash = use commit, but meld into previous commit
2634+
# f, fixup = like "squash", but discard this commit's log message
2635+
# x, exec = run command (the rest of the line) using shell
2636+
#
2637+
# These lines can be re-ordered; they are executed from top to bottom.
2638+
#
2639+
# If you remove a line here THAT COMMIT WILL BE LOST.
2640+
#
2641+
# However, if you remove everything, the rebase will be aborted.
2642+
#
2643+
# Note that empty commits are commented out
2644+
-------------------------------------------------
2645+
2646+
As explained in the comments, you can reorder commits, squash them
2647+
together, edit commit messages, etc. by editing the list. Once you
2648+
are satisfied, save the list and close your editor, and the rebase
2649+
will begin.
2650+
2651+
The rebase will stop where `pick` has been replaced with `edit` or
2652+
when a step in the list fails to mechanically resolve conflicts and
2653+
needs your help. When you are done editing and/or resolving conflicts
2654+
you can continue with `git rebase --continue`. If you decide that
2655+
things are getting too hairy, you can always bail out with `git rebase
2656+
--abort`. Even after the rebase is complete, you can still recover
2657+
the original branch by using the <<reflogs,reflog>>.
2658+
2659+
For a more detailed discussion of the procedure and additional tips,
2660+
see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
26382661

26392662
[[patch-series-tools]]
26402663
Other tools

0 commit comments

Comments
 (0)