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

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

[Jacob Keller]

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

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

[Duy Nguyen]

On Fri, Feb 3, 2017 at 7:30 AM, Jacob Keller <jacob.e.keller@intel.com> wrote:
> 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>

For good practice, perhaps put "git diff --cached HEAD^" before "git commit".

I tend to avoid "reset -p" and "checkout -p" though because sometimes
it does not work. Not sure if it's just me, I think it may have
something to do with splitting hunks. So I usually go with "reset
HEAD^" then "add -p" and "commit -c HEAD@{1}" instead.

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

s/ammend/amend/

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

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

[Junio C Hamano]

Duy Nguyen <pclouds@gmail.com> writes:

>> +$ git reset -p HEAD^                        <1>
>
> For good practice, perhaps put "git diff --cached HEAD^" before "git commit".
>
> I tend to avoid "reset -p" and "checkout -p" though because sometimes
> it does not work. Not sure if it's just me, I think it may have
> something to do with splitting hunks. So I usually go with "reset
> HEAD^" then "add -p" and "commit -c HEAD@{1}" instead.

Perhaps I am superstitious, but I do that, too.  

Doing this that way, the users do not need to learn "reset -p" or
"checkout -p" and only need to know "add -p", and not having to
learn two extra things is a big plus.  On the other hand, it
requires the users to learn the reflog, but that knowledge extends
to the use outside of the -c option of "commit" command, so overall
I think it is a win.


>> +$ 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
>
> s/ammend/amend/
>
>> +    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.

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

[Jacob Keller]

On Fri, Feb 3, 2017 at 10:59 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Duy Nguyen <pclouds@gmail.com> writes:
>
>>> +$ git reset -p HEAD^                        <1>
>>
>> For good practice, perhaps put "git diff --cached HEAD^" before "git commit".
>>
>> I tend to avoid "reset -p" and "checkout -p" though because sometimes
>> it does not work. Not sure if it's just me, I think it may have
>> something to do with splitting hunks. So I usually go with "reset
>> HEAD^" then "add -p" and "commit -c HEAD@{1}" instead.
>
> Perhaps I am superstitious, but I do that, too.
>
> Doing this that way, the users do not need to learn "reset -p" or
> "checkout -p" and only need to know "add -p", and not having to
> learn two extra things is a big plus.  On the other hand, it
> requires the users to learn the reflog, but that knowledge extends
> to the use outside of the -c option of "commit" command, so overall
> I think it is a win.
>
>

I didn't know about the "-c" option to git commit, that makes the add
-p path a bit more straight forward. I'll re-word the example to use
this new suggested flow.

Thanks,
Jake