Skip to main content

git-dirty-triage

한국어

Tell which modified files in a lagging checkout are really unpublished.

$ git-dirty-triage
checkout is 7 commits behind origin/main
5 changed tracked files: 3 already published, 1 unpublished, 1 needs a decision · 3 untracked entries (1 already on the remote)
      2  identical         same bytes as the remote
      1  stale             an earlier published version of the remote file
      1  contained         the remote already holds every line
      1  new               not on the remote
      1  differs_clean     unpublished edit, merges cleanly
      1  differs_conflict  needs a decision, conflicting lines
      1  untracked_dir     untracked directory, not expanded
        differs_conflict     0 min ago  conflict.txt  1 unique line(s)
        differs_clean        0 min ago  merge.txt  1 unique line(s)
        untracked_dir                  build/  3 file(s)
        new                  0 min ago  new.txt

Why

Several agents or sessions share one checkout. When one of them publishes, it builds a commit on top of the remote tip and pushes; it does not fast-forward the shared checkout, because other sessions are editing files there at that moment. The branch lags on purpose, and git status keeps listing work that is already on the remote.

That listing is not harmless. A later "commit everything and push" builds on the stale local HEAD, collides with the remote's newer version of the same file, and the conflict is not in anyone's edit — it is in the publication.

git status cannot tell you which modified files carry something new: it compares the working tree with the local index, never with the remote. This tool compares every modified path with the remote tip and answers the real question per path.

  • The bytes equal the remote file: the work is published; nothing to do.
  • The bytes equal an earlier published version: also published.
  • Every line already exists in the remote file: nothing unique.
  • The bytes are not on the remote: unpublished.

Untracked trees make that list worse. A build output directory is thousands of files nobody edited, and expanding it buries the handful of real changes. By default git lists an untracked directory as one build/ row, and this tool keeps it that way: one row, no hashing, never committed. Untracked files themselves are still classified, so a file the remote already has counts as published.

Without --commit-unpublished the command only reads. That option writes a commit object and a private ref; it still never moves your branch, index or working tree.

Install

$ pipx install git-dirty-triage     # recommended: isolated, on PATH
$ uvx git-dirty-triage --help       # or run without installing
$ pip install git-dirty-triage      # inside a project

Python 3.9 or newer, git 2.x, and no Python dependencies. The installed command is named git-dirty-triage, so git also runs it as git dirty-triage.

Usage

Classify the dirty paths

$ git-dirty-triage

It fetches the branch first, then compares. The first line says how far the checkout lags. The second is the count that matters, in two parts separated by ·: tracked changes in full detail, then untracked entries. The lines below list only the paths that are not already published. git status order is kept; a long path is shortened from the left.

The per-class counts under the summary cover every row, untracked files included. The summary line splits tracked changes from untracked entries, so the two views differ when an untracked file is already on the remote.

Untracked paths

-u/--untracked follows git status:

Value An untracked directory An untracked file
normal (default) one row, build/, with a file count its own row, classified
all expanded: every file gets a row and is classified its own row, classified
no not listed not listed
$ git-dirty-triage --prefix build
checkout is 7 commits behind origin/main
1 untracked entry
      1  untracked_dir     untracked directory, not expanded
        untracked_dir                  build/  3 file(s)

$ git-dirty-triage --prefix build --untracked all
checkout is 7 commits behind origin/main
3 untracked entries
      3  new               not on the remote
        new                  0 min ago  build/a.log
        new                  0 min ago  build/cache/b.log
        new                  0 min ago  build/cache/c.log

The file count comes from a directory walk; nothing inside an untracked directory is hashed or compared with the remote. untracked_dir rows are never printed by --print-unpublished and never committed. Use --untracked all when you want those files.

Print only the unpublished paths

$ git-dirty-triage --print-unpublished
merge.txt
new.txt

One path per line, ready to pipe. Untracked directories are not printed; untracked files are. Filenames that contain a newline are reported as skipped and never printed, so a line is always one path:

