Git Status Porcelain: Scripting & Automation Guide 2026

A lot of teams meet Git automation the same way. A shell snippet goes into a pre-commit hook, then into CI, then into a release script. Months later, someone upgrades Git, adds a file with a strange name, or introduces generated output into the repo, and a “simple” parser starts making wrong decisions.

That failure mode is avoidable. Git status porcelain exists for exactly this reason. It gives you a machine-oriented status format with a stability contract, but using it safely still takes care. The risky part isn’t choosing porcelain. It’s assuming that porcelain alone makes parsing trivial.

If your broader problem is keeping code and documentation aligned across repositories, hooks, and CI, automation has to extend beyond state checks. Teams that need docs to track source changes usually pair repository checks with documentation automation workflows so code movement doesn’t leave README files, API references, and architecture docs behind.

The Hidden Risk of Unstable Automation Scripts

A common pipeline failure looks boring in the logs. A script shells out to git status, greps a human-readable line, and branches into the wrong path. The repo isn’t broken. The parser is. That distinction matters when a deployment is blocked and the person on call has to figure out whether the issue is the build, the repository, or the glue code around both.

I’ve seen this happen in scripts that assumed output wording, column spacing, or localized text would stay friendly to grep forever. It works until somebody changes environments, adds a rename, or runs the script on a machine with different defaults. Then your “dirty repo” check becomes a source of false positives or, worse, false negatives.

Why human output breaks automation

The regular git status command is for people reading a terminal. It is intentionally descriptive. That’s useful in day-to-day development and dangerous in automation.

What production scripts need is a contract. Git provides one through porcelain status. The Git manual states that git status --porcelain is designed to produce output that is “guaranteed not to change in a backwards-incompatible way” and is easy to parse for scripts, which is why it became the stable interface many tools build on (Git status manual).

This becomes more important as repository checks multiply. Teams use status checks in local hooks, editor integrations, branch protections, release pipelines, and repo health jobs. The parser tends to get copied from one place to five.

Stable repo checks are only half the job

Even when the parser is correct, status output still only tells you repository state. It doesn’t explain the meaning of a change or keep docs aligned with it. That’s where code-aware documentation automation helps. If your issue is stale onboarding docs or API references drifting after merges, GitHub documentation automation workflows are the better layer to automate than trying to infer documentation intent from status lines alone.

The Porcelain Version 1 Format Specification

Most automation starts with porcelain v1 because it’s compact, stable, and widely understood. If you only need to know whether files are modified, staged, deleted, renamed, or untracked, v1 is usually enough.

The basic shape of each line

In porcelain v1, each changed path appears as a line that begins with a two-character status field:

• **X** is the file status in the index.
• **Y** is the file status in the working tree.

After that comes a space and then the path. For renames and copies, Git may include path movement syntax in the output rather than a simple single path.

A few representative examples:

 M app.py
M  app.py
MM app.py
A  docs/api.md
D  old.txt
R  old_name.py -> new_name.py
?? scratch.txt

Read those carefully:

• M app.py means the file is modified in the working tree but not staged.
• M app.py means the modification is staged in the index.
• MM app.py means both staged and unstaged changes exist.
• ?? scratch.txt means the file is untracked.

Git status porcelain v1 XY codes

That table is enough for most policy checks, but advanced scripts still need a few interpretation rules.

What scripts should extract first

The safest first pass is not “parse everything.” It is:

1. Read the two-character status code.
2. Preserve the remainder of the record as path data.
3. Apply business rules after parsing, not during token splitting.

That order prevents a lot of brittle shell logic.

Cases people often misread

Some status combinations are straightforward. Others cause bugs because scripts flatten too much meaning into a single “changed” flag.

• **MM**** is not the same as ****M **. It means there are staged changes and additional unstaged changes.
• **R**** needs special treatment**. A rename record can contain old and new paths.
• **??**** isn’t an error state**. It may be expected in workflows that generate temporary files, test fixtures, or local scratch content.

A practical lookup mindset

For hooks and CI, v1 works well when you ask narrow questions:

