The short version of 'git status' and the close but different '--porcelain' mode
- Published at
- Updated at
- Reading time
- 3min
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.
I have used git for years 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 there is also a -s
or --short
flag.
> git status -s
M nuxt.config.js
M package-lock.json
M package.json
?? untracked.file
At first look, these two flags 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 the 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 script-parseable. Imagine running 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 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 with color 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
is the way to go. The flag is also available for commands like push
or blame
. ๐ Happy scripting! ๐
Join 5.4k readers and learn something new every week with Web Weekly.