git-span 1.1.17 → 1.1.24
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.
- package/README.md +52 -39
- package/man/git-span.1 +2 -2
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,57 +1,70 @@
|
|
|
1
|
-
# git
|
|
1
|
+
# git-span
|
|
2
2
|
|
|
3
|
-
`git
|
|
3
|
+
`git-span` tracks implicit semantic dependencies: exact line ranges or whole files that must stay aligned even though no schema, type, test, or build step enforces the relationship.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Each span records its anchors and a compact, decision-relevant reason. Span declarations live under `.span/` as ordinary tracked repository data, and `git span drift` reports when their recorded content moves, changes, or disappears.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
cycle-safe positional repair; `--operation-id <uuid>` makes a delivery-unknown
|
|
14
|
-
repair replayable across processes. Failures leave stdout empty, while a valid
|
|
15
|
-
no-overlap query succeeds with an empty `spans` array. The complete schema,
|
|
16
|
-
token, failure, service, and recovery contract is in the
|
|
17
|
-
[command reference](../../plugins-claude/git-span/skills/git-span/references/command-reference.md#exact-batched-context).
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g git-span
|
|
11
|
+
git span --version
|
|
12
|
+
```
|
|
18
13
|
|
|
19
|
-
|
|
20
|
-
queries and falls back to the same strict in-process answer whenever the
|
|
21
|
-
watcher or service is unavailable. The released-binary
|
|
22
|
-
[acceptance harness](./scripts/context-acceptance.py) runs 31 samples in each
|
|
23
|
-
required warm cell. On the documented 2026-08-14 container run, warm context
|
|
24
|
-
p50/p95 improvement over the legacy process lifecycle was at least
|
|
25
|
-
78.2%/76.3% (clean) and reached 86.7%/90.0% (multi-span); cold bootstrap was 43.0 ms,
|
|
26
|
-
invalidated rebuild 42.7 ms, strict fallback 34.6 ms, and a journaled repair
|
|
27
|
-
136.1 ms. Root-switch and linked-worktree checks passed.
|
|
14
|
+
The package installs the native binary for supported Linux, macOS, and Windows hosts.
|
|
28
15
|
|
|
29
|
-
|
|
16
|
+
## Create a span
|
|
30
17
|
|
|
31
|
-
|
|
18
|
+
```bash
|
|
19
|
+
git span add checkout-request-flow \
|
|
20
|
+
src/client.ts#L10-L40 \
|
|
21
|
+
src/server.ts#L20-L64
|
|
32
22
|
|
|
33
|
-
|
|
23
|
+
git span why checkout-request-flow \
|
|
24
|
+
"The server contract is authoritative for the request fields the client sends."
|
|
34
25
|
|
|
35
|
-
|
|
26
|
+
git add .span
|
|
27
|
+
git commit -m "Record checkout request coupling"
|
|
28
|
+
```
|
|
36
29
|
|
|
37
|
-
A
|
|
30
|
+
A useful why is one or two present-tense clauses that state the shared relationship and any decisive authority, invariant, intentional difference, or lifecycle gate.
|
|
38
31
|
|
|
39
|
-
|
|
32
|
+
## Review and reconcile
|
|
40
33
|
|
|
41
|
-
|
|
34
|
+
```bash
|
|
35
|
+
git span list
|
|
36
|
+
git span show checkout-request-flow
|
|
37
|
+
git span tree checkout-request-flow
|
|
38
|
+
git span history checkout-request-flow
|
|
39
|
+
git span drift
|
|
40
|
+
```
|
|
42
41
|
|
|
43
|
-
|
|
42
|
+
`git span drift --fix` repairs mechanically safe movement and whitespace-only changes. Meaning-changing drift remains visible for review. Refresh an unchanged anchor address with `git span add`; move an anchor atomically with `git span replace`.
|
|
44
43
|
|
|
45
|
-
|
|
46
|
-
- Machine-readable output — commands whose effective output format is machine-readable (`--porcelain`, `--oneline`, `--format` other than human, `context`, `merge-driver`) never engage the check.
|
|
47
|
-
- Non-TTY stdout — piped or scripted invocations (including the VS Code extension and the agent-hooks shell-outs) are silent regardless of the other layers.
|
|
48
|
-
- Hidden internal subcommands (`__context-service`, `__update-check`) never engage or remind.
|
|
44
|
+
`git span drift` exits nonzero when actionable drift remains, making it suitable for CI:
|
|
49
45
|
|
|
50
|
-
|
|
46
|
+
```yaml
|
|
47
|
+
- uses: actions/checkout@v4
|
|
48
|
+
with:
|
|
49
|
+
fetch-depth: 0
|
|
50
|
+
- run: npm install -g git-span
|
|
51
|
+
- run: git span drift
|
|
52
|
+
```
|
|
51
53
|
|
|
52
|
-
##
|
|
54
|
+
## Agent and editor integrations
|
|
53
55
|
|
|
54
|
-
|
|
56
|
+
Git-span ships integrations for Claude Code, OpenAI Codex, OpenCode, and Antigravity. Their hooks heal positional drift after supported tool calls, surface semantic drift as context, and advise before commits with unresolved span debt. The VS Code extension provides an interactive editor for `.span/` declarations.
|
|
55
57
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
+
Install integrations separately after putting `git span` on `PATH`. See [git-span.com](https://git-span.com) for current host-specific instructions and limitations.
|
|
59
|
+
|
|
60
|
+
## Automation
|
|
61
|
+
|
|
62
|
+
Commands with `--format json` provide machine-readable output. `git span context <address>... --format json` returns an exact repository snapshot for paths and inclusive line ranges, including selected spans, whys, current status, and resolver sources. Published JSON Schemas and their contracts are documented at [git-span.com](https://git-span.com).
|
|
63
|
+
|
|
64
|
+
## Documentation
|
|
65
|
+
|
|
66
|
+
- [git-span.com](https://git-span.com) — installation, concepts, command reference, agent integration, and CI guidance
|
|
67
|
+
|
|
68
|
+
## License
|
|
69
|
+
|
|
70
|
+
MIT — Copyright © 2026 Goodfoot Media LLC.
|
package/man/git-span.1
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
.\" GENERATED by gen-manpage. Do not edit by hand.
|
|
2
2
|
.ie \n(.g .ds Aq \(aq
|
|
3
3
|
.el .ds Aq '
|
|
4
|
-
.TH git-span 1 "git-span 1.1.
|
|
4
|
+
.TH git-span 1 "git-span 1.1.24"
|
|
5
5
|
.ie \n(.g .ds Aq \(aq
|
|
6
6
|
.el .ds Aq '
|
|
7
7
|
.SH NAME
|
|
@@ -148,7 +148,7 @@ Print this message or the help of the given subcommand(s)
|
|
|
148
148
|
.ie \n(.g .ds Aq \(aq
|
|
149
149
|
.el .ds Aq '
|
|
150
150
|
.SH VERSION
|
|
151
|
-
v1.1.
|
|
151
|
+
v1.1.24
|
|
152
152
|
.SH EXAMPLES
|
|
153
153
|
Anchor a new span alongside a code change:
|
|
154
154
|
.PP
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "git-span",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.24",
|
|
4
4
|
"bin": "bin/git-span.exe",
|
|
5
5
|
"man": [
|
|
6
6
|
"man/git-span.1"
|
|
@@ -27,11 +27,11 @@
|
|
|
27
27
|
"scripts/postinstall.js"
|
|
28
28
|
],
|
|
29
29
|
"optionalDependencies": {
|
|
30
|
-
"git-span-darwin-arm64": "1.1.
|
|
31
|
-
"git-span-darwin-x64": "1.1.
|
|
32
|
-
"git-span-linux-arm64": "1.1.
|
|
33
|
-
"git-span-linux-x64": "1.1.
|
|
34
|
-
"git-span-win32-x64": "1.1.
|
|
30
|
+
"git-span-darwin-arm64": "1.1.24",
|
|
31
|
+
"git-span-darwin-x64": "1.1.24",
|
|
32
|
+
"git-span-linux-arm64": "1.1.24",
|
|
33
|
+
"git-span-linux-x64": "1.1.24",
|
|
34
|
+
"git-span-win32-x64": "1.1.24"
|
|
35
35
|
},
|
|
36
36
|
"repository": {
|
|
37
37
|
"type": "git",
|