• Is the worktree clean?
• Are there untracked files?
• Did generated output modify tracked files?
• Are there staged changes outside an allowed directory?

It works less well when the question is semantic, such as whether a change is important, reviewable, or documentation-worthy. That boundary is where teams often overreach with status-based automation.

Exploring Porcelain v2 and Advanced Flags

Porcelain v1 is good for compact checks. Porcelain v2 is better when you need richer metadata and a more structured grammar for tooling. If your script has to understand renames, modes, object IDs, or branch state in a disciplined way, v2 is usually the cleaner choice.

When v1 is enough and when it isn’t

For a repo cleanliness check, v1 is ideal. It is terse and easy to inspect manually when debugging a script.

For a tool that persists structured state, v2 gives you fewer excuses to write loose parsing logic. Its records are more explicit about what each field represents, which helps once automation grows beyond “fail if dirty.”

A simplified side-by-side illustration:

# v1
 M docs/readme.md
R  old.txt -> new.txt
?? notes.tmp

# v2
1 .M N... 100644 100644 100644 <oid> <oid> docs/readme.md
2 R. N... 100644 100644 100644 <oid> <oid> R100 new.txt	old.txt
? notes.tmp

The exact v2 record types matter less than the operational point. It is more structured and better suited to serious tooling.

Flags that matter in practice

A few status flags change how useful porcelain is in automation:

• **-b** adds branch and tracking information at the top. That’s useful for prompts and policy checks tied to branch state.
• **--untracked-files=<mode>** changes how untracked files are reported. That matters in large repos and generated-code workflows.
• **-z** changes path termination to NUL. For safe parsing, this is often the most important flag in the whole command.

Choosing the right format for the job

Use v1 when you need small, readable status checks in hooks and lightweight CI logic.

Use v2 when the parser is part of a longer-lived tool and you want stronger structure from the start.

A useful heuristic is simple:

• Hook script. Prefer v1 with -z.
• Editor or prompt integration. Prefer the simplest output that meets latency needs.
• Internal automation tool. Prefer v2 if you’ll keep extending it.

Practical Parsing Strategies with Code Examples

The fastest way to break a Git parser is to split lines on whitespace and assume the last token is the file name. That works right up until someone commits docs/API v2.md or a path that contains a tab.

A Bash pattern that stays readable

If you don’t need full path safety yet, you can still write Bash that respects the fixed-width status field. The key is to slice, not tokenize.

#!/usr/bin/env bash
set -euo pipefail

git status --porcelain=v1 | while IFS= read -r line; do
  status="${line:0:2}"
  path="${line:3}"

  case "$status" in
    " M")
      printf 'unstaged modified: %s\n' "$path"
      ;;
    "M ")
      printf 'staged modified: %s\n' "$path"
      ;;
    "??")
      printf 'untracked: %s\n' "$path"
      ;;
    *)
      printf 'other %s %s\n' "$status" "$path"
      ;;
  esac
done

That pattern is much safer than awk '{print $2}', but it still isn’t the final form for hostile filenames. Use it when you’re dealing with controlled paths and understand the limitation.

Python is usually the cleaner long-term choice

For automation that will live longer than a one-off hook, Python gives you better control over subprocess output and easier extension into structured records.

#!/usr/bin/env python3
import subprocess

def get_porcelain_v1():
    result = subprocess.run(
        ["git", "status", "--porcelain=v1"],
        check=True,
        capture_output=True,
        text=True,
    )
    records = []
    for line in result.stdout.splitlines():
        status = line[:2]
        path = line[3:]
        records.append({"status": status, "path": path})
    return records

for record in get_porcelain_v1():
    if record["status"] == "??":
        print(f"untracked: {record['path']}")
    elif record["status"] == " M":
        print(f"unstaged: {record['path']}")

Once you have records as dictionaries, later policy checks become straightforward. You can filter by directory, reject certain patterns, or summarize staged versus unstaged changes without reparsing strings everywhere.

Simple tasks worth automating

A few checks show up repeatedly in real repositories:

