This article is a follow-up to the comments from yesterday’s discussion about interactive adding. Many readers were eager to learn more about the powerful git add -p command, which is a shortcut to the patch mode of interactive adding. This command allows you to break up changes in files into smaller chunks, enabling you to commit exactly what you want without committing the entire file.
Why Use Piecemeal Staging?
The ability to stage changes in small, manageable pieces is incredibly useful. For example, you might have a line of code that works fine on your machine but could break the build on others’ systems or the build server. By using piecemeal staging, you can commit only the parts of the file that are ready, leaving other changes for later commits.
Example of Piecemeal Staging
Let’s go through an example using our project’s README file. After making some changes, here’s what git diff shows:
diff --git a/README.md b/README.md
index 2556dae..45d8b6e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,14 @@
> There is only one way...
> ~ Henry Van Dyke
+# Project information
+
+Blah blah blah...
+
# Want to contribute?
If you have ideas about...
+
+# About
+
+This blog is just awesome.
As you can see, changes have been made in different parts of the file. However, I want to commit only the changes in the lower half. To do this, we use:
git add -p
Running this command presents a prompt similar to git add -i, with several options:
Stage this hunk [y/n/a/d/s/e/?]? ?
y - stage this hunk
n - do not stage this hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help
Most of these options are self-explanatory, but let’s focus on the more interesting ones. The s option splits the current hunk into smaller chunks. This will divide the changes into two smaller hunks: one for the “Project Information” block and another for the “About” block. After splitting, you’ll be prompted with just the changes for each hunk:
Split into 2 hunks.
@@ -1,6 +1,10 @@
> There is only one way...
> ~ Henry Van Dyke
+# Project information
+
+Blah blah blah...
+
# Want to contribute?
If you have ideas about...
Stage this hunk [y/n/a/d/j/J/e/?]? n
We can ignore this hunk by pressing n, and move on to the next one:
@@ -4,3 +8,7 @@
# Want to contribute?
If you have ideas about...
+
+# About
+
+This blog is just awesome.
Stage this hunk [y/n/a/d/K/e/?]? y
Here, we press y to stage this hunk.
Running git status now will show changes to be committed and changes not yet added to the index. It might look strange, but it makes sense since we staged only part of the changes in the file.
The e option allows you to manually edit the hunk in your favorite editor, giving you even more control over what gets staged. Instructions are included with that option, so you can experiment with it when you have the chance.
Piecemeal staging with git add -p is a powerful feature that allows you to commit exactly what you want and keep your commits clean and focused. If you have any stories about how git add -p has helped you, or if you think we missed a neat feature, let us know in the comments!