If you are writing automation that touches a git repo then porcelain is the polite way to ask for machine readable status without the drama. Porcelain output is compact and stable so your scripts do not have to guess which human friendly phrase will change next week.

What porcelain actually gives you

Porcelain is a stab at consistency for programmatic parsing. The simple version prints two status flags then a path. The first column is the staged state and the second column is the work tree state. That tiny format avoids the usual noise you get when humans try to describe a tree and think color is an API.

Quick examples you can copy and paste

git status --porcelain
# example lines
M src/app.py
A src/new.py
?? README.md

# for scripting use the safer variant
git status --porcelain=v2 -z

How to read the basic lines

• Read the first two characters as flags and the rest as the path.
• Common letters include M for modified, A for added, D for deleted, R for renamed, C for copied and U for unmerged conflicts.
• Question marks mean untracked files and are a great way to remind you that you forgot to add a README.

Why porcelain v2 is your friend

Porcelain v2 was designed for tooling not poetry. It gives more predictable fields and separate records for complex events like renames and copies. When filenames contain spaces or newlines the old approach becomes a fragile mess. Using the null terminated form solves that problem and keeps your automation from crying on weird filenames.

Parsing rules that keep your CI awake

• Prefer porcelain v2 with null termination. Use git status --porcelain=v2 -z and split on the NUL character.
• Avoid ad hoc regexes that match the human summary. Those will break the minute someone adds a new status you did not expect.
• Handle rename and copy records explicitly because they carry extra metadata your script may need to map source to destination.
• Test parsing with tricky filenames. Spaces, unicode, and newlines are the usual suspects that bite in production.

Small checklist for robust scripts

• Use porcelain v2 when possible for predictable fields.
• Use the -z option and split on null to handle odd filenames.
• Treat the first two chars as status flags and then use the remaining fields according to the record type.
• Cover renames and copies so your CI does not make bad guesses during deployments.
• Run your parser locally and in CI environments like GitHub Actions, GitLab runners, or Bitbucket pipelines before relying on it for a release.

In short, treat porcelain as a stable API for status output. Give your scripts predictable input and they will repay you by failing less dramatically at 3 AM. Also consider a cup of coffee for the human who still wants pretty summaries and color.