$ git-dirty-triage --print-unpublished | while IFS= read -r p; do git add -- "$p"; done

Commit the unpublished paths on top of the remote tip, without pushing

$ git-dirty-triage --commit-unpublished -m "local work"
committed 2 path(s) as 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e on top of origin/main
  ref:  refs/git-dirty-triage/main
  push: not pushed
  next: git push origin 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e:refs/heads/main

The commit is built on a temporary index from the remote tip's tree: the parent is origin/main, not your HEAD. Edited text uses the three-way merge of your bytes and the remote's, so neither side loses a line; new and binary files are taken whole. Your branch, index and working tree are untouched, and nothing is pushed.

The commit is kept reachable as refs/git-dirty-triage/<branch>. Push it when you have looked at it. Until the remote actually has those bytes, a rerun still reports the paths as unpublished on the remote — that is the question the tool answers.

Conflicting paths are never committed. Resolve them where they are edited; a line-union merge of a changelog or a ledger is not a resolution.

Files touched by local-only commits

--ahead answers the other blind spot: a file that was committed locally, never reached the remote, and has a clean working copy. The dirty scan cannot see it.

$ git-dirty-triage --ahead
checkout is 7 commits behind origin/main
1 path touched by local-only commits: 0 already published, 1 unpublished, 0 need a decision
      1  new               not on the remote
        new                  0 min ago  notes.txt

The three-way base is the merge-base blob instead of HEAD. A path the remote deleted is not brought back, and a version the remote once held counts as stale. --ahead reads commit contents, so --untracked does not apply.

One directory or file

$ git-dirty-triage --prefix src --prefix README.md

--prefix limits the listing itself, not only the report, so a unit costs what its own paths cost. Prefixes are repo-relative.

Machine-readable output

$ git-dirty-triage --json
{"repo": "/tmp/demo/shared", "ref": "origin/main", "behind": 7, "mode": "worktree",
 "counts": {"identical": 2, "stale": 1, "contained": 1, "new": 1, "differs_clean": 1,
            "differs_conflict": 1, "untracked_dir": 1},
 "summary": {"paths": 8,
             "tracked": {"paths": 5, "published": 3, "unpublished": 1, "decide": 1, "deleted": 0, "skipped": 0},
             "untracked": {"entries": 3, "published": 1}},
 "paths": [{"path": "conflict.txt", "class": "differs_conflict", "age_min": 0,
            "reason": "1 unique line(s)", "untracked": false, "files": null}, …]}

(Shown wrapped and shortened; the command prints one line.)

Every row carries untracked and files; files is the count on an untracked_dir row and null elsewhere.

--commit-unpublished --json prints a receipt instead: status, commit, parent, ref, files, paths, pushed and the push command, or {"status": "nothing_to_commit"}.

Exit status

0 means the report was printed, even when it reports unpublished or conflicting paths — the report is data. 2 means a usage or git error. With --commit-unpublished, 0 also covers nothing to commit.

How it decides

Class Working bytes against the remote tip Unpublished?
identical same blob as remote no
stale equal to an earlier published version of the path no
contained every non-blank line already exists in the remote file no
new the remote has no file at this path yes
differs_clean unique lines, and a three-way merge with HEAD as base is clean yes
differs_conflict unique lines, and the same merge conflicts no — a decision
differs_binary binary, and the remote blob is unchanged since HEAD yes, whole file
deleted removed in the working tree reported only
untracked_dir untracked directory under --untracked normal one row; never hashed, printed or committed
skipped not a plain file (symlink, path with a newline) reported only

A clean merge whose result equals the remote bytes is contained: the path only lags.

The cost is one batched hash-object pass and one ls-tree per side. Per-path history is read only for a path that really differs. A 38,925-path checkout was classified in 107 seconds on an Apple-silicon Mac (Python 3.12, warm cache).

A real example

