You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: README.md
+4-3Lines changed: 4 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -250,12 +250,13 @@ Commit a single compressed file to your repo and your teammates skip the reindex
250
250
-**Best** (`zstd -9` + index strip + `VACUUM INTO`) — written on explicit `index_repository`
251
251
-**Fast** (`zstd -3`) — written by the watcher for low-latency incremental updates
252
252
-**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:
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.
259
260
-**Optional**: never committed unless you want it. Add `.codebase-memory/` to `.gitignore` if you prefer everyone to reindex from scratch.
260
261
261
262
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