Git – Ignoring Files Locally

If you use a version control system like Git, you’ve probably encountered situations where certain files exist in your project but should not be committed to the repository, for example, files containing credentials, local environment configuration, or temporary logs. Excluding files from the repository is handled by the .gitignore file. It works like a filter that tells Git: “don’t track these files.”

Global file ignoring

Each entry in .gitignore tells Git not to add the specified files to the repository at all. They are completely ignored during commits. This is a great solution for files that should never appear in the project history.

But what if the situation is reversed? What if you have a file that must exist in the repository, for example, one that contains shared project configuration (such as phpcs.xml.dist or config.json), but you still need to modify it locally without the risk of those changes being committed or overwritten by a git pull?

In this case, .gitignore won’t help, because it only works for new, untracked files. Our file is already tracked by Git. So what can be done?

Ignoring files locally with the skip-worktree flag

The git update-index --skip-worktree command works a bit like a local .gitignore, but only for your environment. Git still knows that the file exists and keeps its version in the repository, but it stops reacting to local changes.

Example:

git update-index --skip-worktree phpcs.xml.dist

From this point on, you can edit phpcs.xml.dist however you like – add your own rules, paths, or settings. Git will not show it in git status, and your local changes will not be included in commits. Importantly, other developers on the team will still see the original file from the repository, so the shared workflow remains unaffected.

Reverting local ignoring

If you want Git to start tracking the file normally again, for example, if you want to restore the repository version or commit your changes, use the --no-skip-worktree option:

git update-index --no-skip-worktree phpcs.xml.dist

After running this command, Git will start detecting changes in this file again.

How to check which files are currently ignored locally

If you want to see which files have the skip-worktree flag set, run the following command in the terminal:

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

The letter S before a file name indicates that the file is marked as skip-worktree.

Important: The git update-index --skip-worktree phpcs.xml.dist command allows you to modify the file locally while Git ignores those changes, but keep the following in mind:

• Run the command before making any changes to the file.
• If you modify the file on one branch and the file differs on another branch, Git may prevent you from switching branches. In that case, you’ll need to stop ignoring the file. For this reason, it’s best to apply your local changes on each branch at the very beginning of your work.
• This flag works locally only – it is not visible in the repository and does not affect other developers.
• If someone else changes this file in the repository and you run git pull, Git will not automatically merge those changes. You’ll need to handle the update manually.
• The --skip-worktree flag works only for files that are already tracked by Git. It does not apply to new, untracked files, those should be handled with .gitignore.

The git update-index --skip-worktree command acts like a local “do not disturb” mode for selected files. It allows you to tailor the repository to your own working environment without risking changes to the shared codebase.