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

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

[Jacob Keller]

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

It is often useful to break a commit into multiple parts that are more
logical separations. This can be tricky to learn how to do without the
brute-force method if re-writing code or commit messages from scratch.

Add a section to the git-reset documentation which shows an example
process for how to use git add -p and git commit -c HEAD@{1} to
interactively break a commit apart and re-use the original commit
message as a starting point when making the new commit message.

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

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 25432d9257f9..add6220fce77 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -292,6 +292,44 @@ $ 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 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.
++
+------------
+$ git reset 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>
+------------
++
+<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.
+
 
 DISCUSSION
 ----------
-- 
2.11.0.864.ge7592a54611d

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

[Junio C Hamano]

Jacob Keller <jacob.e.keller@intel.com> writes:

> +Split a commit into two::

Let's say "...into two (or more)" to match what appears in
"SPLITTING COMMITS" section of "rebase -i" documentation.  Yours is
written as a sequence of more concrete steps than the existing one
over there, so it may also make sense to add reference to bring
readers of "git rebase --help" to this section.

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

"two (or more)" again.  In <5> you already hint that the user can
repeat 2-4 number of times.

> +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.
> ++
> +------------
> +$ git reset 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>
> +------------
> ++
> +<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.
> +

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

[Duy Nguyen]

On Sat, Feb 4, 2017 at 3:28 AM, Jacob Keller <jacob.e.keller@intel.com> wrote:
> +------------
> +$ git reset HEAD^                           <1>

It may be a good idea to add -N here, so that 'add -p' can pick up the
new files if they are added in HEAD.

> +$ git add -p                                <2>
-- 
Duy

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

[Philip Oakley]

From: "Duy Nguyen" <pclouds@gmail.com>
> On Sat, Feb 4, 2017 at 3:28 AM, Jacob Keller <jacob.e.keller@intel.com> 
> wrote:
>> +------------
>> +$ git reset HEAD^                           <1>
>
> It may be a good idea to add -N here, so that 'add -p' can pick up the
> new files if they are added in HEAD.

When looking at the man page for `reset` [1] it implies that `-N` requires 
`--mixed` also to be given. Is that correct? Or could the man page be 
clearer?

>
>> +$ git add -p                                <2>
> -- 
> Duy
>
Philip
[1] https://git-scm.com/docs/git-reset 

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

[Duy Nguyen]

On Sat, Feb 4, 2017 at 7:16 PM, Philip Oakley <philipoakley@iee.org> wrote:
> From: "Duy Nguyen" <pclouds@gmail.com>
>>
>> On Sat, Feb 4, 2017 at 3:28 AM, Jacob Keller <jacob.e.keller@intel.com>
>> wrote:
>>>
>>> +------------
>>> +$ git reset HEAD^                           <1>
>>
>>
>> It may be a good idea to add -N here, so that 'add -p' can pick up the
>> new files if they are added in HEAD.
>
>
> When looking at the man page for `reset` [1] it implies that `-N` requires
> `--mixed` also to be given. Is that correct?

Yes. But since --mixed is the default mode, "reset -N" equals "reset --mixed -N"

> Or could the man page be clearer?

If someone makes questions, I guess the answer is yes it should be made clearer.
-- 
Duy