A while back, I came across a tweet by Ben Lesh. He mentioned a CLI flag for the git status
command that I didn’t know – --porcelain
. I went ahead and read the documentation for git status
. Here’s what I learned.
Three ways to control the output of git status
Section titled Three ways to control the output of `git status`
I use git for quite a while now, and I usually go with the "normal" git status
command whose output is very verbose.
> git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
(use "git push" to publish your local commits)
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: nuxt.config.js
modified: package-lock.json
modified: package.json
Untracked files:
(use "git add <file>..." to include in what will be committed)
untracked.file
no changes added to commit (use "git add" and/or "git commit -a")
As you see, the default output of git status
is very wordy. While this is not a problem, it shows a lot of information that I’m not interested in as a daily git user. All I care about are files and their status.
When you run git status
with the --porcelain
flag, the displayed information looks as follows:
> git status --porcelain
M nuxt.config.js
M package-lock.json
M package.json
?? untracked.file
Using git status
with the --porcelain
flag is more efficient. After reading the documentation, I found out that there is also a -s
or --short
flag.
> git status -s
M nuxt.config.js
M package-lock.json
M package.json
?? untracked.file
On the first look, these seem to be very similar, but there is one difference that is only visible in the terminal.
git status -s
highlights the characters that give information on a files’ status. This highlighting makes it easier to read. This formatting and color highlighting are missing when using --porcelain
.
The difference between git status -s
and git status --porcelain
So why’s that? It turns out that the --porcelain
flag is used to generate output that is easily parseable by a script. Imagine you run some automation that checks the status of a git repository before running further commands. In that case, you don’t want to have help text and terminal colors included in the output.
Additionally, you also don’t want that the output changes or differs from git version to git version. --porcelain
guarantees that there won’t be backward-incompatible changes to the output so that your scripts won’t break with a git update.
For compact display including some colored guidance, you can use git status -s
, and if you’re automating git workflows, you can use git status --porcelain
. That’s cool!
Different versions of git status --porcelain
The last thing I learned is that --porcelain
comes with different included versions (remember the backward compatibility promise). Without a defined version --porcelain
uses the v1
format that you have seen in this post. There is also a v2
available.
# --porcelain version 1
$ git status --porcelain
M nuxt.config.js
M package-lock.json
M package.json
?? untracked.file
# --porcelain version 2
$ git status --porcelain=v2
1 .M N... 100644 100644 100644 9f49fa176b56de04416172603c0f8e623706cf7a 9f49fa176b56de04416172603c0f8e623706cf7a nuxt.config.js
1 .M N... 100644 100644 100644 7042578104220c9fa983a749e8f87d488a7a9e80 7042578104220c9fa983a749e8f87d488a7a9e80 package-lock.json
1 .M N... 100644 100644 100644 823ac73a97a0f9c9c73e9bd775bd3421d7a2940c 823ac73a97a0f9c9c73e9bd775bd3421d7a2940c package.json
? untracked.file
v2
includes more additional information. If you want to find out more about version two, head over to git status
documentation.
For advanced automation using git, --porcelain
definitely can be very useful. The flag is also available for commands like push
or blame
. ?