← All Notes

Ignore Local Changes to a Tracked File with Git Skip-Worktree

git, skip-worktree, tracked-files, local-changes, version-control

Use Git’s skip-worktree flag when a file must remain tracked in the repository, but your local copy needs persistent changes that should not normally be committed.

Common examples include:

  • Local configuration files
  • Fixture or seed files populated with development data
  • Files containing machine-specific paths
  • Tracked templates that are customized locally

Enable skip-worktree

git update-index --skip-worktree path/to/file

The file remains tracked, and the committed repository version is unchanged. Git will normally stop showing local modifications to that file in git status.

Check whether a file is marked

git ls-files -v path/to/file

A file marked with skip-worktree starts with S:

S path/to/file

To list every file currently marked:

git ls-files -v | grep '^S'

Re-enable normal tracking

Before intentionally committing changes to the file, remove the flag:

git update-index --no-skip-worktree path/to/file

Git will then detect and display its local changes normally.

Important limitations

skip-worktree is stored only in the local Git repository. It is not committed or shared with other developers, so each developer must enable it separately.

It can also cause confusion when switching branches or pulling changes if the tracked repository version of the file has changed.

For shared project configuration, a cleaner structure is usually:

config.example.json
config.local.json

Commit the example file and add the local file to .gitignore.

Use skip-worktree when the same tracked file must exist in the repository and also needs a different persistent local version.