[PATCH] reset: add an example of how to split a commit into two

[Jacob Keller <jacob.e.keller@intel.com>]

From: Jacob Keller <jacob.keller@gmail.com>

It is sometimes useful to break a commit into parts to more logically
show how the code changes. There are many possible ways to achieve this
result, but one simple and powerful one is to use git reset -p.

Add an example to the documentation showing how this can be done so that
users are more likely to discover this, instead of inventing more
painful methods such as re-writing code from scratch, or duplicating git
add -p more times than necessary.

Signed-off-by: Jacob Keller <jacob.keller@gmail.com>
---
 Documentation/git-reset.txt | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 25432d9257f9..4adac7a25bf9 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -292,6 +292,29 @@ $ git reset --keep start                    <3>
 <3> But you can use "reset --keep" to remove the unwanted commit after
     you switched to "branch2".
 
+Split a commit into two::
++
+Suppose that you have created a commit, but later decide that you want to split
+the changes into two separate commits, including only part of the old commit
+into the first commit, and including the rest as a separate commit on top. You
+can use git reset in patch mode to interactively select which hunks to split
+out into a separate commit.
++
+------------
+$ git reset -p HEAD^                        <1>
+$ git commit --amend                        <2>
+$ git commit ...                            <3>
+------------
++
+<1> This lets you interactively undo changes between HEAD^ and HEAD, so you can
+    select which parts to remove from the initial commit. The changes are
+    placed into the index, leaving the working tree untouched.
+<2> Now, you ammend the initial commit with the modifications that you just
+    made in the index.
+<3> Finally, you can add and then commit the final original unmodified files
+    back as the second commit, enabling you to logically separate a commit
+    into a sequence of two commits instead.
+
 
 DISCUSSION
 ----------
-- 
2.11.0.864.ge7592a54611d