* [PATCH v3] reset: add an example of how to split a commit into two
@ 2017-02-16 0:22 Jacob Keller
2017-02-16 19:19 ` Junio C Hamano
0 siblings, 1 reply; 4+ messages in thread
From: Jacob Keller @ 2017-02-16 0:22 UTC (permalink / raw)
To: git; +Cc: Jacob Keller, Junio C Hamano
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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
The interdiff between v2 and v3 is not really worth showing since I
basically re-wrote the entire section a bit. I reworded the descriptions
and steps to indicate that you can break a commit apart into an
arbitrary number of separate commits. I also added a bit more
explanation to each step, and separately numbered the "repeat some steps
multiple times" portion.
Documentation/git-reset.txt | 48 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 25432d9257f9..67a63574092d 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -292,6 +292,54 @@ $ 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 apart into a sequence of commits::
++
+Suppose that you have create lots of logically separate changes and commit 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 -N HEAD^ <1>
+$ git add -p <2>
+$ git diff --cached <3>
+$ git commit -c HEAD@{1} <4>
+... <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. 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
----------
--
2.12.0.rc0.177.g63172abf21d0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v3] reset: add an example of how to split a commit into two
2017-02-16 0:22 [PATCH v3] reset: add an example of how to split a commit into two Jacob Keller
@ 2017-02-16 19:19 ` Junio C Hamano
2017-02-16 19:49 ` Junio C Hamano
0 siblings, 1 reply; 4+ messages in thread
From: Junio C Hamano @ 2017-02-16 19:19 UTC (permalink / raw)
To: Jacob Keller; +Cc: git, Jacob Keller
Jacob Keller <jacob.e.keller@intel.com> writes:
> The interdiff between v2 and v3 is not really worth showing since I
> basically re-wrote the entire section a bit.
Could this be made into an incremental, now that v2 has been in
'next' for about 10 days, please?
> +Split a commit apart into a sequence of commits::
> ++
> +Suppose that you have create lots of logically separate changes and commit them
s/create/&d/; s/commit/&ed/
> +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 -N HEAD^ <1>
> +$ git add -p <2>
> +$ git diff --cached <3>
> +$ git commit -c HEAD@{1} <4>
> +... <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. 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.
> +
Nicely done. We could talk more "best practice" things in this
sequence (e.g. "'stash --keep' then test in isolation"), but it is
already sufficiently long, so extending it may hurt the readability
more than it helps by guiding the readers to better ways.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v3] reset: add an example of how to split a commit into two
2017-02-16 19:19 ` Junio C Hamano
@ 2017-02-16 19:49 ` Junio C Hamano
2017-02-16 21:26 ` Jacob Keller
0 siblings, 1 reply; 4+ messages in thread
From: Junio C Hamano @ 2017-02-16 19:49 UTC (permalink / raw)
To: Jacob Keller; +Cc: git, Jacob Keller
Junio C Hamano <gitster@pobox.com> writes:
> Jacob Keller <jacob.e.keller@intel.com> writes:
>
>> The interdiff between v2 and v3 is not really worth showing since I
>> basically re-wrote the entire section a bit.
>
> Could this be made into an incremental, now that v2 has been in
> 'next' for about 10 days, please?
Nah, I think it is easier to read "log -p" if I just revert v2 out
of existence from 'next', and queue this (with a minor typofixes) as
a different topic to be merged later to 'master'.
So no need to resend and certainly no need to make it incremental.
>> +Split a commit apart into a sequence of commits::
>> ++
>> +Suppose that you have create lots of logically separate changes and commit them
>
> s/create/&d/; s/commit/&ed/
I'd do this myself while queuing.
Thanks.
>
>> +together. Then, later you decide that it might be better to have each logical
>> +chunk associated with its own commit. ...
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v3] reset: add an example of how to split a commit into two
2017-02-16 19:49 ` Junio C Hamano
@ 2017-02-16 21:26 ` Jacob Keller
0 siblings, 0 replies; 4+ messages in thread
From: Jacob Keller @ 2017-02-16 21:26 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jacob Keller, Git mailing list
On Thu, Feb 16, 2017 at 11:49 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Jacob Keller <jacob.e.keller@intel.com> writes:
>>
>>> The interdiff between v2 and v3 is not really worth showing since I
>>> basically re-wrote the entire section a bit.
>>
>> Could this be made into an incremental, now that v2 has been in
>> 'next' for about 10 days, please?
>
> Nah, I think it is easier to read "log -p" if I just revert v2 out
> of existence from 'next', and queue this (with a minor typofixes) as
> a different topic to be merged later to 'master'.
>
Ok. Yea, I didn't even realize it was put into next because of the
various comments I'd received. I guess I could have checked, but the
diff really is bad when seeing incrementally.
> So no need to resend and certainly no need to make it incremental.
>
>>> +Split a commit apart into a sequence of commits::
>>> ++
>>> +Suppose that you have create lots of logically separate changes and commit them
>>
>> s/create/&d/; s/commit/&ed/
>
> I'd do this myself while queuing.
>
> Thanks.
Thanks,
Jake
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2017-02-16 21:27 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-02-16 0:22 [PATCH v3] reset: add an example of how to split a commit into two Jacob Keller
2017-02-16 19:19 ` Junio C Hamano
2017-02-16 19:49 ` Junio C Hamano
2017-02-16 21:26 ` Jacob Keller
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).