Repository navigation
snapshot: fails on git < 2.45 — unknown option 'sparse' (git add --all --sparse) #52953
Description
Summary
Snapshot / checkpoint capture fails on any worktree whose git is older than 2.45, because opencode invokes git add --all --sparse (the --sparse flag was added to git add in Git 2.45). Every edit logs failed to capture snapshot and no checkpoint/revert is ever created.
Environment
- opencode: v2.0.18
- Worktree OS: Debian 11 (bullseye), git 2.30.2, inside a devcontainer
- Worktree:
/var/www
Evidence
From /home/dev/.local/share/opencode/log/opencode.log (this repeats on every change, dozens of times per minute while the agent edits):
message="spawning process" command=git args="[\"--git-dir\",\"/home/dev/.local/share/opencode/snapshot/<repo>/<rev>\",\"--work-tree\",\"/var/www\",\"add\",\"--all\",\"--sparse\",\"--pathspec-from-file=-\",\"--pathspec-file-nul\"]" cwd=/var/www
level=WARN message="failed to capture snapshot" cause="Git.OperationError: error: unknown option `sparse'\nusage: git add [<options>] [--] <pathspec>...\n..."
Raw error:
Git.OperationError: error: unknown option `sparse'
usage: git add [<options>] [--] <pathspec>...
Expected
Snapshot/checkpoint capture works, or degrades gracefully (e.g. without --sparse).
Actual
Capture fails for every change; checkpoints and revert are never available in that environment.
Suggested fix
- Detect
git --versionand, when it is< 2.45, omit--sparse(plaingit add --all ...). - Or retry once without
--sparsewhen this specific error is returned. - Note this is not a rare/old environment: Debian 11 ships git 2.30 and Debian 12 ships 2.39, so many devcontainers and CI images are affected.
Reproduction
- Run opencode against a worktree inside a container/OS with
git < 2.45(e.g. Debian 11, git 2.30.2). - Make any edit through the agent.
- Observe
failed to capture snapshot: error: unknown option 'sparse'and the absence of checkpoints/revert.
Activity
github-actions commentedon Oct 3, 2026
This issue might be a duplicate of existing issues. Please check:
sparseoption used bygit add, causing snapshot capture to fail.Francis13CR commentedon Oct 3, 2026
Thanks. Re #21302: like #33510, that one was auto-closed by the inactivity bot ("automatically closed after 60 days of no activity… if the issue is still relevant please open a new one"), not fixed. This is that re-report — and it's still reproducible on v2.0.18.
Two useful details from #21302 worth carrying forward:
WARN: in some paths it may abort/interrupt the turn. If so, this is not just "no checkpoints" — it can end a session.My environment for reference: opencode v2.0.18, Debian 11 (bullseye) / git 2.30.2, worktree
/var/www. Still getsfailed to capture snapshot: Git.OperationError: error: unknown option 'sparse'on every change, with no checkpoint/revert.So: still relevant, still reproducible, and potentially tied to session interruptions rather than only to missing snapshots.
Darsh-Nandu commentedon Oct 6, 2026
I'd like to take this if it's not already being worked on. Plan: check the git version once (
git --version) and leave out--sparsefrom the snapshotgit addwhen git is older than 2.45, in bothpackages/opencode/src/snapshot/index.tsandpackages/core/src/git.ts, with a test for the version check.mujiannan commentedon Oct 9, 2026
Independent confirmation from a third platform: Windows 11, Git for Windows 2.28.0, opencode 1.18.32. The exact invocation the snapshot service runs (
git add --all --sparse --pathspec-from-file=- --pathspec-file-nul) exits 129 before the upgrade, and exit 0 after 2.28.0 -> 2.55.0.FWIW, from a user's side I'd say upgrading git (>= 2.45) is the whole fix — I don't think opencode needs a compat fallback for this. Windows is an easy place to hit it because Git for Windows does not self-update: this box had been sitting on 2.28.0 from 2020 with nobody noticing. Ten-second check:
git --version,git add -h | grep sparse.(On 1.18.x the log line is
failed to add snapshot files+exitCode=129, notfailed to capture snapshot— grepping the newer wording finds nothing.)opencodejr commentedon Oct 27, 2026
Thanks for the detailed report and logs. Using real git 2.30.2 (the version in Debian 11), I reproduced this on v2.0.18: every snapshot capture ran
git add --all --sparse --pathspec-from-file=- --pathspec-file-nul, which failed witherror: unknown option `sparse', so no checkpoint was ever created.I ran the same steps on the latest
dev(45b53fe) and couldn't reproduce it there. Snapshot capture was rewritten (#51996) and no longer usesgit add --sparse; with git 2.30.2 the snapshot is now created without errors. The change appears to have shipped in v2.0.26, so upgrading should fix it (bun add -g @opencode/cli@latestor your usual install method).The bot will close this issue in 1 day unless you reply that it still happens on a newer version.
opencodejr commentedon Oct 28, 2026
Closing this as completed, since there's been no reply since my last comment. With git 2.30.2 the snapshot failure (
unknown option `sparse') happened on v2.0.18 but not on the latestdev(45b53fe). The snapshot rewrite in #51996 removedgit add --sparse, and that change appears to have shipped in v2.0.26. Upgrading to the latest release should fix it.If snapshots still fail with git older than 2.45 on a newer version, please comment here or open a new issue with your
opencode --version,git --versionand the log lines. Thanks again for the clear report!