Appearance
git update-index — Local Config Management with skip-worktree and assume-unchanged
A guide for DevOps engineers who need Git to track a file as a template (.env.example, config/local.yaml, ide/workspace.xml) but never accidentally commit local customizations of it.
1. The Problem
Your repo has a file that must be tracked — a CI config template, a Docker Compose override stub, a .env.example that documents every variable. Every developer or runner needs their own copy with real values. You cannot .gitignore it because the template itself must version with the code.
The naive approach — edit, be careful, never git add . — fails under pressure. One git commit -a or git add :/ and your local secrets are in the commit history forever.
Two Git index flags solve this: --assume-unchanged and --skip-worktree. They look similar. They are not the same.
2. The Two Flags
--assume-unchanged
git update-index --assume-unchanged <path>Tells Git: "I promise this file has not changed. Do not bother checking it. Treat it as unchanged even if the working tree copy differs."
Designed for files that are genuinely large and slow to stat (e.g., .gitignore in a 300k-file monorepo, build artifacts that live in the index for sparse reasons). You are making a performance promise: if the file does change, you will tell Git yourself by clearing the flag.
Git trusts you. It will not warn you when the working tree differs from the index. It will silently skip the file in git status, git add ., git commit -a, and git diff. This is the right flag only when you can keep that promise.
--skip-worktree
git update-index --skip-worktree <path>Tells Git: "This file is tracked in the index. I know it differs locally. Do not touch my local copy on checkout, merge, pull, or rebase, and do not stage changes to it. I want to keep my version."
Designed for the exact DevOps scenario above. Git does not trust you — it knows the file may diverge and prevents porcelain commands from overwriting your local copy during merges, checkouts, and pulls.
This is the flag you want for local config management.
Comparison
| Behaviour | --assume-unchanged | --skip-worktree |
|---|---|---|
git status ignores differences | Yes | Yes |
git add . stages the file | No | No |
git commit -a commits it | No | No |
git checkout overwrites local changes | Yes — overwrites silently | No — preserves local copy |
git pull / git merge overwrites local changes | Yes — may cause conflicts or overwrite | No — preserves local copy, merge stops with error |
git diff shows differences | No | Yes — git diff HEAD -- <path> still works |
git stash includes it | Yes | No |
| Git warns you on divergence | No — trusts your promise | Yes — refuses to clobber |
| Use case | Performance: large files that genuinely don't change | Config: tracked template with local customizations |
3. The DevOps Pattern
Mark a local config file
bash
# You have a tracked template
git add config/local.yaml
git commit -m "feat(config): add local config template"
# Now customize it for your environment
# Edit config/local.yaml with real values
# Tell Git to leave it alone
git update-index --skip-worktree config/local.yamlFrom this point:
git statusshows the file as unchanged (even though it differs from HEAD).git add .skips it.git commit -askips it.git checkout mainpreserves your local copy.git pullpreserves your local copy (but see pitfalls below).git diffshows nothing for that path.git diff HEAD -- config/local.yamlstill shows the diff.
Verify which files are flagged
bash
# List all files with skip-worktree set
git ls-files -v | grep '^S'
# Output: S config/local.yaml
# List all files with assume-unchanged
git ls-files -v | grep '^h'
# Output: h config/local.yaml
# The flag letter in column 1:
# S = skip-worktree
# H = normal (cache-hydrated)
# h = assume-unchanged (lowercase = flag set)
# s = skip-worktree (lowercase s)
# M = unchanged but in merge conflict
# ? = untrackedTemporarily override the flag
bash
# When the template itself changes upstream, you need to update your local copy
# Unset the flag, pull changes, re-set it
git update-index --no-skip-worktree config/local.yaml
git pull # or git checkout HEAD -- config/local.yaml to reset
# Re-apply your local customizations
git update-index --skip-worktree config/local.yamlClear the flag permanently
bash
git update-index --no-skip-worktree config/local.yaml4. CI/CD Patterns
Pattern 1: CI runner secrets injection
A CI runner needs a config file with runtime credentials that differ from the committed template. The runner's setup step writes the real config and marks it skip-worktree so no subsequent build step accidentally stages it.
yaml
# .forgejo/workflows/deploy.yaml
jobs:
deploy:
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Inject runner config
run: |
cat > config/deploy.yaml << 'EOF'
api_key: ${{ secrets.DEPLOY_KEY }}
endpoint: ${{ vars.DEPLOY_ENDPOINT }}
EOF
git update-index --skip-worktree config/deploy.yaml
- name: Run deploy
run: ./deploy.shThe skip-worktree flag prevents any subsequent step that runs git add . or git commit (some CI frameworks do this for artifact tracking) from leaking the secret into Git.
Pattern 2: Multi-env config scaffolding
A monorepo with per-environment config files that each developer or pipeline customizes:
bash
# One-time setup per environment
for env_config in config/development.yaml config/staging.override.yaml; do
cp "${env_config}.example" "$env_config"
git update-index --skip-worktree "$env_config"
donePattern 3: Pre-commit drift detection
A pre-commit hook that warns if a skip-worktree file has been modified compared to its committed state, prompting the developer to verify the change is intentional:
bash
# .git/hooks/pre-commit
for file in $(git ls-files -v | grep '^S' | awk '{print $2}'); do
if ! git diff --quiet HEAD -- "$file"; then
echo "Warning: skip-worktree file '$file' differs from HEAD."
echo "If you want to commit this change, run:"
echo " git update-index --no-skip-worktree '$file'"
echo " git add '$file'"
echo " git commit -m 'update $file'"
echo " git update-index --skip-worktree '$file'"
exit 1
fi
donePattern 4: CI guard — assert no flagged files leak
A CI check that fails if any skip-worktree or assume-unchanged file is present in the checkout, ensuring the runner didn't leave behind flagged files from a previous build:
bash
# CI gate: fail if any flagged files exist
FLAGGED=$(git ls-files -v | grep -E '^(S|h)' | wc -l)
if [ "$FLAGGED" -ne 0 ]; then
echo "ERROR: $FLAGGED files have index flags set. Clean them before committing."
git ls-files -v | grep -E '^(S|h)'
exit 1
fiThis gate is useful in a release pipeline or pre-merge check where you want to ensure no local-override flags leaked from a developer workstation into CI.
Pattern 5: Automated template sync
When the upstream template changes, a script can pull the new template, re-apply local overrides from a diff stash, and re-mark the file:
bash
# scripts/sync-config.sh
CONFIG_FILE="config/local.yaml"
# Unmark
git update-index --no-skip-worktree "$CONFIG_FILE"
# Save local diff before upstream update
LOCAL_DIFF=$(git diff HEAD -- "$CONFIG_FILE")
# Pull new template from upstream
git checkout HEAD -- "$CONFIG_FILE"
# Re-apply local changes if they still apply
if [ -n "$LOCAL_DIFF" ]; then
echo "$LOCAL_DIFF" | git apply --3way || {
echo "Local overrides conflicted. Resolve manually, then re-mark:"
echo " git update-index --skip-worktree $CONFIG_FILE"
exit 1
}
fi
# Re-mark
git update-index --skip-worktree "$CONFIG_FILE"5. Common Pitfalls
Pitfall 1: Using --assume-unchanged for config management
The most common mistake. --assume-unchanged does NOT protect your local changes during merges or checkouts. A git checkout or git pull that touches the file will overwrite your local copy without warning. Use --skip-worktree for config files.
Pitfall 2: Merge conflict on skip-worktree file
If the upstream changes a skip-worktree file and you pull, Git will refuse to overwrite it and the merge will stop with:
error: Your local changes to the following files would be overwritten by merge:
config/local.yaml
Please commit your changes or stash them before you merge.This is by design — Git is protecting your local config. Resolution:
bash
# Option A: Accept upstream, re-apply local changes
git update-index --no-skip-worktree config/local.yaml
git stash
git pull
git stash pop # may conflict
git update-index --skip-worktree config/local.yaml
# Option B: Keep your local version, skip upstream changes
git pull --no-ff # will fail as above
# Then use git checkout --ours/theirs after resolvingPitfall 3: Forgetting you flagged files
A teammate inherits a repo with skip-worktree files set. They see git status clean, edit the tracked template, commit — and nothing happens. The file stays uncommitted. They waste an hour debugging.
Mitigation: Document in the repo's CONTRIBUTING.md or setup script which files are expected to be flagged, and provide a make setup or scripts/setup-dev.sh that handles it.
Pitfall 4: Flag leaks across worktrees
Skip-worktree and assume-unchanged flags are per-worktree settings. They live in $GIT_DIR/info/exclude equivalent (the index extension), not in the shared repo config. If you create a second worktree, you must re-apply the flags there.
bash
# Check flags in the current worktree
git ls-files -v | grep '^S'
# In a new worktree, the flags are NOT inherited
# Re-run git update-index --skip-worktree <path> in the new worktreePitfall 5: git stash with skip-worktree files
git stash does NOT include skip-worktree files. If you need to stash changes to a flagged file temporarily, unset the flag first:
bash
git update-index --no-skip-worktree config/local.yaml
git stash
# ... do something ...
git stash pop
git update-index --skip-worktree config/local.yamlPitfall 6: git clean and flagged files
git clean -fd does not remove skip-worktree or assume-unchanged files because Git considers them part of the working tree state. However, git clean -fdx may remove untracked files that the flagged file depends on. Test with --dry-run first.
Pitfall 7: Submodule skip-worktree
Skip-worktree on a submodule's file works at the submodule level, not the superproject. To skip a file inside a submodule, you must cd into the submodule and set the flag there. The superproject's index does not control submodule working tree flags.
6. When to Use Each Flag
| Scenario | Flag |
|---|---|
| Tracked config template with local customizations | --skip-worktree |
IDE workspace file (.idea/workspace.xml) that is tracked in the repo | --skip-worktree |
| Large generated file that is tracked but expensive to stat | --assume-unchanged |
.gitignore in a sparse-index monorepo (performance) | --assume-unchanged |
| CI runner injecting secrets into a tracked config template | --skip-worktree |
| File that must survive checkout/merge/pull with local changes | --skip-worktree |
| File you promise will never change locally | --assume-unchanged |
7. Additional Commands Reference
bash
# Mark files
git update-index --skip-worktree <path> [...]
git update-index --assume-unchanged <path> [...]
# Unmark files
git update-index --no-skip-worktree <path> [...]
git update-index --no-assume-unchanged <path> [...]
# List all flagged files
git ls-files -v | grep -E '^(S|h)'
# Count flagged files
git ls-files -v | grep -c -E '^(S|h)'
# Check if a specific file is flagged
git ls-files -v config/local.yaml | grep -q '^S' && echo "skip-worktree" || echo "normal"
# Show the actual diff of a skip-worktree file (git diff skips it)
git diff HEAD -- config/local.yaml
# Reset a file to HEAD (clears local changes, flag persists)
git checkout HEAD -- config/local.yaml
# Then unset flag if needed
git update-index --no-skip-worktree config/local.yaml8. How It Works Internally
Both flags are stored in the Git index as CE_VALID (--assume-unchanged) and CE_SKIP_WORKTREE (--skip-worktree) flags on the index entry. These are bits in the ce_flags field of each cache entry (struct cache_entry). When Git reads the index:
- CE_VALID (assume-unchanged): Git skips
lstat()on the working tree file entirely. The index entry is treated as up-to-date regardless of the working tree state. - CE_SKIP_WORKTREE (skip-worktree): Git reads the index entry but does not compare it to the working tree. The index entry is treated as authoritative for the working tree — checkout, merge, and pull operations will not overwrite it.
The flags survive git gc, git repack, and git fsck. They survive git fetch and git push. They are lost on git clone (new index) and git worktree add (new per-worktree index).
The flags are not pushed or fetched. They are strictly local index state. If you want to share the expectation that a file should be marked skip-worktree, document it in a setup script that teammates run after clone.