@matheusbsbs / matheus-bagliano / commits / 6c26bf4d4e

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 <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>

W. Trevor King committed Feb 19, 2013 at 05:05 UTC 6c26bf4d4e4b1f40dcd067f8ce0c76f64eab9f47

1 file changed +69 -46

Documentation/user-manual.txt

+69 -46

@@ -2556,6 +2556,12 @@ return mywork to the state it had before you started the rebase:

2556 $ git rebase --abort

2557 -------------------------------------------------

2558

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 +

2565 [[rewriting-one-commit]]

2566 Rewriting a single commit

2567 -------------------------

@@ -2569,72 +2575,89 @@ $ git commit --amend

2575

2576 which will replace the old commit by a new commit incorporating your

2577 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.

2580

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>>.

2583

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 +-------------------------------------------

2587

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:

2591

2592 -------------------------------------------------

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

2595 -------------------------------------------------

2596

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]:

2599

2600 -------------------------------------------------

2600 -$ git tag -d bad

2601 +$ git am *.patch

2602 -------------------------------------------------

2603

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 +-------------------------

2607

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.

2611

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:

2614

2615 -------------------------------------------------

2617 -$ git checkout -b mywork-new origin

2618 -$ gitk origin..mywork &

2616 +$ git rebase -i HEAD~5

2617 -------------------------------------------------

2618

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.

2621

2622 -------------------------------------------------

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 +...

2626

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].

2661

2662 [[patch-series-tools]]

2663 Other tools