The short version of 'git status' and the close but different '--porcelain' mode

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! 👋