Partlet

4.7 KiB ยท raw

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# git work

A shared interface for inspecting commit history, changed files, and patches.
Requires Bash 4+ and Git with `--diff-merges=first-parent` support. No network
access, Python dependencies, package installation, or repository setup required.

## Commands

```bash
git work log                         # compact history from HEAD
git work log main..HEAD               # selected history
git work log --work                   # outstanding commits and published boundary
git work log -n 10                    # ten recent commits

git work files                       # files changed in HEAD
git work files abc123 --status        # specific commit, including change types
git work files HEAD~3..HEAD --stat     # statistics for each selected commit
git work files --work                 # net changes in unpublished work

git work diff                        # HEAD's patch
git work diff abc123                  # a specific commit's patch
git work diff main..HEAD --word       # individual word diffs for a range
git work diff --work                  # aggregate unpublished diff
git work diff --work --word -- src/   # word diff filtered to paths

git work files --staged --status
git work diff --unstaged
git work status                      # branch, baseline, outstanding count, status
git work base                        # machine-readable baseline ref
```

Scope options and positional revisions are mutually exclusive. Git revision
syntax includes single commits, ranges, and exclusions such as `HEAD^!`.
Files/diff default to the one HEAD commit; log defaults to history from HEAD.
Ranges produce individual commit outputs, oldest first. Merge patches compare
against the first parent, including when paths are supplied. Root patches compare
against an empty tree. Empty commit selections produce no output.

The files view defaults to names; `--status` and `--stat` are alternative views.
Diff defaults to line patches; `--word` uses Git's colored word diff. Paths after
`--` are relative to the directory where you invoked the command. Native Git
configuration controls rename detection, diff algorithms, and ordinary coloring.
Only the options documented by `git work --help` are supported.

`--work` includes committed changes plus net staged/unstaged changes in tracked
files. Opposing changes can cancel out in the aggregate diff while the log still
shows both commits. Untracked files appear in `status`; add them to the index to
include them in diffs. Staged means index versus HEAD (empty tree before the first
commit); unstaged means working tree versus index.

## Published baseline

For `--work`, `status`, and `base`, `--base REF` overrides `git config work.base`.
Explicit invalid refs fail rather than falling back. Otherwise:

1. Identify the integration branch from `work.mainBranch`, a valid locally cached
   `origin/HEAD`, then existing `main` or `master` refs in that order.
2. On a feature branch or detached HEAD, use the local integration branch,
   falling back to `origin/<branch>`.
3. On the integration branch, use its valid remote-tracking upstream, falling
   back to `origin/<branch>`. A local upstream is not evidence of publication.
4. With no baseline, all history is unpublished. With an unrecognizable integration
   branch, configure `work.mainBranch` or explicitly choose a base.

For example:

```bash
git config work.mainBranch trunk
git config work.base upstream/main
git work diff --work --base release
```

The log heading identifies the published baseline tip. The graph's `o` marks
published ancestry connecting to outstanding commits; that boundary can be older
than the baseline tip. When caught up, the baseline tip is always displayed as
context, even when a path filter would exclude it. A log limit or a path filter
can omit graph boundaries; the heading still identifies the baseline.

Aggregate diffs use the common ancestor of HEAD and the baseline, avoiding
unrelated changes made on the integration branch after branching. Missing or
multiple common ancestors produce an error asking for an explicit base. Shallow
history may require fetching more history manually. An unborn HEAD with an
existing baseline cannot produce an aggregate diff until ancestry exists.

Nothing fetches automatically: remote refs represent the last locally observed
remote state. Publication is based on ancestry, not patch matching; squash merges
and cherry-picks cannot automatically prove an old commit has landed. The helper
never writes refs, objects, the index, or working files itself; configured Git
external diff tools retain their normal behavior.

`base` prints a full ref name for an automatically selected base, or the exact
explicit revision. If there is no baseline it prints a notice on stderr and exits
1. Usage and baseline errors exit 2; other Git errors retain Git's exit status.