Skip to main content
git-dirty-triage: a local branch leaving the published line

git-dirty-triage

한국어

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

Python 3.9+ · Git 2.x

pypi license

38,925 paths classified in 107 seconds on one warm-cache macOS checkout.

Install · Quick start · Why

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 and the fixture in docs/demo/make-repo.sh. See CONTRIBUTING.md for the review process and AGENTS.md for the code layout and safety rules.

License

MIT. See LICENSE.

Metadata

Release files for git-dirty-triage 0.1.3

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.3
File Size Uploaded Provenance Actions
git_dirty_triage-0.1.3.tar.gz 18.3 kB Without provenance Details for git_dirty_triage-0.1.3.tar.gz

Built distribution (wheel)

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

Total release size: 36.3 kB

Release files / git_dirty_triage-0.1.3.tar.gz

Download URL git_dirty_triage-0.1.3.tar.gz
Size 18.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3e358ea73a50907465d8d7cf7b5014127e479c89533da04294ecd0c7bd71454c
BLAKE2b-256 checksum
How to use checksums
6c6b32fb9a7b5fb15b36502ad899ae4885c7872ac3e61e9d218fb404dc02fca0
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.3-py3-none-any.whl

Download URL git_dirty_triage-0.1.3-py3-none-any.whl
Size 17.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f276f57b1b3502b221b8f551d344fafccd9ad49cb0e41a698891546d67d196aa
BLAKE2b-256 checksum
How to use checksums
4f80b0c6bd679b57f30a4bb015d4ec85584672905867a5c449662a52d05a8c34
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.3

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