Skip to main content

git-dirty-triage

한국어

A Git command that separates unpublished edits from work already on the remote.

A checkout seven commits behind origin is classified, then two unpublished paths are printed

The demo uses a throwaway remote and two clones. One clone publishes seven commits; the other keeps local edits. Fixture and tape.

Install

pipx install git-dirty-triage
uv tool install git-dirty-triage
pip install git-dirty-triage

Python 3.9+, Git 2.x, and no Python dependencies. The installed command also works as git dirty-triage.

Verified on macOS arm64 with Python 3.12. Linux and Windows have not been exercised.

Quick start

Run it from your checkout. It fetches the remote first, then classifies the changed paths. These outputs were captured from the bundled throwaway repository.

$ 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
$ git-dirty-triage --print-unpublished
merge.txt
new.txt
$ 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)

merge.txt and new.txt carry unpublished work. conflict.txt needs a decision. The untracked build/ directory stays one row unless you pass --untracked all.

Why

In a shared checkout, another session can publish your bytes without moving your local branch or index. git status still calls those files modified because it compares them with your index. That leaves you sorting old work from new work before every commit.

This command compares the working files with the remote tip and earlier published versions. It separates already-published bytes, new edits, and conflicts. A normal report does not change your branch, index, or working files; the default fetch does update remote-tracking refs.

Tool Use it for
git status / git diff Changes against your own index or local commit
git log / git range-diff Commit history and differences between commit series
git-dirty-triage Working files in a checkout that lags behind published work

If your checkout already follows the remote, start with git status.

Measurement

A previous warm-cache run classified 38,925 paths in 107 seconds on an Apple-silicon Mac with Python 3.12. This is one observed checkout, not a throughput guarantee. Unique differences require per-path history and content reads; use --prefix to limit the work to your directory.

Reference

Option What you get
--repo PATH Inspect that checkout instead of the current directory
--remote NAME, --branch NAME Choose the comparison ref; remote defaults to origin
--prefix PATH Limit the scan and report to a repo-relative prefix; repeatable
--json Full report, counts and per-path classifications
--print-unpublished One unpublished path per line
--untracked normal One row per untracked directory, with a file count; default
--untracked all Expand untracked directories into file rows
--untracked no Omit untracked paths
--ahead Inspect paths touched by local-only commits, even with clean working files
--no-fetch Use the last fetched ref
--commit-unpublished -m MESSAGE Build a commit on the remote tip; do not push

There is no configuration file or tool-specific environment variable. With no --branch, the tool tries the remote's default branch, then main, then master.

Classes

Compare working files with the remote, then separate published, unpublished, and review-only paths

This groups classification outcomes. Contained does not prove equivalent line order; opaque untracked directories are counted without content comparison.

Class Meaning Commit candidate?
identical Same bytes as the remote No
stale Same bytes as an earlier published version No
contained Every nonblank local line is already in the remote file No
new No remote file at that path Yes
differs_clean Unique lines; three-way merge succeeds Yes
differs_conflict Three-way merge conflicts Needs a decision
differs_binary Binary difference Only if remote bytes are unchanged since HEAD
deleted Working file removed Report only
untracked_dir Unexpanded directory Report only
skipped Unsupported path, such as a symlink or newline in a name Report only

contained is a line-membership heuristic. It does not preserve line order or repetition, so it cannot establish semantic equivalence. Review reorder-only changes yourself.

Build a commit

git-dirty-triage --commit-unpublished -m "Update the parser"

The commit uses a temporary index and the remote tip as its parent. It keeps a private ref under refs/git-dirty-triage/<branch>. Your current branch, index and working tree stay as they were; the command prints a suggested push command but does not run it.

For differs_clean, the committed bytes are the three-way merge, which can differ from your working file. Conflicting, deleted, skipped, and opaque directory rows are excluded. Unpublished does not mean ready to publish: inspect the selected changes before using this option.

JSON and exits

--json returns repo, ref, behind, mode, counts, summary, and paths. summary separates tracked changes from untracked entries; per-class counts include both. Every path has class, reason, untracked, and files (a count for opaque directories, otherwise null).

Exit 0 means the report was produced, even if it contains conflicts. Exit 2 means a usage or Git error. Commit mode also exits 0 when there is nothing to commit.

Limits

  • A failed fetch prints a warning and uses the last fetched ref. The report then describes that cached state.
  • stale means previously published, not equal to the current remote. contained compares lines, not meaning.
  • Renames appear as deletion plus addition. Deleted paths are reported, never committed.
  • Untracked directories are counted but not hashed or compared unless expanded with --untracked all.
  • --ahead needs a merge base; a depth-one shallow clone may lack one.
  • Empty repositories without a remote tip are unsupported.
  • Linux and Windows are untested. The saved measurement covers one macOS checkout only.

Contributing

Issues and platform reports are welcome; run python3 -m compileall -q src from the source checkout. See AGENTS.md for the code layout and safety rules.

License: MIT.

Metadata

Release files for git-dirty-triage 0.1.1

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.1
File Size Uploaded Provenance Actions
git_dirty_triage-0.1.1.tar.gz 17.8 kB Without provenance Details for git_dirty_triage-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 35.4 kB

Release files / git_dirty_triage-0.1.1.tar.gz

Download URL git_dirty_triage-0.1.1.tar.gz
Size 17.8 kB
Tags Source
SHA-256 checksum
How to use checksums
23cb679f32c21734bcb968054d25e59528aad8ce9867e34a0a319ed6f81ccfbd
BLAKE2b-256 checksum
How to use checksums
ead7291ed1bb69af32effcb6978bd85077323779940601bccf69dde1afb33373
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.1-py3-none-any.whl

Download URL git_dirty_triage-0.1.1-py3-none-any.whl
Size 17.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
178f419de5a9ccfe38b893acf2bb7fd6eedfa04114e8d5458923f6f62cd9bebc
BLAKE2b-256 checksum
How to use checksums
8bb93fe94ef449bd0f30ea802b4a3050e254883a37429502629d05d8e29718a2
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.1

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