From: "W. Trevor King" <wking@tremily.us>
To: Git <git@vger.kernel.org>
Cc: Junio C Hamano <gitster@pobox.com>,
Jonathan Nieder <jrnieder@gmail.com>,
"W. Trevor King" <wking@tremily.us>
Subject: [PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i'
Date: Tue, 19 Feb 2013 05:05:00 -0500 [thread overview]
Message-ID: <e9f8a25c05f9cfe89c6bcbefb69f40cd629f9925.1361267945.git.wking@tremily.us> (raw)
In-Reply-To: <cover.1361267945.git.wking@tremily.us>
In-Reply-To: <cover.1361267945.git.wking@tremily.us>
From: "W. Trevor King" <wking@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 <wking@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 use `git format-patch` to create a series of
-patches, then reset the state to before the patches:
+This will open your editor with a list of steps to be taken to perform
+your rebase.
-------------------------------------------------
-$ git format-patch origin
-$ git reset --hard origin
--------------------------------------------------
+pick deadbee The oneline of this commit
+pick fa1afe1 The oneline of the next commit
+...
-Then modify, reorder, or eliminate patches as preferred before applying
-them again with linkgit:git-am[1].
+# Rebase c0ffeee..deadbee onto c0ffeee
+#
+# Commands:
+# p, pick = use commit
+# r, reword = use commit, but edit the commit message
+# e, edit = use commit, but stop for amending
+# s, squash = use commit, but meld into previous commit
+# f, fixup = like "squash", but discard this commit's log message
+# x, exec = run command (the rest of the line) using shell
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+# 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 where `pick` has been replaced with `edit` or
+when a step in the list fails to mechanically resolve conflicts and
+needs your help. When you are done editing and/or resolving conflicts
+you can continue with `git rebase --continue`. If you decide that
+things are getting too hairy, you can always bail out with `git rebase
+--abort`. Even after the rebase is complete, you can still recover
+the original branch by using the <<reflogs,reflog>>.
+
+For a more detailed discussion of the procedure and additional tips,
+see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
[[patch-series-tools]]
Other tools
--
1.8.1.336.g94702dd
next prev parent reply other threads:[~2013-02-19 10:05 UTC|newest]
Thread overview: 97+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-02-08 16:43 [PATCH] user-manual: Rewrite git-gc section for automatic packing W. Trevor King
2013-02-08 17:36 ` Junio C Hamano
2013-02-08 18:35 ` W. Trevor King
2013-02-08 23:04 ` Junio C Hamano
2013-02-08 23:04 ` Junio C Hamano
2013-02-10 15:10 ` [PATCH v2 00/15] User manual updates W. Trevor King
2013-02-10 15:10 ` [PATCH v2 01/15] user-manual: Rewrite git-gc section for automatic packing W. Trevor King
2013-02-10 15:10 ` [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse W. Trevor King
2013-02-10 21:24 ` Junio C Hamano
2013-02-10 21:46 ` W. Trevor King
2013-02-10 22:36 ` Junio C Hamano
2013-02-14 18:57 ` Junio C Hamano
2013-02-17 17:06 ` W. Trevor King
2013-02-18 0:15 ` [PATCH v3 0/9] User manual updates W. Trevor King
2013-02-18 0:15 ` [PATCH v3 1/9] user-manual: Use 'remote add' to setup push URLs W. Trevor King
2013-02-18 1:58 ` Junio C Hamano
2013-02-18 2:15 ` Jonathan Nieder
2013-02-18 0:15 ` [PATCH v3 2/9] user-manual: Reorganize the reroll sections, adding 'git rebase -i' W. Trevor King
2013-02-18 2:23 ` Junio C Hamano
2013-02-18 2:39 ` W. Trevor King
2013-02-18 3:48 ` Junio C Hamano
2013-02-18 0:15 ` [PATCH v3 3/9] user-manual: Give 'git push -f' as an alternative to +master W. Trevor King
2013-02-18 2:24 ` Junio C Hamano
2013-02-18 0:15 ` [PATCH v3 4/9] user-manual: Mention 'git remote add' for remote branch config W. Trevor King
2013-02-18 2:26 ` Junio C Hamano
2013-02-18 2:41 ` W. Trevor King
2013-02-18 0:15 ` [PATCH v3 5/9] user-manual: Standardize backtick quoting W. Trevor King
2013-02-25 22:53 ` [PATCH v5] " W. Trevor King
2013-02-18 0:15 ` [PATCH v3 6/9] user-manual: Use 'git config --global user.*' for setup W. Trevor King
2013-02-18 2:47 ` Junio C Hamano
2013-02-18 12:12 ` W. Trevor King
2013-02-18 0:15 ` [PATCH v3 7/9] user-manual: Use request-pull to generate "please pull" text W. Trevor King
2013-02-18 2:50 ` Junio C Hamano
2013-02-18 0:16 ` [PATCH v3 8/9] user-manual: Flesh out uncommitted changes and submodule updates W. Trevor King
2013-02-18 2:53 ` Junio C Hamano
2013-02-19 9:35 ` W. Trevor King
2013-02-18 0:16 ` [PATCH v3 9/9] user-manual: Use -o latest.tar.gz to create a gzipped tarball W. Trevor King
2013-02-18 2:58 ` Junio C Hamano
2013-02-18 12:16 ` W. Trevor King
2013-02-18 8:56 ` [PATCH v3 0/9] User manual updates Junio C Hamano
2013-02-18 12:27 ` W. Trevor King
2013-02-18 13:00 ` [PATCH v2 02/15] user-manual: Update for receive.denyCurrentBranch=refuse Drew Northup
2013-02-18 21:26 ` Junio C Hamano
2013-02-10 15:10 ` [PATCH v2 03/15] user-manual: Use 'remote add' to setup push URLs W. Trevor King
2013-02-10 21:33 ` Junio C Hamano
2013-02-10 21:54 ` W. Trevor King
2013-02-10 22:08 ` Jonathan Nieder
2013-02-10 22:19 ` W. Trevor King
2013-02-10 22:45 ` Junio C Hamano
2013-02-10 22:57 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 04/15] user-manual: Use git branch --merged W. Trevor King
2013-02-10 21:37 ` Junio C Hamano
2013-02-10 21:56 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 05/15] user-manual: Add a few references to 'git rebase -i' W. Trevor King
2013-02-10 21:53 ` Junio C Hamano
2013-02-10 22:00 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 06/15] user-manual: Give 'git push -f' as an alternative to +master W. Trevor King
2013-02-10 22:00 ` Junio C Hamano
2013-02-10 22:04 ` W. Trevor King
2013-02-10 23:19 ` Junio C Hamano
2013-02-10 15:10 ` [PATCH v2 07/15] user-manual: Mention 'git remote add' for remote branch config W. Trevor King
2013-02-10 22:08 ` Junio C Hamano
2013-02-10 22:09 ` Junio C Hamano
2013-02-10 22:22 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 08/15] user-manual: Standardize backtick quoting W. Trevor King
2013-02-10 15:22 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 09/15] user-manual: Use 'git config --global user.*' for setup W. Trevor King
2013-02-10 22:12 ` Junio C Hamano
2013-02-10 22:25 ` W. Trevor King
2013-02-10 22:48 ` Junio C Hamano
2013-02-10 22:52 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 10/15] user-manual: Fix 'both: so' -> 'both; so' typo W. Trevor King
2013-02-10 15:10 ` [PATCH v2 11/15] user-manual: Fix 'http' -> 'HTTP' typos W. Trevor King
2013-02-10 15:10 ` [PATCH v2 12/15] user-manual: Use request-pull to generate "please pull" text W. Trevor King
2013-02-10 22:23 ` Junio C Hamano
2013-02-10 22:29 ` W. Trevor King
2013-02-10 15:10 ` [PATCH v2 13/15] user-manual: Fix 'you - Git' -> 'you--Git' typo W. Trevor King
2013-02-10 15:10 ` [PATCH v2 14/15] user-manual: Flesh out uncommitted changes and submodule updates W. Trevor King
2013-02-10 15:10 ` [PATCH v2 15/15] user-manual: Use --format=tar.gz to create a gzipped tarball W. Trevor King
2013-02-10 22:27 ` Junio C Hamano
2013-02-10 22:32 ` W. Trevor King
2013-02-10 22:52 ` Junio C Hamano
2013-02-10 23:01 ` W. Trevor King
2013-02-10 22:31 ` [PATCH v2 00/15] User manual updates Junio C Hamano
2013-02-10 22:36 ` W. Trevor King
2013-02-19 9:34 ` [PATCH v3 0/9] " W. Trevor King
2013-02-19 10:04 ` [PATCH v4 0/3] " W. Trevor King
2013-02-19 10:05 ` W. Trevor King [this message]
2013-02-19 18:47 ` [PATCH v4 1/3] user-manual: Reorganize the reroll sections, adding 'git rebase -i' Junio C Hamano
2013-02-19 18:51 ` W. Trevor King
2013-02-19 20:56 ` Junio C Hamano
2013-03-24 12:23 ` [PATCH] user-manual: Fix the interactive rebase example commit range W. Trevor King
2013-03-24 20:00 ` Eric Sunshine
2013-03-24 20:22 ` W. Trevor King
2013-02-19 10:05 ` [PATCH v4 2/3] user-manual: Use request-pull to generate "please pull" text W. Trevor King
2013-02-19 10:05 ` [PATCH v4 3/3] user-manual: Flesh out uncommitted changes and submodule updates W. Trevor King
2013-02-09 1:13 ` [PATCH] user-manual: Rewrite git-gc section for automatic packing Javier Tia
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=e9f8a25c05f9cfe89c6bcbefb69f40cd629f9925.1361267945.git.wking@tremily.us \
--to=wking@tremily.us \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).