Skip to content

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 differencesYesYes
git add . stages the fileNoNo
git commit -a commits itNoNo
git checkout overwrites local changesYes — overwrites silentlyNo — preserves local copy
git pull / git merge overwrites local changesYes — may cause conflicts or overwriteNo — preserves local copy, merge stops with error
git diff shows differencesNoYes — git diff HEAD -- <path> still works
git stash includes itYesNo
Git warns you on divergenceNo — trusts your promiseYes — refuses to clobber
Use casePerformance: large files that genuinely don't changeConfig: 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.yaml

From this point:

  • git status shows the file as unchanged (even though it differs from HEAD).
  • git add . skips it.
  • git commit -a skips it.
  • git checkout main preserves your local copy.
  • git pull preserves your local copy (but see pitfalls below).
  • git diff shows nothing for that path. git diff HEAD -- config/local.yaml still 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
#   ? = untracked

Temporarily 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.yaml

Clear the flag permanently ​

bash
git update-index --no-skip-worktree config/local.yaml

4. 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.sh

The 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"
done

Pattern 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
done

Pattern 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
fi

This 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 resolving

Pitfall 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 worktree

Pitfall 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.yaml

Pitfall 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 ​

ScenarioFlag
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.yaml

8. 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.

Git Master — Git Reference for Every Skill Level