in these files are in good order. You do not want to see them
when you run "git diff", because you plan to work on other files
and changes with these files are distracting.
-<2> Somebody asks you to pull, and the changes sounds worthy of merging.
+<2> Somebody asks you to pull, and the changes sound worthy of merging.
<3> However, you already dirtied the index (i.e. your index does
not match the HEAD commit). But you know the pull you are going
to make does not affect frotz.c or filfre.c, so you revert the
<3> But you can use "reset --keep" to remove the unwanted commit after
you switched to "branch2".
-Split a commit into two::
+Split a commit apart into a sequence of commits::
+
-Suppose that you have created a commit, but later decide that you want to break
-apart the changes into two logical chunks and commit each separately. You want
-to include part of the original commit into the first commit, while including
-the remainder in a second commit. You can use git reset to rewind the history
-without changing the index, and then use git add -p to interactively select
-which hunks to put into the first commit.
+Suppose that you have created lots of logically separate changes and committed
+them together. Then, later you decide that it might be better to have each
+logical chunk associated with its own commit. You can use git reset to rewind
+history without changing the contents of your local files, and then successively
+use `git add -p` to interactively select which hunks to include into each commit,
+using `git commit -c` to pre-populate the commit message.
+
------------
-$ git reset HEAD^ <1>
+$ git reset -N HEAD^ <1>
$ git add -p <2>
$ git diff --cached <3>
$ git commit -c HEAD@{1} <4>
-...
-$ git add ... <5>
-$ git diff --cached <6>
-$ git commit ... <7>
+... <5>
+$ git add ... <6>
+$ git diff --cached <7>
+$ git commit ... <8>
------------
+
<1> First, reset the history back one commit so that we remove the original
- commit, but leave the working tree with all the changes.
-<2> Now, interactively select hunks to add to a new commit using git add -p.
- This will ask for each hunk separately and you can use simple commands like
- "yes, include", "no don't include" or even "edit".
-<3> Once satisfied with the hunks, you should verify that it is what you
- expected by using git diff --cached to show all changes in the index.
-<4> Next, commit the changes stored in the index. "-c" specifies to load the
- editor with a commit message from a previous commit so that you can re-use the
- original commit message. HEAD@{1} is special notation to reference what
- HEAD used to be prior to the reset command. See linkgit:git-reflog[1] for
- more details.
-<5> Now you've created the first commit, and can repeat steps 2-4 as often as
- you like to break the work into any number of commits. Here we show a second
- step which simply adds the remaining changes.
-<6> Then check again that the changes are what you expected to add.
-<7> And finally commit the remaining changes.
+ commit, but leave the working tree with all the changes. The -N ensures
+ that any new files added with HEAD are still marked so that git add -p
+ will find them.
+<2> Next, we interactively select diff hunks to add using the git add -p
+ facility. This will ask you about each diff hunk in sequence and you can
+ use simple commands such as "yes, include this", "No don't include this"
+ or even the very powerful "edit" facility.
+<3> Once satisfied with the hunks you want to include, you should verify what
+ has been prepared for the first commit by using git diff --cached. This
+ shows all the changes that have been moved into the index and are about
+ to be committed.
+<4> Next, commit the changes stored in the index. The -c option specifies to
+ pre-populate the commit message from the original message that you started
+ with in the first commit. This is helpful to avoid retyping it. The HEAD@{1}
+ is a special notation for the commit that HEAD used to be at prior to the
+ original reset commit (1 change ago). See linkgit:git-reflog[1] for more
+ details. You may also use any other valid commit reference.
+<5> You can repeat steps 2-4 multiple times to break the original code into
+ any number of commits.
+<6> Now you've split out many of the changes into their own commits, and might
+ no longer use the patch mode of git add, in order to select all remaining
+ uncommitted changes.
+<7> Once again, check to verify that you've included what you want to. You may
+ also wish to verify that git diff doesn't show any remaining changes to be
+ committed later.
+<8> And finally create the final commit.
DISCUSSION