sparse index: support skip-worktree setup required by add --ignore-missing

[genedna]

Summary

Libra cannot construct or operate on Git's skip-worktree sparse-index state used by upstream t/t3705-add-sparse-checkout.sh test 13. In particular, update-index --force-remove and update-index --skip-worktree are rejected, and sparse-checkout is not implemented. As a result, the target command add --dry-run --ignore-missing sparse_entry is never reached in the upstream-compatible scenario.

This is tracked by libra-testcases as TC-0010 (git add --dry-run --ignore-missing warn on sparse path).

Versions

• Libra: 0.22.19
• Git control: 2.55.0.782.g1630431f32
• Platform: macOS/Darwin, case-insensitive APFS
• Upstream source: Git commit 1630431f326e15fcde608827b5ff38422528eb59, t/t3705-add-sparse-checkout.sh lines 10-25 and 140-147

Reproduction

set -eu

work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT

"$LIBRA" init -q --initial-branch=main "$work/repo"
cd "$work/repo"

"$LIBRA" update-index --force-remove sparse_entry
printf 'sparse\n' >sparse_entry
"$LIBRA" add sparse_entry
"$LIBRA" update-index --skip-worktree sparse_entry

Actual behavior

$ libra update-index --force-remove sparse_entry
error: unexpected argument '--force-remove' found
Error-Code: LBR-CLI-002
exit=129

$ libra update-index --skip-worktree sparse_entry
error: unexpected argument '--skip-worktree' found
Error-Code: LBR-CLI-002
exit=129

$ libra sparse-checkout init --no-cone
libra: 'sparse-checkout' is not a libra command. See 'libra --help'.
Error-Code: LBR-CLI-001
exit=129

The original full test run stops at update-index --force-remove sparse_entry; it never executes add --dry-run --ignore-missing sparse_entry.

Expected behavior

Git supports the setup:

git update-index --force-remove sparse_entry        # exit 0
git add sparse_entry                                # exit 0
git update-index --skip-worktree sparse_entry       # exit 0
git config core.sparseCheckout false                # exit 0
git commit --allow-empty -m 'ensure sparse_entry exists at HEAD'

After removing the working-tree path, Git runs:

git add --dry-run --ignore-missing sparse_entry

The command exits with a regular non-zero status, leaves the skip-worktree index entry unchanged and unstaged, and reports that the path is outside the sparse-checkout definition with --sparse/sparsity-rule advice.

Acceptance criteria

1. Support update-index --force-remove and update-index --skip-worktree for the sparse-entry setup, or provide Git-compatible behavior through the mapped CLI surface.
2. Support the sparse-checkout behavior required for a skip-worktree entry, including the core.sparseCheckout=false scenario used above.
3. For add --dry-run --ignore-missing on a missing skip-worktree path, return a regular non-zero status, preserve the index entry and staged diff state, and emit a diagnostic identifying the sparse path and remediation.
4. Product-specific error-code, hint, or JSON formatting is acceptable, but the target command must actually be reached in the upstream scenario.

Test tracking

• cases/tc0010-add-dry-run-sparse-path/tc0010-add-dry-run-sparse-path.sh
• libra-git-testcases-spec.md TC-0010
• results/libra-0.22.19/notes.md TC-0010
• libra-git-testcases-review.md TC-0010

[genedna]

TC-0033 update: sparse-entry setup also blocks add --renormalize coverage

TC-0033 in genedna/libra-testcases maps to pinned Git 2.55.0.782.g1630431f32, t/t3705-add-sparse-checkout.sh#12 (git add --renormalize does not update sparse entries).

The upstream test first creates a skip-worktree sparse entry with setup_sparse_entry, whose first command is:

git update-index --force-remove sparse_entry

Git control passes the complete sequence. Libra 0.22.19 stops before the target git add --renormalize sparse_entry command:

error: unexpected argument '--force-remove' found
Error-Code: LBR-CLI-002
exit=129

The add --renormalize behavior is therefore not independently tested. This is an additional consumer of the sparse-index/skip-worktree capability tracked here, alongside TC-0010. It is not a separate renormalize defect based on the current evidence.

Please include TC-0033 in the scope of this issue. Acceptance should cover the existing criteria for constructing a skip-worktree entry and reaching sparse-path add operations, then re-run t/t3705-add-sparse-checkout.sh#12 to verify that add --renormalize rejects the sparse path without changing the index and emits the expected sparse-path diagnostic semantics.

Run: tc0033-analysis-20260914-235724-libra failed at update-index --force-remove; the Git control run with the same ID passed.

[genedna]

TC-0043 update: add -A must preserve a missing skip-worktree entry

TC-0043 maps to pinned Git t/t3705-add-sparse-checkout.sh#3, git add -A does not remove sparse entries.