The output at the top of this page comes from examples/make-demo.sh, which builds a throwaway remote and two clones in a temp directory: peer publishes seven commits, shared lags and edits the same five files plus one new file, one untracked copy of a published file and an untracked build/ tree.

$ bash examples/make-demo.sh
demo repo: /tmp/git-dirty-triage-demo/shared
$ cd /tmp/git-dirty-triage-demo/shared && git-dirty-triage

When you do not need it

  • Each agent has its own clone or worktree. Every checkout then tracks the remote, and git status is already the truth.
  • The checkout is up to date with the remote. Same reason.
  • A single writer, no concurrent publication. Nothing is published behind your back.
  • You want to know whether two branches will merge. Use git merge-tree or git range-diff; this tool judges one working tree against one remote branch.

You need it when a checkout is deliberately behind and still has edits — the state a shared multi-agent checkout ends up in.

Limits

  • The answer describes the last fetch. The command fetches by default and prints a warning when the fetch fails, then compares with what is already fetched. --no-fetch skips the fetch without a notice.
  • Files, not trees. Directories are not classified; a rename appears as a delete plus a new file. Deleted and skipped paths are reported and never committed.
  • "Unpublished" is not "wanted". A cleanly merging edit is unpublished by definition; deciding whether it belongs in a commit is yours.
  • Binary files are all-or-nothing, and only when the remote copy has not changed since HEAD; otherwise the path needs a decision.
  • A committed edit is not your working file. For differs_clean the commit holds the three-way merge, which can differ from the bytes on disk. Your working tree is left as it was.
  • Untracked directories stay opaque by default. Their file count comes from a directory walk; nothing inside is hashed or compared with the remote. --untracked all expands them, which is expensive on a large build tree and is the only way to see, print or commit their files.
  • --ahead needs a merge-base. A depth-1 shallow clone has none.
  • Empty repositories are not supported; there is no remote tip to compare with.
  • Tested on macOS (Apple silicon, Python 3.12). The code uses only the standard library and git; Linux and Windows are untested — reports welcome.
  • Very large dirty sets cost one cat-file and one log per genuinely differing file; only the identical and new paths are cheap.

There is no configuration file and no environment variable. Every default is a flag: --repo, --remote, --branch, --untracked.

Agents

If you are an AI agent asked to publish work from a shared checkout, read AGENTS.md. The Claude Code skill lives in skill/git-dirty-triage/SKILL.md; install it by copying that folder to ~/.claude/skills/git-dirty-triage/.

License

MIT — see LICENSE.

Metadata

Release files for git-dirty-triage 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-dirty-triage 0.1.0
File Size Uploaded Provenance Actions
git_dirty_triage-0.1.0.tar.gz 20.7 kB Without provenance Details for git_dirty_triage-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-dirty-triage 0.1.0
File Interpreter ABI Platform Actions
git_dirty_triage-0.1.0-py3-none-any.whl Python 3 none any Details for git_dirty_triage-0.1.0-py3-none-any.whl

Total release size: 39.8 kB

Release files / git_dirty_triage-0.1.0.tar.gz

Download URL git_dirty_triage-0.1.0.tar.gz
Size 20.7 kB
Tags Source
SHA-256 checksum
How to use checksums
fff33d51cc367730bdd5f540ecedb754089e5c3ab9bc12346271289d6b54673f
BLAKE2b-256 checksum
How to use checksums
4bef03c0b890e1edf8909e632ff6e465c390ae5eb1866d5c2b7b3f3ce82b210b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / git_dirty_triage-0.1.0-py3-none-any.whl

Download URL git_dirty_triage-0.1.0-py3-none-any.whl
Size 19.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
78bb6faa28c7280b1c62f5f8e8cf36a4cd6addf6377f271157c8c1323dd77cf3
BLAKE2b-256 checksum
How to use checksums
42da682b609ff1909613408f7e7e8b8d6069ff5f88e0f0f7dbab0fcbb3c020d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for git-dirty-triage 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page