Git is one of the most powerful tools in a software workflow, and knowing tricks to bend it to your will can help you to be more efficient and keep your repository better organized. It has an overwhelming amount of tools under the hood, and today we’ll be looking at the enormously useful
--patch mode to see how it’s often a better option than a plain old
A Simple Example
Let’s start by creating a simple test repository containing a few text files.
mkdir ./patch-mode && cd ./patch-mode git init . echo "Superman" >> heroes echo "Wonder Woman" >> heroes echo "Spider Man" >> heroes echo "Iron Man" >> heroes echo "R2D2" >> robots echo "Johnny #5" >> robots echo "Kitt" >> robots
Because these are brand new files, we’ll go ahead and run an initial
git add with the special
-N flag to let git know that we intend to add these files later, but for now, to act as if these files were already staged.
git add -N heroes robots
Let’s stop and have a look at the diff to see what our changes look like
diff --git a/heroes b/heroes index e69de29..81533d0 100644 --- a/heroes +++ b/heroes @@ -0,0 +1,3 @@ +Superman +Wonder Woman +Spider Man +Iron Man diff --git a/robots b/robots index e69de29..3572eed 100644 --- a/robots +++ b/robots @@ -0,0 +1,3 @@ +R2D2 +Johnny #5 +Kitt
Exactly what we’d expect. We see the addition of four heroes and three robots. At this point we could
git add -a,
git add ., or
git add heroes robots to stage all of the changes at one time. Sometimes, though, you’ve made changes elsewhere that you might not want to commit, and any of those commands would cause you to unintentionally stage those changes. Let’s see if we can avoid that.
The –patch flag
git add --patch
diff --git a/heroes b/heroes index e69de29..cf1fcb8 100644 --- a/heroes +++ b/heroes @@ -0,0 +1,4 @@ +Superman +Wonder Woman +Spider Man +Iron Man Stage this hunk [y,n,q,a,d,/,e,?]?
git add --patch is showing us the first hunk of changes, our heroes file with four additions. It’s also giving us a list of options for staging the hunk;
[y,n,q,a,d,/,e,?]. The list shows the options available to us given our current hunk, but you can type
? and hit
[Enter] to get a better understanding of all of the options. Our available options are:
- y - stage this hunk
- n - do not stage this hunk
- q - quit; do not stage this hunk or any of the remaining ones
- a - stage this hunk and all later hunks in the file
- d - do not stage this hunk or any of the later hunks in the file
- / - search for a hunk matching the given regex
- e - manually edit the current hunk
- ? - print help
This time, it’s a good thing we opted for
--patch! We haven’t decided if Iron Man is a hero. I mean, he doesn’t have any true super powers after all. Let’s not include him in our list, at least for this commit. To do that, we’ll choose
e to manually edit this hunk. Keep in mind we’re not editing the actual file, just the diff to be applied to this hunk.
# Manual hunk edit mode -- see bottom for a quick guide @@ -0,0 +1,4 @@ +Superman +Wonder Woman +Spider Man +Iron Man # --- # To remove '-' lines, make them ' ' lines (context). # To remove '+' lines, delete them. # Lines starting with # will be removed. # # If the patch applies cleanly, the edited hunk will immediately be # marked for staging. If it does not apply cleanly, you will be given # an opportunity to edit again. If all lines of the hunk are removed, # then the edit is aborted and the hunk is left unchanged.
We now have the ability to move about freely in the hunk and modify it according to the instructions in the comment at the bottom. In our case, we’d like to remove a ‘+’ line from the hunk. Namely, the Iron Man addition. Removing that line should result in the following hunk
# Manual hunk edit mode -- see bottom for a quick guide @@ -0,0 +1,4 @@ +Superman +Wonder Woman +Spider Man # --- # To remove '-' lines, make ...
Again, we’re not telling git that we want to delete “Iron Man” from the heroes file, just that we don’t want to commit that specific piece of the hunk right now. Save the hunk with
:wq and git will move on to the next hunk of changes.
diff --git a/robots b/robots index e69de29..3572eed 100644 --- a/robots +++ b/robots @@ -0,0 +1,3 @@ +R2D2 +Johnny #5 +Kitt Stage this hunk [y,n,q,a,d,/,e,?]?
These changes look good! Let’s choose
y to let git know that we’d like to stage this hunk of changes as is.
At this point, there are no more changes to be added and git will exit the interactive
--patch mode. If we take a look at
git status, we’ll see that new heroes file is staged for commit and that it has modifications that are not staged for commit:
On branch master Initial commit Changes to be committed: new file: heroes new file: robots Changes not staged for commit: modified: heroes
Hopfully it’s clear that this is happening because the heroes file still contains our “Iron Man” line, and that line was not staged for commit thanks to us using the interactive
--patch mode. Running
git diff will confirm that that is indeed the change in question:
diff --git a/heroes b/heroes index 81533d0..cf1fcb8 100644 --- a/heroes +++ b/heroes @@ -1,3 +1,4 @@ Superman Wonder Woman Spider Man +Iron Man
--patch mode effectively is a great way to keep your commits logical and narrow. I’ve found that it also helps to force me to take a closer look at all of my changes to ensure I’m only commiting code that should be commited. Take a moment to get comfortable using it in your workflow and it will pay great dividends in the long run with regard to your commit history.