Git control 2.55.0.782.g1630431f32 creates a skip-worktree sparse_entry, removes the worktree file, writes an ignore rule, then runs git add -A. Git exits successfully with empty stderr and preserves the exact index entry.

Libra 0.22.19 fails in setup_sparse_entry before the target add -A command runs:

git update-index --force-remove sparse_entry
error: unexpected argument '--force-remove' found
Error-Code: LBR-CLI-002
exit=129

This is another consumer of the sparse-index/skip-worktree capability tracked here, not an independently observed add -A defect.

Please add this acceptance case after the skip-worktree setup works:

1. A missing worktree path with a skip-worktree index entry must survive add -A unchanged.
2. The command must exit 0 with empty stderr in the .gitignore scenario from upstream test replace mercury with git-internal #3.
3. Re-run the complete t/t3705-add-sparse-checkout.sh#3 sequence.

Run: tc0043-analysis-20260915-010441-libra failed at update-index --force-remove; the paired Git control run passed.

[genedna]

Adding TC-0046 to this issue's scope: the same setup_sparse_entry gap blocks
git add --refresh does not update sparse entries (t/t3705-add-sparse-checkout.sh
test #10). The target command add --refresh sparse_entry is never reached on the
libra track.

Where TC-0046 fails (recorded run final-0.22.19 and fresh re-run)

• git update-index --force-remove sparse_entry (first command of
  setup_sparse_entry) → libra exits 129 (LBR-CLI-002: "unexpected argument
  '--force-remove' found"); the && chain aborts, so add --refresh sparse_entry
  and the ls-files --debug mtime checks never execute.
• cmdlog for test feat: add option -F/--file for commit command #10 on the libra track contains exactly one git invocation
  (that update-index --force-remove, rc=129); the git control track runs the
  full setup (force-remove/add/skip-worktree/config/commit --allow-empty/
  rev-parse), then the tested add --refresh exits 1 with the sparse advice
  block and the test passes (ok 10).
• All tests in this file that call setup_sparse_entry (libra results.tsv rows
  2–21) fail at the same command. Test-case mappings affected by this one setup
  helper: TC-0043 (replace mercury with git-internal #3), TC-0046 (feat: add option -F/--file for commit command #10), TC-0052 ([r2cn] 替换 Libra 的 SQLite 为 Turso #11), TC-0033 (feat: add option -f/--force for tag command #12), TC-0010
  ([r2cn-测试任务]为 tag 命令添加 --force 参数 #13), TC-0034 ([r2cn-测试任务] libra show 命令的支持 #16) — TC-0046 is the add --refresh representative.
• Fresh two-track re-run 2026-09-15 (RUN_ID tc0046-analysis-20260915-120000,
  independent clone at repo HEAD fc95a58a): git=PASS, libra=FAIL, identical to
  the recorded excerpt (single rejected setup command).

TC-0046-specific acceptance criteria (once #490 lands)

With a repo where sparse_entry is a skip-worktree index entry (built via the
upstream-compatible setup_sparse_entry), libra must:

1. add --refresh sparse_entry exit as a regular failure (test_must_fail class;
   git exits 1) with stderr byte-equal to git's error_and_hint block:
   the "matched paths that exist outside of your sparse-checkout definition"
   header, the sparse_entry line, the three hint: lines including
   git config set advice.updateSparsePath false.
2. Leave the index untouched: git diff --staged -- sparse_entry empty
   (test_sparse_entry_unstaged), and ls-files --debug sparse_entry | grep mtime
   output identical before and after (git's --refresh does not update
   skip-worktree entries' cached stat).
3. Pass upstream t/t3705-add-sparse-checkout.sh feat: add option -F/--file for commit command #10 verbatim under the
   two-track harness (git control PASS).

TC tracking paths

• TC script: cases/tc0046-add-refresh-sparse/tc0046-add-refresh-sparse.sh
• Spec: libra-git-testcases-spec.md § "add --refresh" → TC-0046 (lines 1203–1231)
• Recorded verdict: results/libra-0.22.19/summary.tsv row TC-0046;
  results/libra-0.22.19/notes.md line 65;
  review section in libra-git-testcases-review.md (tc0046-add-refresh-sparse)
• Excerpts: results/libra-0.22.19/run-20260913-142055/excerpts/libra/TC-0046.log

[genedna]

Related issues

This issue is related to the following open issues (cross-linked):

• libra update-index: rejects the --index-info option/argument; rejects the --refresh option/argument; rejects the --skip-worktree option/argument #540: Mirrors: update-index --skip-worktree is the sparse-index prerequisite; sparse-index --skip-worktree prerequisite is the same update-index gap
• libra sparse-checkout: subcommand/option not recognized (LBR-CLI-001) #551: Mirrors: sparse-checkout / --skip-worktree setup is required

Linked to improve discoverability, triage, and tracking of shared root causes.