git-dirty-triage 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 El Fenomeno
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,249 @@
1
+ Metadata-Version: 2.4
2
+ Name: git-dirty-triage
3
+ Version: 0.1.0
4
+ Summary: Tell which modified files in a lagging or shared Git checkout are really unpublished, and commit only those on top of the remote tip without pushing.
5
+ Author: El Fenomeno
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/elfenomenokim/git-dirty-triage
8
+ Project-URL: Repository, https://github.com/elfenomenokim/git-dirty-triage
9
+ Project-URL: Issues, https://github.com/elfenomenokim/git-dirty-triage/issues
10
+ Keywords: git,dirty,checkout,monorepo,multi-agent,agents,three-way-merge,cli
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Topic :: Software Development :: Version Control :: Git
18
+ Classifier: Topic :: Utilities
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # git-dirty-triage
25
+
26
+ [한국어](https://github.com/elfenomenokim/git-dirty-triage/blob/main/README.ko.md)
27
+
28
+ Tell which modified files in a lagging checkout are really unpublished.
29
+
30
+ ```console
31
+ $ git-dirty-triage
32
+ checkout is 7 commits behind origin/main
33
+ 5 changed tracked files: 3 already published, 1 unpublished, 1 needs a decision · 3 untracked entries (1 already on the remote)
34
+ 2 identical same bytes as the remote
35
+ 1 stale an earlier published version of the remote file
36
+ 1 contained the remote already holds every line
37
+ 1 new not on the remote
38
+ 1 differs_clean unpublished edit, merges cleanly
39
+ 1 differs_conflict needs a decision, conflicting lines
40
+ 1 untracked_dir untracked directory, not expanded
41
+ differs_conflict 0 min ago conflict.txt 1 unique line(s)
42
+ differs_clean 0 min ago merge.txt 1 unique line(s)
43
+ untracked_dir build/ 3 file(s)
44
+ new 0 min ago new.txt
45
+ ```
46
+
47
+ ## Why
48
+
49
+ 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.
50
+
51
+ 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.
52
+
53
+ `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.
54
+
55
+ - The bytes equal the remote file: the work is published; nothing to do.
56
+ - The bytes equal an earlier published version: also published.
57
+ - Every line already exists in the remote file: nothing unique.
58
+ - The bytes are not on the remote: unpublished.
59
+
60
+ 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.
61
+
62
+ 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.
63
+
64
+ ## Install
65
+
66
+ ```console
67
+ $ pipx install git-dirty-triage # recommended: isolated, on PATH
68
+ $ uvx git-dirty-triage --help # or run without installing
69
+ $ pip install git-dirty-triage # inside a project
70
+ ```
71
+
72
+ 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`.
73
+
74
+ ## Usage
75
+
76
+ ### Classify the dirty paths
77
+
78
+ ```console
79
+ $ git-dirty-triage
80
+ ```
81
+
82
+ 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.
83
+
84
+ 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.
85
+
86
+ ### Untracked paths
87
+
88
+ `-u/--untracked` follows git status:
89
+
90
+ | Value | An untracked directory | An untracked file |
91
+ |---|---|---|
92
+ | `normal` (default) | one row, `build/`, with a file count | its own row, classified |
93
+ | `all` | expanded: every file gets a row and is classified | its own row, classified |
94
+ | `no` | not listed | not listed |
95
+
96
+ ```console
97
+ $ git-dirty-triage --prefix build
98
+ checkout is 7 commits behind origin/main
99
+ 1 untracked entry
100
+ 1 untracked_dir untracked directory, not expanded
101
+ untracked_dir build/ 3 file(s)
102
+
103
+ $ git-dirty-triage --prefix build --untracked all
104
+ checkout is 7 commits behind origin/main
105
+ 3 untracked entries
106
+ 3 new not on the remote
107
+ new 0 min ago build/a.log
108
+ new 0 min ago build/cache/b.log
109
+ new 0 min ago build/cache/c.log
110
+ ```
111
+
112
+ 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.
113
+
114
+ ### Print only the unpublished paths
115
+
116
+ ```console
117
+ $ git-dirty-triage --print-unpublished
118
+ merge.txt
119
+ new.txt
120
+ ```
121
+
122
+ 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:
123
+
124
+ ```console
125
+ $ git-dirty-triage --print-unpublished | while IFS= read -r p; do git add -- "$p"; done
126
+ ```
127
+
128
+ ### Commit the unpublished paths on top of the remote tip, without pushing
129
+
130
+ ```console
131
+ $ git-dirty-triage --commit-unpublished -m "local work"
132
+ committed 2 path(s) as 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e on top of origin/main
133
+ ref: refs/git-dirty-triage/main
134
+ push: not pushed
135
+ next: git push origin 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e:refs/heads/main
136
+ ```
137
+
138
+ 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.
139
+
140
+ 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.
141
+
142
+ 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.
143
+
144
+ ### Files touched by local-only commits
145
+
146
+ `--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.
147
+
148
+ ```console
149
+ $ git-dirty-triage --ahead
150
+ checkout is 7 commits behind origin/main
151
+ 1 path touched by local-only commits: 0 already published, 1 unpublished, 0 need a decision
152
+ 1 new not on the remote
153
+ new 0 min ago notes.txt
154
+ ```
155
+
156
+ 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.
157
+
158
+ ### One directory or file
159
+
160
+ ```console
161
+ $ git-dirty-triage --prefix src --prefix README.md
162
+ ```
163
+
164
+ `--prefix` limits the listing itself, not only the report, so a unit costs what its own paths cost. Prefixes are repo-relative.
165
+
166
+ ### Machine-readable output
167
+
168
+ ```console
169
+ $ git-dirty-triage --json
170
+ {"repo": "/tmp/demo/shared", "ref": "origin/main", "behind": 7, "mode": "worktree",
171
+ "counts": {"identical": 2, "stale": 1, "contained": 1, "new": 1, "differs_clean": 1,
172
+ "differs_conflict": 1, "untracked_dir": 1},
173
+ "summary": {"paths": 8,
174
+ "tracked": {"paths": 5, "published": 3, "unpublished": 1, "decide": 1, "deleted": 0, "skipped": 0},
175
+ "untracked": {"entries": 3, "published": 1}},
176
+ "paths": [{"path": "conflict.txt", "class": "differs_conflict", "age_min": 0,
177
+ "reason": "1 unique line(s)", "untracked": false, "files": null}, …]}
178
+ ```
179
+
180
+ (Shown wrapped and shortened; the command prints one line.)
181
+
182
+ Every row carries `untracked` and `files`; `files` is the count on an `untracked_dir` row and `null` elsewhere.
183
+
184
+ `--commit-unpublished --json` prints a receipt instead: `status`, `commit`, `parent`, `ref`, `files`, `paths`, `pushed` and the `push` command, or `{"status": "nothing_to_commit"}`.
185
+
186
+ ### Exit status
187
+
188
+ `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`.
189
+
190
+ ## How it decides
191
+
192
+ | Class | Working bytes against the remote tip | Unpublished? |
193
+ |---|---|---|
194
+ | `identical` | same blob as remote | no |
195
+ | `stale` | equal to an earlier published version of the path | no |
196
+ | `contained` | every non-blank line already exists in the remote file | no |
197
+ | `new` | the remote has no file at this path | yes |
198
+ | `differs_clean` | unique lines, and a three-way merge with `HEAD` as base is clean | yes |
199
+ | `differs_conflict` | unique lines, and the same merge conflicts | no — a decision |
200
+ | `differs_binary` | binary, and the remote blob is unchanged since `HEAD` | yes, whole file |
201
+ | `deleted` | removed in the working tree | reported only |
202
+ | `untracked_dir` | untracked directory under `--untracked normal` | one row; never hashed, printed or committed |
203
+ | `skipped` | not a plain file (symlink, path with a newline) | reported only |
204
+
205
+ A clean merge whose result equals the remote bytes is `contained`: the path only lags.
206
+
207
+ 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).
208
+
209
+ ## A real example
210
+
211
+ 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.
212
+
213
+ ```console
214
+ $ bash examples/make-demo.sh
215
+ demo repo: /tmp/git-dirty-triage-demo/shared
216
+ $ cd /tmp/git-dirty-triage-demo/shared && git-dirty-triage
217
+ ```
218
+
219
+ ## When you do not need it
220
+
221
+ - **Each agent has its own clone or worktree.** Every checkout then tracks the remote, and `git status` is already the truth.
222
+ - **The checkout is up to date with the remote.** Same reason.
223
+ - **A single writer, no concurrent publication.** Nothing is published behind your back.
224
+ - **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.
225
+
226
+ You need it when a checkout is deliberately behind and still has edits — the state a shared multi-agent checkout ends up in.
227
+
228
+ ## Limits
229
+
230
+ - **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.
231
+ - **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.
232
+ - **"Unpublished" is not "wanted".** A cleanly merging edit is unpublished by definition; deciding whether it belongs in a commit is yours.
233
+ - **Binary files are all-or-nothing**, and only when the remote copy has not changed since HEAD; otherwise the path needs a decision.
234
+ - **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.
235
+ - **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.
236
+ - **`--ahead` needs a merge-base.** A depth-1 shallow clone has none.
237
+ - **Empty repositories are not supported**; there is no remote tip to compare with.
238
+ - **Tested on macOS (Apple silicon, Python 3.12).** The code uses only the standard library and `git`; Linux and Windows are untested — reports welcome.
239
+ - **Very large dirty sets** cost one `cat-file` and one `log` per genuinely differing file; only the identical and new paths are cheap.
240
+
241
+ There is no configuration file and no environment variable. Every default is a flag: `--repo`, `--remote`, `--branch`, `--untracked`.
242
+
243
+ ## Agents
244
+
245
+ If you are an AI agent asked to publish work from a shared checkout, read [AGENTS.md](https://github.com/elfenomenokim/git-dirty-triage/blob/main/AGENTS.md). The Claude Code skill lives in [`skill/git-dirty-triage/SKILL.md`](https://github.com/elfenomenokim/git-dirty-triage/blob/main/skill/git-dirty-triage/SKILL.md); install it by copying that folder to `~/.claude/skills/git-dirty-triage/`.
246
+
247
+ ## License
248
+
249
+ MIT — see [LICENSE](https://github.com/elfenomenokim/git-dirty-triage/blob/main/LICENSE).
@@ -0,0 +1,226 @@
1
+ # git-dirty-triage
2
+
3
+ [한국어](https://github.com/elfenomenokim/git-dirty-triage/blob/main/README.ko.md)
4
+
5
+ Tell which modified files in a lagging checkout are really unpublished.
6
+
7
+ ```console
8
+ $ git-dirty-triage
9
+ checkout is 7 commits behind origin/main
10
+ 5 changed tracked files: 3 already published, 1 unpublished, 1 needs a decision · 3 untracked entries (1 already on the remote)
11
+ 2 identical same bytes as the remote
12
+ 1 stale an earlier published version of the remote file
13
+ 1 contained the remote already holds every line
14
+ 1 new not on the remote
15
+ 1 differs_clean unpublished edit, merges cleanly
16
+ 1 differs_conflict needs a decision, conflicting lines
17
+ 1 untracked_dir untracked directory, not expanded
18
+ differs_conflict 0 min ago conflict.txt 1 unique line(s)
19
+ differs_clean 0 min ago merge.txt 1 unique line(s)
20
+ untracked_dir build/ 3 file(s)
21
+ new 0 min ago new.txt
22
+ ```
23
+
24
+ ## Why
25
+
26
+ 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.
27
+
28
+ 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.
29
+
30
+ `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.
31
+
32
+ - The bytes equal the remote file: the work is published; nothing to do.
33
+ - The bytes equal an earlier published version: also published.
34
+ - Every line already exists in the remote file: nothing unique.
35
+ - The bytes are not on the remote: unpublished.
36
+
37
+ 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.
38
+
39
+ 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.
40
+
41
+ ## Install
42
+
43
+ ```console
44
+ $ pipx install git-dirty-triage # recommended: isolated, on PATH
45
+ $ uvx git-dirty-triage --help # or run without installing
46
+ $ pip install git-dirty-triage # inside a project
47
+ ```
48
+
49
+ 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`.
50
+
51
+ ## Usage
52
+
53
+ ### Classify the dirty paths
54
+
55
+ ```console
56
+ $ git-dirty-triage
57
+ ```
58
+
59
+ 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.
60
+
61
+ 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.
62
+
63
+ ### Untracked paths
64
+
65
+ `-u/--untracked` follows git status:
66
+
67
+ | Value | An untracked directory | An untracked file |
68
+ |---|---|---|
69
+ | `normal` (default) | one row, `build/`, with a file count | its own row, classified |
70
+ | `all` | expanded: every file gets a row and is classified | its own row, classified |
71
+ | `no` | not listed | not listed |
72
+
73
+ ```console
74
+ $ git-dirty-triage --prefix build
75
+ checkout is 7 commits behind origin/main
76
+ 1 untracked entry
77
+ 1 untracked_dir untracked directory, not expanded
78
+ untracked_dir build/ 3 file(s)
79
+
80
+ $ git-dirty-triage --prefix build --untracked all
81
+ checkout is 7 commits behind origin/main
82
+ 3 untracked entries
83
+ 3 new not on the remote
84
+ new 0 min ago build/a.log
85
+ new 0 min ago build/cache/b.log
86
+ new 0 min ago build/cache/c.log
87
+ ```
88
+
89
+ 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.
90
+
91
+ ### Print only the unpublished paths
92
+
93
+ ```console
94
+ $ git-dirty-triage --print-unpublished
95
+ merge.txt
96
+ new.txt
97
+ ```
98
+
99
+ 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:
100
+
101
+ ```console
102
+ $ git-dirty-triage --print-unpublished | while IFS= read -r p; do git add -- "$p"; done
103
+ ```
104
+
105
+ ### Commit the unpublished paths on top of the remote tip, without pushing
106
+
107
+ ```console
108
+ $ git-dirty-triage --commit-unpublished -m "local work"
109
+ committed 2 path(s) as 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e on top of origin/main
110
+ ref: refs/git-dirty-triage/main
111
+ push: not pushed
112
+ next: git push origin 08627b9a8f3ccfca858b1c32dd5bc5ac2135915e:refs/heads/main
113
+ ```
114
+
115
+ 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.
116
+
117
+ 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.
118
+
119
+ 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.
120
+
121
+ ### Files touched by local-only commits
122
+
123
+ `--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.
124
+
125
+ ```console
126
+ $ git-dirty-triage --ahead
127
+ checkout is 7 commits behind origin/main
128
+ 1 path touched by local-only commits: 0 already published, 1 unpublished, 0 need a decision
129
+ 1 new not on the remote
130
+ new 0 min ago notes.txt
131
+ ```
132
+
133
+ 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.
134
+
135
+ ### One directory or file
136
+
137
+ ```console
138
+ $ git-dirty-triage --prefix src --prefix README.md
139
+ ```
140
+
141
+ `--prefix` limits the listing itself, not only the report, so a unit costs what its own paths cost. Prefixes are repo-relative.
142
+
143
+ ### Machine-readable output
144
+
145
+ ```console
146
+ $ git-dirty-triage --json
147
+ {"repo": "/tmp/demo/shared", "ref": "origin/main", "behind": 7, "mode": "worktree",
148
+ "counts": {"identical": 2, "stale": 1, "contained": 1, "new": 1, "differs_clean": 1,
149
+ "differs_conflict": 1, "untracked_dir": 1},
150
+ "summary": {"paths": 8,
151
+ "tracked": {"paths": 5, "published": 3, "unpublished": 1, "decide": 1, "deleted": 0, "skipped": 0},
152
+ "untracked": {"entries": 3, "published": 1}},
153
+ "paths": [{"path": "conflict.txt", "class": "differs_conflict", "age_min": 0,
154
+ "reason": "1 unique line(s)", "untracked": false, "files": null}, …]}
155
+ ```
156
+
157
+ (Shown wrapped and shortened; the command prints one line.)
158
+
159
+ Every row carries `untracked` and `files`; `files` is the count on an `untracked_dir` row and `null` elsewhere.
160
+
161
+ `--commit-unpublished --json` prints a receipt instead: `status`, `commit`, `parent`, `ref`, `files`, `paths`, `pushed` and the `push` command, or `{"status": "nothing_to_commit"}`.
162
+
163
+ ### Exit status
164
+
165
+ `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`.
166
+
167
+ ## How it decides
168
+
169
+ | Class | Working bytes against the remote tip | Unpublished? |
170
+ |---|---|---|
171
+ | `identical` | same blob as remote | no |
172
+ | `stale` | equal to an earlier published version of the path | no |
173
+ | `contained` | every non-blank line already exists in the remote file | no |
174
+ | `new` | the remote has no file at this path | yes |
175
+ | `differs_clean` | unique lines, and a three-way merge with `HEAD` as base is clean | yes |
176
+ | `differs_conflict` | unique lines, and the same merge conflicts | no — a decision |
177
+ | `differs_binary` | binary, and the remote blob is unchanged since `HEAD` | yes, whole file |
178
+ | `deleted` | removed in the working tree | reported only |
179
+ | `untracked_dir` | untracked directory under `--untracked normal` | one row; never hashed, printed or committed |
180
+ | `skipped` | not a plain file (symlink, path with a newline) | reported only |
181
+
182
+ A clean merge whose result equals the remote bytes is `contained`: the path only lags.
183
+
184
+ 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).
185
+
186
+ ## A real example
187
+
188
+ 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.
189
+
190
+ ```console
191
+ $ bash examples/make-demo.sh
192
+ demo repo: /tmp/git-dirty-triage-demo/shared
193
+ $ cd /tmp/git-dirty-triage-demo/shared && git-dirty-triage
194
+ ```
195
+
196
+ ## When you do not need it
197
+
198
+ - **Each agent has its own clone or worktree.** Every checkout then tracks the remote, and `git status` is already the truth.
199
+ - **The checkout is up to date with the remote.** Same reason.
200
+ - **A single writer, no concurrent publication.** Nothing is published behind your back.
201
+ - **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.
202
+
203
+ You need it when a checkout is deliberately behind and still has edits — the state a shared multi-agent checkout ends up in.
204
+
205
+ ## Limits
206
+
207
+ - **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.
208
+ - **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.
209
+ - **"Unpublished" is not "wanted".** A cleanly merging edit is unpublished by definition; deciding whether it belongs in a commit is yours.
210
+ - **Binary files are all-or-nothing**, and only when the remote copy has not changed since HEAD; otherwise the path needs a decision.
211
+ - **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.
212
+ - **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.
213
+ - **`--ahead` needs a merge-base.** A depth-1 shallow clone has none.
214
+ - **Empty repositories are not supported**; there is no remote tip to compare with.
215
+ - **Tested on macOS (Apple silicon, Python 3.12).** The code uses only the standard library and `git`; Linux and Windows are untested — reports welcome.
216
+ - **Very large dirty sets** cost one `cat-file` and one `log` per genuinely differing file; only the identical and new paths are cheap.
217
+
218
+ There is no configuration file and no environment variable. Every default is a flag: `--repo`, `--remote`, `--branch`, `--untracked`.
219
+
220
+ ## Agents
221
+
222
+ If you are an AI agent asked to publish work from a shared checkout, read [AGENTS.md](https://github.com/elfenomenokim/git-dirty-triage/blob/main/AGENTS.md). The Claude Code skill lives in [`skill/git-dirty-triage/SKILL.md`](https://github.com/elfenomenokim/git-dirty-triage/blob/main/skill/git-dirty-triage/SKILL.md); install it by copying that folder to `~/.claude/skills/git-dirty-triage/`.
223
+
224
+ ## License
225
+
226
+ MIT — see [LICENSE](https://github.com/elfenomenokim/git-dirty-triage/blob/main/LICENSE).
@@ -0,0 +1,48 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "git-dirty-triage"
7
+ version = "0.1.0"
8
+ description = "Tell which modified files in a lagging or shared Git checkout are really unpublished, and commit only those on top of the remote tip without pushing."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "El Fenomeno" }]
14
+ keywords = [
15
+ "git",
16
+ "dirty",
17
+ "checkout",
18
+ "monorepo",
19
+ "multi-agent",
20
+ "agents",
21
+ "three-way-merge",
22
+ "cli",
23
+ ]
24
+ classifiers = [
25
+ "Development Status :: 4 - Beta",
26
+ "Environment :: Console",
27
+ "Intended Audience :: Developers",
28
+ "Operating System :: OS Independent",
29
+ "Programming Language :: Python :: 3",
30
+ "Programming Language :: Python :: 3 :: Only",
31
+ "Topic :: Software Development :: Version Control :: Git",
32
+ "Topic :: Utilities",
33
+ ]
34
+ dependencies = []
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/elfenomenokim/git-dirty-triage"
38
+ Repository = "https://github.com/elfenomenokim/git-dirty-triage"
39
+ Issues = "https://github.com/elfenomenokim/git-dirty-triage/issues"
40
+
41
+ [project.scripts]
42
+ git-dirty-triage = "git_dirty_triage.cli:main"
43
+
44
+ [tool.setuptools]
45
+ package-dir = { "" = "src" }
46
+
47
+ [tool.setuptools.packages.find]
48
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,47 @@
1
+ """In a lagging shared checkout, tell which modified files are really unpublished.
2
+
3
+ from git_dirty_triage import classify, summarize
4
+
5
+ top, rows = classify("/path/to/checkout", "origin/main")
6
+ print(summarize(rows))
7
+ """
8
+
9
+ from .classify import (
10
+ DECISION_CLASSES,
11
+ PUBLISHED_CLASSES,
12
+ UNPUBLISHED_CLASSES,
13
+ classify,
14
+ classify_ahead,
15
+ counts_by_bucket,
16
+ summarize,
17
+ )
18
+ from .commit import build_commit, commit_unpublished, unpublished_rows
19
+ from .gitio import git, is_text, out, pathspecs_for, resolve_ref, short_path, toplevel, under
20
+ from .report import format_report, json_report, summary_line
21
+
22
+ __version__ = "0.1.0"
23
+
24
+ __all__ = [
25
+ "__version__",
26
+ "PUBLISHED_CLASSES",
27
+ "UNPUBLISHED_CLASSES",
28
+ "DECISION_CLASSES",
29
+ "classify",
30
+ "classify_ahead",
31
+ "summarize",
32
+ "counts_by_bucket",
33
+ "unpublished_rows",
34
+ "build_commit",
35
+ "commit_unpublished",
36
+ "format_report",
37
+ "json_report",
38
+ "summary_line",
39
+ "git",
40
+ "out",
41
+ "toplevel",
42
+ "is_text",
43
+ "resolve_ref",
44
+ "pathspecs_for",
45
+ "short_path",
46
+ "under",
47
+ ]
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())