• Pre-commit hygiene. Block commits when generated files changed but weren’t staged intentionally.
• Build verification. Run a generator, then fail if the repo is left dirty.
• Local helper commands. Show whether a repo is clean before switching branches or publishing artifacts.

For day-to-day Git commands, this kind of parser pairs well with a compact reference like this Git cheat sheet, especially when teams mix hooks, aliases, and CI scripts.

A useful pre-commit example

This shell hook fails when untracked files exist under a generated output directory:

#!/usr/bin/env bash
set -euo pipefail

has_generated_untracked=false

git status --porcelain=v1 | while IFS= read -r line; do
  status="${line:0:2}"
  path="${line:3}"

  if [[ "$status" == "??" && "$path" == generated/* ]]; then
    printf 'Refusing commit. Untracked generated file: %s\n' "$path" >&2
    has_generated_untracked=true
  fi
done

if [[ "$has_generated_untracked" == true ]]; then
  exit 1
fi

There is one Bash gotcha here. In some shells, the while loop may run in a subshell when fed by a pipe, which means has_generated_untracked won’t persist. In production hooks, prefer process substitution or do the parsing in Python if state handling starts to get awkward. Small details like that are why Git automation ages better when the parser is explicit.

Handling Edge Cases and Common Pitfalls

Most broken parsers pass basic tests. They fail when filenames stop being friendly. A path with spaces is enough to break sloppy for file in $(...) logic. Tabs, newlines, quotes, and other unusual characters make it worse.

Why the usual shell tricks fail

The beginner pattern looks like this:

for file in $(git status --porcelain); do
  echo "$file"
done

That doesn’t iterate over files. It iterates over shell-split words. A single status record turns into multiple tokens, and a file named docs/api spec.md becomes separate fragments. The official Git documentation is clear on the broader issue: porcelain is machine-readable, but safe automation still needs NUL-delimited or carefully escaped handling patterns for edge cases (Git status documentation).

Use -z when filenames matter

The defensive answer is -z. It switches record termination to NUL, which is the delimiter that survives pathological file names safely.

A more reliable Bash pattern:

#!/usr/bin/env bash
set -euo pipefail

while IFS= read -r -d '' record; do
  status="${record:0:2}"
  path="${record:3}"

  printf 'status=%s path=%q\n' "$status" "$path"
done < <(git status --porcelain=v1 -z)

And the Python equivalent:

#!/usr/bin/env python3
import subprocess

result = subprocess.run(
    ["git", "status", "--porcelain=v1", "-z"],
    check=True,
    capture_output=True,
)

records = result.stdout.split(b"\x00")
for raw in records:
    if not raw:
        continue
    status = raw[:2].decode("utf-8", errors="replace")
    path = raw[3:].decode("utf-8", errors="replace")
    print({"status": status, "path": path})

Other traps worth planning for

A few failure modes show up repeatedly:

• Rename handling. A rename record isn’t just a status plus a single path. Test rename scenarios explicitly.
• Generated artifacts. git status porcelain reports that something changed, not whether the change matters.
• Diff semantics. If your workflow needs content-level meaning after a status check, use a diff layer. For structured payloads, a resource like this developer’s guide to JSON diffing is helpful because repository state and content comparison solve different problems.
• Base selection mistakes. Teams often pair status checks with branch comparison logic. If your script also computes divergence or review scope, understanding ancestry matters more than many people expect. This guide to Git merge-base is the right companion topic there.

Real-World Use Cases in Automation and CI/CD

The useful question isn’t “Can I parse Git status?” It is “What decisions should this parser drive?” That changes how much rigor you need.

Checks that pay off quickly

A few patterns deliver value almost immediately.

• Build dirtiness checks. Run your code generator, formatter, or docs builder in CI. Then fail if tracked files changed unexpectedly. This catches missing generated output before merge.
• Pre-commit policy checks. Reject commits that include temporary files, forbidden directories, or accidental local artifacts.
• Prompt and editor integrations. Polling repository state frequently benefits from a lightweight, machine-readable command.

The performance angle matters for the third case. A fish shell issue documents a significant performance difference in a large repository and reports git status --porcelain=v1 completing in about 0.14 s in one measurement, which is exactly why high-frequency tooling prefers porcelain over more human-oriented status parsing (fish shell issue).

Where teams overuse status checks

Status checks are strong at proving repository hygiene. They are weak at reasoning about intent.

For example, a CI job can fail if make docs leaves the repository dirty. That’s useful. But the same check can’t tell you whether the changed docs represent a meaningful API update, an expected reflow, or generated noise. That gap is why engineering teams often combine repository checks with broader CI/CD practices for predictable pipelines, not just one status parser.

Good fit and bad fit

Good fit:

• clean/dirty checks
• staged versus unstaged policy
• untracked file detection
• lightweight repo status polling

Bad fit:

• deciding whether a change is important
• deciding whether docs are adequate
• deciding whether generated changes are safe to ignore by default

Those higher-level decisions need repository conventions, path rules, diff inspection, or code-aware tooling layered on top.

Automating Repository Checks vs Documenting Changes

git status porcelain answers operational questions well. Did a file change? Is the worktree clean? Are there untracked files after a build? Those are useful controls for hooks and CI.

It doesn’t answer the questions engineering managers primarily care about during onboarding, audit prep, or handover. Why did the API surface change? Which service contract moved? Did the refactor alter architecture, or only formatting? As noted in a discussion of Git status limitations, status output alone can’t distinguish transient build artifacts from substantive source changes, so it isn’t a reliable proxy for documentation drift or review importance (Initial Commit discussion of git status).

State isn’t the same as meaning

That distinction is where a lot of internal automation stops too early. Teams build reliable checks around repository state, but they still leave README files stale, OpenAPI references outdated, and onboarding docs dependent on tribal knowledge.

If you’re comparing repository workflows more broadly, a market overview like discover top version control solutions can be useful context. But whichever platform your team uses, status parsing is still only one layer.

Where documentation automation fits

When the primary requirement is keeping docs aligned with code, use repository checks for enforcement and documentation automation for interpretation. One practical option is keeping documentation in sync with code through change-aware tooling rather than trying to infer semantics from status lines.

DocuWriter.ai fits at that layer. Its Autopilot AI Agent connects once through OAuth and webhooks to GitHub, GitLab, Bitbucket, or Azure DevOps, watches changes, and generates documentation suggestions that can be reviewed or auto-applied. That covers README generation, AI code documentation, OpenAPI and Swagger documentation, UML diagrams from code, and refactoring-oriented documentation support. That is a different job from git status porcelain, and teams usually need both.

Frequently Asked Questions About Git Status Porcelain

Is --porcelain the same as --short

No. They may look similar in casual use, but they aren’t the same contract. --short is a concise human-facing format. --porcelain is the scripting interface. If you’re writing automation, use porcelain.

Should I use v1 or v2

Use v1 for compact checks and short scripts. Use v2 when you need richer structure and expect the parser to grow over time.

Can I customize porcelain output

Not in the way people usually mean. That’s deliberate. The point of porcelain is a stable format for tooling, not a user-customizable report.

What’s the safest way to parse filenames

Use -z and parse NUL-delimited records. If your script may ever see spaces, tabs, or unusual characters in paths, that should be your default.

Can porcelain tell me whether a repo is dirty without listing everything

Yes. In a shell, many teams check whether the command returns any output and branch on that condition. That’s often enough for “fail if dirty” logic.

Does porcelain solve all repo automation problems

No. It solves the format stability problem. It does not solve semantic interpretation, content-aware documentation, or policy design.

If your team already relies on Git hooks and CI checks, the next step is making code changes visible in human-readable documentation too. DocuWriter.ai connects to GitHub, GitLab, Bitbucket, and Azure DevOps, watches repository changes through Autopilot, and generates or updates READMEs, code documentation, OpenAPI and Swagger references, UML diagrams, and refactoring docs so your automation doesn’t stop at “something changed.”