Skip to content

Commit 4b844b7

Browse files
angusgastleclaude
andcommitted
docs: apply review feedback on team artifact LFS guidance
Address maintainer review on PR #1697: - LFS pattern goes in the repo-root .gitattributes; the auto-created .codebase-memory/.gitattributes (bare graph.db.zst, merge=ours) is kept as-is, since a slash-containing pattern inside it would anchor to .codebase-memory/ and match nothing - Lead with commit cadence as the cheaper fix; LFS is for teams that need the artifact to move on every commit - Name the LFS costs: metered storage/bandwidth, no pruning without support, and teammates without `git lfs install` fall back to a full reindex Co-Authored-By: Claude Code <noreply@anthropic.com>
1 parent 9baa0a8 commit 4b844b7

1 file changed

Lines changed: 4 additions & 3 deletions

File tree

README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -250,12 +250,13 @@ Commit a single compressed file to your repo and your teammates skip the reindex
250250
- **Best** (`zstd -9` + index strip + `VACUUM INTO`) — written on explicit `index_repository`
251251
- **Fast** (`zstd -3`) — written by the watcher for low-latency incremental updates
252252
- **Bootstrap**: when no local DB exists but the artifact is present, `index_repository` imports the artifact first, then runs incremental indexing — avoiding the full reindex cost
253-
- **No merge pain**: a `.gitattributes` line with `merge=ours` is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact
254-
- **Use Git LFS for team repos**: the artifact can be >20MB of binary that regenerates on every re-index. Committing it plainly stores a full new blob each time — a repo can reach gigabytes of bloat within a normal week of indexing. For any team-shared repo, register the artifact with Git LFS instead of committing it inline. Replace the auto-created `merge=ours` line in `.gitattributes` with the LFS tracking pattern:
253+
- **No merge pain**: a `.codebase-memory/.gitattributes` line with `merge=ours` is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact
254+
- **Commit it deliberately**: the artifact is rewritten on every index, including the watcher's Fast tier, and git stores each rewrite as a full new blob. Committing every refresh is what turns a 20 MB file into gigabytes of history — one team reached ~6 GB across ~350 commits of this single path. Pick a cadence (a release, a milestone, a nightly job) rather than committing every save.
255+
- **Git LFS, if it must move on every commit**: track it from the **repo-root** `.gitattributes` and leave the auto-created `.codebase-memory/.gitattributes` in place — the nearer file goes on supplying `merge=ours`, and only `filter` comes from the root:
255256
```gitattributes
256257
.codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
257258
```
258-
If you are migrating an existing repo where the artifact was already committed plainly, strip the historical blobs first with `git-filter-repo` — one team's un-LFS'd history accumulated ~7GB before a history rewrite reclaimed it. LFS keeps clones small and avoids the "same file, hundreds of versions" bloat the plain commit path produces.
259+
Track only the `.zst`; `artifact.json` is small and carries the schema version. The attribute applies to future commits only, so a repo that already has the blobs in history needs `git-filter-repo` to rewrite them first. Two costs to weigh before adopting it: GitHub meters LFS storage and bandwidth, and its objects cannot be pruned without contacting support; and every teammate needs `git lfs install` — without it their checkout leaves a pointer file where the artifact should be, the integrity-checked import refuses it, and they fall back to a full reindex.
259260
- **Optional**: never committed unless you want it. Add `.codebase-memory/` to `.gitignore` if you prefer everyone to reindex from scratch.
260261

261262
The result is similar in spirit to graphify's `graphify-out/` directory, but as a single compressed file with explicit two-tier export, integrity-checked import, and zero merge friction.

0 commit comments

Comments
 (0)