# git update-index: Usage, Options & Common CI Errors

> git update-index edits the index directly, including assume-unchanged and skip-worktree. Reference for these flags and why they cause "lost edit" bugs.

Source: https://latchkey.dev/learn/command-reference/git-update-index  
Updated: 2026-06-25

git update-index is the plumbing that edits the staging area directly, including the assume-unchanged and skip-worktree bits.

update-index is low-level. Its assume-unchanged/skip-worktree flags are powerful but a common source of "my change vanished" bugs.

## What it does

git update-index registers file contents and flags in the index. It can mark files assume-unchanged (a performance hint) or skip-worktree (tell Git to ignore local edits to a tracked file).

## Common usage

```Terminal
git update-index --assume-unchanged config.local
git update-index --no-assume-unchanged config.local
git update-index --skip-worktree settings.json
git update-index --refresh
git ls-files -v | grep '^[hsS]'   # list flagged files
```

## Options

| Flag | What it does |
| --- | --- |
| --assume-unchanged | Skip change detection (perf hint, not durable) |
| --skip-worktree | Ignore local changes to a tracked file |
| --no-assume-unchanged / --no-skip-worktree | Clear the bits |
| --refresh | Refresh stat info in the index |
| --chmod=+x | Set the executable bit on a file |

## Common errors in CI

Edits to a file marked assume-unchanged or skip-worktree silently do not get committed - and these bits are local-only, so they cause "works on my machine" drift. Audit with git ls-files -v (lowercase letters indicate the flags) and clear with --no-skip-worktree.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git update-index: Usage, Options & Common CI Errors?

update-index is low-level. Its assume-unchanged/skip-worktree flags are powerful but a common source of "my change vanished" bugs.

### What it does?

git update-index registers file contents and flags in the index. It can mark files assume-unchanged (a performance hint) or skip-worktree (tell Git to ignore local edits to a tracked file).

### Common errors in CI?

Edits to a file marked assume-unchanged or skip-worktree silently do not get committed - and these bits are local-only, so they cause "works on my machine" drift. Audit with git ls-files -v (lowercase letters indicate the flags) and clear with --no-skip-worktree.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt