A Git sparse checkout can make files disappear from your working tree, but that does not mean Git deleted them from history. In fact, Git’s documented behavior is to leave skip-worktree files intact in the commit. A naïve “green” result (clean status or diff) can mask a missing file. This playbook defines a strict contract for commit completeness and describes isolated tests with pinned versions to ensure the intended file remains in the commit tree. The approach follows the evidence-led style of Refonte Learning’s technical validation playbooks. The goal is a verifiable gate: if a file is hidden by sparse-checkout, the release is only ACCEPTED if we can show the file’s blob is still in the commit, otherwise REPAIR/HOLD. We explicitly define expected inputs and outputs, use synthetic commits and fixtures, record each test’s evidence, and conclude with an explicit decision (ACCEPT, REPAIR, RERUN or HOLD) for the release.
Define the acceptance contract
The first step is to declare exactly what outcome is required. In this case, our contract is simple but strict: the commit under test must contain the intended file path with its expected content, even if it was missing from the working directory due to sparse-checkout. We treat any attempt to rely solely on a clean Git status or diff as insufficient. A clean working tree does not prove completeness if a skip-worktree file is missing. Thus we require explicit evidence from git ls-tree that the file is in the commit. We use git ls-files separately to inspect the index.
Concretely, our expected-case manifest (see below) lists the files that should appear in the commit and their expected blobs. The acceptance condition is that the actual commit’s tree contains all those paths. We draw from Git’s documented semantics: setting skip-worktree on a file “instructs Git to ignore the absence of the file” and “not have its absence recorded in commits”. In other words, hiding a file by sparse-checkout should not delete it from the commit. We use this as our oracle: the skip-worktree bit means Git should still treat the file as present. If our tests show the file’s blob is present in HEAD, we ACCEPT. If it is missing or altered, we will seek repair or hold the release.
We also define failure conditions. For example, if a file is truly removed (via git rm) but our manifest still expects it, that is a violation. We prepare to treat unexpected deletions as a broken contract. As in the release-file validation playbook, we declare the expected file set before inspection. For this fixture, missing or altered required files violate the contract; unrelated extra files are outside its scope. The release gate is stricter than a green status: we will only call a case ACCEPT if the evidence ledger shows every intended file is confirmed in the commit. Otherwise, we classify the outcome as REPAIR or HOLD, according to our decision matrix below.
Capture the baseline and pin versions
Before any tests, we capture the base environment. That means freezing tool versions and initial state so the experiment is reproducible. For example, we note:
$ git --version
git version 2.56.0
# EXPECTED / NOT EXECUTED (pinned lab version)
We run on a known OS and shell (e.g. Linux, Bash). We create a disposable directory and disable system and global Git configuration to isolate results:
$ lab_dir=$(mktemp -d)
$ cd "$lab_dir"
$ unset GIT_CONFIG
$ export GIT_CONFIG_NOSYSTEM=1
$ export GIT_CONFIG_GLOBAL=/dev/null
$ git init -q -b master
$ git config user.name "Sparse Checkout Lab"
$ git config user.email "[email protected]"
$ git config core.excludesFile /dev/null
$ git config core.autocrlf false
$ git config commit.gpgsign false
# Disposable repository with synthetic author details.
We also record the initial HEAD of our baseline commit, and pin all relevant versions. This is analogous to the submodule validation playbook, which meticulously documented the Git and CPython versions used in its experiments. We ensure the Git docs are from the same release series we test (the sparse-checkout and ls-files manuals applicable to Git 2.56.0). All version and ID metadata goes into our final evidence manifest.
The baseline setup is: a new Git repo with at least one commit containing the file(s) we will test. We explicitly note the commit OID (via git rev-parse HEAD) to refer to it later. For example:
$ echo "baseline content" > foo.txt
$ git add foo.txt
$ git commit -m "Add foo.txt baseline"
# EXPECTED / NOT EXECUTED; illustrative commit ID:
[master (root-commit) 1234567] Add foo.txt baseline
1 file changed, 1 insertion(+)
$ baseline_oid=$(git rev-parse HEAD)
$ git rev-parse HEAD
1234567890abcdef1234567890abcdef12345678
All displayed outputs are EXPECTED / NOT EXECUTED for the pinned environment. Commit and blob IDs shown in transcripts are illustrative; record the actual IDs from each run.
Pin exact environment versions
We list exact versions of everything in use. For instance:
$ git --version
git version 2.56.0 # EXPECTED / NOT EXECUTED
$ bash --version
GNU bash, version 5.1.0(1)-release # EXPECTED / NOT EXECUTED
We record the Git repository’s environment (isolated configuration, no system or global excludes). This ensures anyone can rerun with the same results. Each experiment’s results will refer back to these pinned versions. Throughout the article, EXPECTED / NOT EXECUTED identifies illustrative output and planned verdicts, not measured results from the pinned environment.
Build the disposable controlled fixture
Now we construct the test scenario in a throwaway repo. We follow the pattern of a “controlled laboratory”: everything is synthetic and local. Each case starts from a fresh copy of the baseline; run deletion and modification controls in separate disposable fixtures. The fixture steps include:
· Initialize a new local repository (done above).
· Create a file foo.txt with known content, commit it (done above).
· Enable sparse-checkout to hide foo.txt.
· Verify the skip-worktree bit is set.
· Attempt to commit (or no-op commit) and then inspect HEAD.
For this individual root-level file, use non-cone patterns. Cone mode includes root-level files, so it cannot hide foo.txt in this fixture:
# Hide only foo.txt with explicit non-cone patterns.
$ git sparse-checkout set --no-cone -- '*' '!/foo.txt'
$ git sparse-checkout list
# EXPECTED / NOT EXECUTED:
*
!/foo.txt
$ git ls-files -v -- foo.txt
S foo.txt
# EXPECTED / NOT EXECUTED: S identifies skip-worktree.
The git ls-files -v output should prefix foo.txt with S (skip-worktree). This confirms the fixture is set: foo.txt is in the index but not on disk.
We isolate all commands so each invocation’s context is fresh. The submodule validation playbook checks that commands use the intended submodule repository. Here, we ensure core.sparseCheckout is true and only one working tree is involved. In short, by the end of setup, foo.txt is unmodified in Git’s view but missing from the working directory.
Author the independent expected-case manifest
We now write down what the commit should contain, independently of the Git commands. This manifest will list file paths and (optionally) blob checksums expected in HEAD. For our simple case:
Expected files in HEAD:
- foo.txt : content "baseline content"
In a real release gate, the manifest might come from a repository owner or spec. Here we hard-code it. The manifest is our oracle for acceptance: the commit must include all required files with exactly the expected contents. (If extra files appear, we ignore them; missing or modified files are errors.)
With the manifest, we can also define what is not allowed. For instance, if foo.txt were to disappear, that would break the contract. We will use this manifest to compare against Git’s output. This is the “approved input set” for the commit.
Specify a falsifiable negative control
For a negative control, we simulate a scenario that should fail to meet the contract. The simplest negative is to restore the full working tree, explicitly delete the file and commit, and verify that our checks detect the missing file. Example commands:
$ git sparse-checkout disable
$ git rm foo.txt
rm 'foo.txt'
$ git commit -m "Delete foo for negative control"
# EXPECTED / NOT EXECUTED; illustrative commit ID:
[master abcdef0] Delete foo for negative control
1 file changed, 1 deletion(-)
delete mode 100644 foo.txt
$ git ls-tree HEAD
# EXPECTED / NOT EXECUTED: no foo.txt entry.
In this case, git ls-tree HEAD will not list foo.txt. That should contradict our expected manifest (which includes foo.txt). Thus the negative control is falsifiable: our checks should flag this commit as violating the contract. This verifies that our tests catch missing files.
Reproduce the misleading green result
Next we show how the false-positive can occur. In a sparse-checkout context, hiding the file can make Git appear clean. For example, after the sparse patterns are set above, running:
$ git status --porcelain -uno
produces no output. In other words, the working tree is "clean" (no changes). A summary like git status or a zero-diff check would be green, even though foo.txt was removed from the working tree. This is misleading: a mere “no changes” would suggest everything is fine, but in fact the file is hidden. We reproduce this:
$ git status --porcelain -uno
# EXPECTED / NOT EXECUTED: no output; the tree appears clean.
This is the same pattern observed in other Refonte experiments: a superficial check passes while a deeper validation fails. We must not rely on status; instead, we use git ls-tree to inspect the commit and git ls-files to inspect the index.
At this point, a user might run git commit --allow-empty -m "Verify skip-worktree" or even git commit -m "Trivial". Since there are no tracked changes, Git will either do nothing or accept an empty commit. In any event, HEAD remains with the original commit (or a new empty commit), and we must inspect it. The green status was misleading; now we must do the real check.
Run a valid comparison case
To confirm our understanding, we also run a case where the file should be present. For example, disabling sparse-checkout or otherwise reintroducing the file:
$ git sparse-checkout disable
# EXPECTED / NOT EXECUTED: the full working tree is restored.
$ git status
Now foo.txt is back in the working directory and skip-worktree is cleared. We can do:
$ git status --porcelain
# EXPECTED / NOT EXECUTED: no output; foo.txt is present.
$ git ls-files -v foo.txt
H foo.txt
# EXPECTED / NOT EXECUTED: H means tracked, not skip-worktree.
We then verify the commit contents directly:
$ git ls-tree HEAD
# EXPECTED / NOT EXECUTED; illustrative blob ID:
100644 blob abcdef... foo.txt
The displayed hash is illustrative, but the key expected result is that foo.txt appears. This is our “true positive”: the commit does include the file. We compare the observed blob OID to our manifest: if they match, the case passes. The force-with-lease validation playbook also emphasizes using explicit expected commit identities. In their force-with-lease example, they insist on comparing OIDs of remote branches to a known good commit. Here we are similarly comparing the commit’s listed files against an independent expectation.
At the end of this case, we save any relevant outputs for the evidence ledger. For instance, we might save the output of git ls-tree to a file for audit. This ensures any failure can be replayed.
Preserve failure artifacts
If any case fails our checks, we preserve all artifacts for debugging. For example, if foo.txt were missing, we would keep the full output of git ls-tree HEAD, git ls-files -v, and any commit logs. In script form, we might have something like:
$ git ls-tree HEAD > evidence-foo-missing.txt
so we can later inspect it. The point is that every decision is backed by logged evidence: the diff, file listing, or errors that triggered the REPAIR/HOLD decision. This is similar to how the submodule validation playbook logged each identity check in submodule validation.
Exercise negative and boundary cases
We then explore edge conditions. One boundary case is if we manually write a file back in a skip-worktree slot. For example:
$ git sparse-checkout set --no-cone -- '*' '!/foo.txt'
$ echo "new content" > foo.txt
In a sparse checkout, Git clears the skip-worktree bit when it discovers that the file is present in the working tree. We expect that after this, git ls-files -v would show foo.txt with H (tracked and not marked skip-worktree), and explicitly staging the path with git add --sparse before committing would include the modified file (which would then violate the manifest if the content changed). We test that scenario:
$ git status --porcelain
M foo.txt # EXPECTED / NOT EXECUTED (foo.txt reappeared with modifications)
and if we commit:
$ git add --sparse -- foo.txt
$ git commit -m "Modify foo while skip-worktree"
# EXPECTED / NOT EXECUTED: the modified blob is committed.
This is a boundary case: skip-worktree got unset, so the file reappeared normally. Our ledger should treat it as a valid scenario (the file is present, but its content changed). We should catch the content mismatch as a failure, since our manifest expects the old content. This tests that we are paying attention to file content as well as presence.
Another comparison control is to try sparse patterns that do not hide any files (for example, git sparse-checkout set --no-cone -- '*') and confirm that our acceptance logic still holds (the file should of course be present and pass). We do so to be thorough.
Capture the per-case evidence ledger
We record each scenario in a ledger table, mapping case to evidence to outcome. The following results are EXPECTED / NOT EXECUTED for the pinned environment:
Case | Scenario | Expected evidence | Expected verdict |
1 (baseline) | No sparse-checkout (file present) | foo.txt in git ls-tree HEAD | ACCEPT |
2 (sparse-hidden) | skip-worktree on foo.txt | foo.txt still in git ls-tree | ACCEPT |
3 (explicit delete) | git rm foo.txt commit | foo.txt missing from tree | REPAIR/HOLD |
4 (modify & re-add) | Clear skip and change content | foo.txt in tree (wrong blob) | REPAIR |
5 (all included) | Patterns include all files | foo.txt in tree | ACCEPT |
In the evidence column we cite commands like git ls-tree HEAD that show file presence or absence. We use verdicts ACCEPT, REPAIR, HOLD as defined in other Refonte examples. (For example, the Ansible task-coverage playbook outlines a ledger that labels each check ACCEPT/REPAIR/HOLD.) Each case’s outcome is decided by whether the evidence matches our manifest. For instance, Case 3 shows a missing required file and so cannot be accepted without repair.
Reject incomplete evidence
If any expected evidence is missing or inconclusive, we err on the side of HOLD (incomplete). As the Ansible task-coverage playbook emphasizes, evidence must be explicit: any case with “absent or ambiguous” proof gets HOLD. For example, if a command failed or returned no output, we would not assume success. A trivial example: if git ls-tree output could not be obtained (perhaps due to a Git version mismatch), we’d label the case as HOLD until rerun. In practice, our script should catch any unexpected empty output or error and record it. A successful tree listing that proves a required path is absent is a contract failure, as in the deletion control. Only when each required check has clear output do we move forward. This ensures we never make a release decision on partial data.
Reconcile expected and observed identities
For an executed run, compare the manifest to the recorded output. Each file has an expected blob OID (from the manifest) and we have an observed blob OID from git ls-tree HEAD. For instance, after a baseline commit we could extract:
$ git ls-tree HEAD foo.txt
# EXPECTED / NOT EXECUTED; illustrative blob ID:
100644 blob abcdef1234567890abcdef1234567890abcdef12 foo.txt
We check that blob ID (abcdef1...) matches the value we compute from the manifest or content (e.g. via git hash-object). If they match, the file’s identity is confirmed. This step is analogous to the submodule verification in the submodule validation playbook, where they compared committed gitlinks and working HEADs. Here we have one repository, but the principle is the same: explicitly match the observed object ID to the expected one. Any mismatch means someone changed the file content, which also violates the contract (requiring repair).
We document each identity mapping in our ledger. For example:
· Expected: foo.txt → Git blob OID of the exact baseline bytes, including the final newline.
· Observed: foo.txt blob ID from commit.
If they differ, our verdict shifts to REPAIR. If everything lines up, we remain on ACCEPT. This explicit reconciliation prevents trusting name-only matches; we ensure content identity too.
Separate documented guarantees from observations
Throughout, we distinguish “what Git docs promise” from “what we observed”. For example, documentation guarantees that skip-worktree files remain tracked and their absence is ignored in commits. The planned checks should confirm this: foo.txt should remain in the commit in both cases 1 and 2, including when it is absent on disk in case 2. If an executed run showed the file drop out of the commit solely because it was hidden, that would conflict with Git’s docs and flag a serious bug or a misuse.
We do not assume the docs; we verify them. Conversely, some behavior is implied rather than guaranteed: for example, Git doesn’t promise git status ignores skip-worktree differences (it often does, but it’s not documented as an API contract). So we treat any “status is clean” as anecdotal evidence only, not a contract. We rely on documented behavior (from git-update-index, etc.) for firm decisions. In short, documentation tells us what should happen (file not removed); the recorded evidence must confirm it. If docs and reality diverged, we would trust the docs as the standard and consider any divergence a failure to operate as documented (and thus a potential HOLD).
Bound the repair scope
If a check fails, we plan the minimal repair. We explicitly constrain our fixes so they don’t cause more changes. For a missing file, the repair is simply to re-add it (see next section). We avoid multi-file rebases or unbounded merges. Since the contract is narrow (just “file should be present with expected content”), our repair steps affect only that file. Any out-of-scope change (e.g. other files changed) would immediately move us to HOLD. By bounding repairs to the minimal diff needed to satisfy the manifest, we reduce risk of collateral issues.
Implement a bounded repair
In the case 3 deletion control, we implement a fix: restore the file from the last good commit. For example:
# Restore foo.txt from the commit before it was deleted
$ git checkout HEAD~1 -- foo.txt
$ git commit -m "Repair: restore foo.txt"
Now HEAD has a new commit where foo.txt is back. We would then rerun our evidence checks on this repaired commit to ensure it now passes. In effect, the repair aligns the actual tree with our manifest. We mark the repair action and result in our ledger. This is the same pattern as in the Ansible task-coverage playbook: small repairs (e.g. adding a missing step) are labeled REPAIR if they fix the evidence gap.
If the file content had changed (case 4), the repair similarly would be to reset it to the expected blob:
$ git checkout HEAD~1 -- foo.txt # assumes HEAD~1 had the correct content
$ git commit -m "Repair: revert foo.txt to expected content"
Again, only the content of foo.txt is touched. We then update the evidence ledger to show that the repaired candidate yields ACCEPT only after the repeated checks pass.
Test rollback and rerun safety
After making repairs, we test that we can revert the repo to the original baseline and rerun the entire sequence to the same result. This checks for hidden state. For example:
# Roll back only this disposable fixture to its recorded baseline.
$ git sparse-checkout disable
$ git reset --hard "$baseline_oid"
# EXPECTED / NOT EXECUTED; illustrative abbreviated commit ID:
HEAD is now at 1234567 Add foo.txt baseline
# Rerun sparse-checkout and the checks in fresh cases.
We essentially repeat the steps of cases 1–4. The outcomes (ACCEPT/REPAIR) should be identical. If a second run yields a different result (say, skip-worktree not behaving the same way), that indicates a non-determinism or a missing cleanup step, and we would hold the process.
This rerun safety step is like retesting in the AsyncMock completion playbook, where repeating async tasks ensures consistent outcomes. Here we ensure our harness can be executed multiple times without dependency on leftover state (e.g. skip-worktree bits should be cleared by disabling sparse-checkout). Any failure on rerun is noted in the evidence ledger as a non-idempotent risk (and would likely force a HOLD until resolved).
Assign operational ownership
Before making a final gate decision, assign clear responsibility. For example, the release engineer or repo maintainer should own verifying this test. They review the evidence ledger and ensure the tests were run correctly. Just as the AsyncMock completion playbook emphasizes a precise rule for local completion, here we assign a person to interpret the commit evidence. If manual intervention is needed (e.g. file recovered from backups), that owner coordinates it. This ensures accountability: there is a named individual who knows the policy and the evidence, not a vague “somehow it’s green”.
Decide ACCEPT, REPAIR, RERUN or HOLD
Based on the ledger, we now make a decision:
· ACCEPT: All evidence matches the manifest. That is the expected verdict for case 1 and case 2 (file present as expected). This passes the commit-completeness gate: the skip-worktree file was not lost in the commit.
· REPAIR: The evidence showed a fixable discrepancy. For example, if the file was missing (case 3) or content was wrong (case 4), we would have repaired it. After a successful repair, we would reclassify as ACCEPT. If repair cannot restore the exact expected state, we mark HOLD instead.
· RERUN: If any evidence was ambiguous (e.g. a command failed, or an environment mismatch), we rerun the tests in a clean environment. We would only accept on a second run if the evidence becomes clear.
· HOLD: If tests fail in an unfixable way or if evidence remains incomplete. For example, if our negative control or another check still violates the manifest after repair, we place the release on hold and investigate.
These terms mirror the coverage ledger labels in the Ansible task-coverage playbook and other Refonte playbooks. The planned outcomes, all EXPECTED / NOT EXECUTED, are: case 1: ACCEPT; case 2: ACCEPT; case 3: initially REPAIR (or HOLD until repair); case 4: REPAIR; case 5: ACCEPT.
Once all required files are confirmed in the commit (or properly repaired), we conclude ACCEPT. Only then is the gate passed. Any deviation moves to REPAIR or HOLD as per the table.
Connect the practice to Refonte Learning
This disciplined, evidence-based approach exemplifies the engineering skills emphasized in Refonte Learning’s DevOps Engineer program. In that three-month (12–14 h/week) program, participants master version control and release processes among other DevOps fundamentals. In fact, the program explicitly covers Version Control with Git & GitHub, providing a foundation for investigating advanced topics like sparse-checkout. Throughout the curriculum, students work on concrete projects with mentors to build practices like this: setting precise acceptance tests, capturing evidence, and deciding release actions. Graduates earn certificates (Training and Internship certificates) and can use the program’s virtual internship opportunities to apply these skills in project work.
For DevOps engineers, knowing exactly how Git will behave, and testing it rigorously, is critical. This playbook is a microcosm of that mindset. If you found this approach valuable, consider deepening your skills through Refonte Learning’s DevOps Engineer program, where you’ll learn these tools and validation techniques under expert guidance.
