Reputation: 7513
I have local changes to a file that I don't want to commit to my repository. It is a configuration file for building the application on a server, but I want to build locally with different settings. Naturally, the file always shows up when I do 'git status' as something to be staged. I would like to hide this particular change and not commit it. I won't make any other changes to the file.
To clarify, using .gitignore is not what I want since that only prevents new files from being added. I want to ignore changes to a file already in the repository.
After some digging around, I see 2 options: assume-unchanged
and skip-worktree
. A previous question here talks about them but doesn't really explain their differences.
How are the two commands different? Why would someone use one or the other?
Upvotes: 713
Views: 155292
Reputation: 98469
You want to use skip-worktree
:
git update-index --skip-worktree <file_name>
assume-unchanged
is designed for cases where it is expensive to check whether a group of files have been modified; when you set the bit, git
(of course) assumes the files corresponding to that portion of the index have not been modified in the working copy. So it avoids a mess of stat
calls. This bit is lost whenever the file's entry in the index changes (so, when the file is changed upstream).
skip-worktree
is more than that: even where git
knows that the file has been modified (or needs to be modified by a reset --hard
or the like), it will pretend it has not been, using the version from the index instead. This persists until the index is discarded.
There is a good summary of the ramifications of this difference and the typical use cases here: http://fallengamer.livejournal.com/93321.html.
From that article:
--assume-unchanged
assumes that a developer shouldn’t change a file. This flag is meant for improving performance for not-changing folders like SDKs.--skip-worktree
is useful when you instruct git not to touch a specific file ever because developers should change it. For example, if the main repository upstream hosts some production-ready configuration files and you don’t want to accidentally commit changes to those files, --skip-worktree
is exactly what you want.Upvotes: 1028
Reputation: 329
Use skip-worktree as in:
git update-index --skip-worktree changedfile.txt
confirm file status:
git ls-files -v
S changedfile.txt
The first letter, S, means the file is marked with the skip-worktree option
Reason:
"git-update-index --assume-unchanged was never meant to ignore changes to tracked files (only to spare some stats). So do not suggest it as a means to achieve that."
SEE: https://github.com/git/git/commit/936d2c9301e41a84a374b98f92777e00d321a2ea
--skip-worktree explained:
This option ignores changes to a file that is already tracked. git always uses the file content and attributes from the index regardless of any modifications made to the file in the working directory. This allows you to make changes to a file that you don't want to be pushed to upstream. Use this option as already shown above.
To unset this option, use --no-skip-worktree
as in:
git update-index --no-skip-worktree changedfile.txt
--assume-unchanged explained:
This option was specifically made for use cases where it's resource-intensive to check if certain files have been modified. e.g. to optimize resource usage on a slow filesystem, git doesn't check the files to see if the files in question changed, it assumes the files have not been modified in the working directory. This flag is lost whenever the file's entry in the index changes. e.g. when the file is modified upstream.
It's used as follows:
git update-index --assume-unchanged changedfile.txt
confirm file status:
git ls-files -v
h changedfile.txt
The first letter h means the file is marked with the assumed-unchanged option
To unset this option, use –no-assume-unchanged
as in:
git update-index --no-assume-unchanged changedfile.txt
Upvotes: 7
Reputation: 1323913
Note: fallengamer did some tests in 2011 (so they may be outdated), and here are his findings:
Operations
git pull
:assume-unchanged
flag: Git wouldn’t overwrite local file. Instead it would output conflicts and advices how to resolve themskip-worktree
flag: Git wouldn’t overwrite local file. Instead it would output conflicts and advices how to resolve themgit stash
git pull
skip-worktree
results in some extra manual work but at least you wouldn’t lose any data if you had any local changes.
assume-unchanged
flag: Discards all local changes without any possibility to restore them. The effect is like ‘git reset --hard
’. ‘git pull
’ call will succeedskip-worktree
flag: Stash wouldn’t work on skip-worktree
files. ‘git pull
’ will fail with the same error as above. Developer is forced to manually reset skip-worktree
flag to be able to stash and complete the failing pull
.git pull
assume-unchanged
promise and choses to reflect the reality by resetting the flag.
assume-unchanged
flag: Content is updated, flag is lost.git ls-files -v
’ would show that flag is modified to H
(from h
).skip-worktree
flag: Content is updated, flag is preserved.git ls-files -v
' would show the same S
flag as before the pull
.git reset --hard
skip-worktree
file and reflects reality (the file promised to be unchanged actually was changed) for assume-unchanged
file.
assume-unchanged
flag: File content is reverted. Flag is reset to H
(from h
).skip-worktree
flag: File content is intact. Flag remains the same. He adds the following analysis:
It looks like skip-worktree
is trying very hard to preserve your local data. But it doesn’t prevent you to get upstream changes if it is safe. Plus git doesn’t reset the flag on pull
.
But ignoring the ‘reset --hard
' command could become a nasty surprise for a developer.
Assume-unchanged
flag could be lost on the pull
operation and the local changes inside such files doesn’t seem to be important to git.
See:
Junio's (current git maintainer) comment regarding intent of assume-unchanged
,
In particular, Junio points out that changes to assume-unchanged
files could accidentally be committed: "if Git can determine a path
that is marked as assume-unchanged
has changed without incurring
extra lstat(2) cost, it reserves the right to report that the path
has been modified (as a result, git commit -a
is free to commit
that change)."
He concludes:
Actually neither of the flags is intuitive enough.
assume-unchanged
assumes that a developer shouldn’t change a file. If a file was changed – then that change is not important. This flag is meant for improving performance for not-changing folders like SDKs.
But if the promise is broken and a file is actually changed, git reverts the flag to reflect the reality. Probably it’s ok to have some inconsistent flags in generally not-meant-to-be-changed folders.
On the other hand skip-worktree
is useful when you instruct git not to touch a specific file ever. That is useful for an already tracked config file.
Upstream main repository hosts some production-ready config but you would like to change some settings in the config to be able to do some local testing. And you don’t want to accidentally check the changes in such file to affect the production config. In that case skip-worktree
makes perfect scene.
With Git 2.25.1 (Feb. 2020), the "Actually neither of the flags is intuitive enough" mentioned above is further clarified:
See commit 7a2dc95, commit 1b13e90 (22 Jan 2020) by brian m. carlson (bk2204
).
(Merged by Junio C Hamano -- gitster
-- in commit 53a8329, 30 Jan 2020)
(Git Mailing list)
doc
: dissuade users from trying to ignore tracked filesSigned-off-by: Jeff King
Signed-off-by: brian m. carlsonIt is quite common for users to want to ignore the changes to a file that Git tracks.
Common scenarios for this case are IDE settings and configuration files, which should generally not be tracked and possibly generated from tracked files using a templating mechanism.
However, users learn about the assume-unchanged and skip-worktree bits and try to use them to do this anyway.
This is problematic, because when these bits are set, many operations behave as the user expects, but they usually do not help when
git checkout
needs to replace a file.There is no sensible behavior in this case, because sometimes the data is precious, such as certain configuration files, and sometimes it is irrelevant data that the user would be happy to discard.
Since this is not a supported configuration and users are prone to misuse the existing features for unintended purposes, causing general sadness and confusion, let's document the existing behavior and the pitfalls in the documentation for
git update-index
so that users know they should explore alternate solutions.In addition, let's provide a recommended solution to dealing with the common case of configuration files, since there are well-known approaches used successfully in many environments.
The git update-index
man page now includes:
Users often try to use the
assume-unchanged
andskip-worktree
bits to tell Git to ignore changes to files that are tracked. This does not work as expected, since Git may still check working tree files against the index when performing certain operations. In general, Git does not provide a way to ignore changes to tracked files, so alternate solutions are recommended.For example, if the file you want to change is some sort of config file, the repository can include a sample config file that can then be copied into the ignored name and modified. The repository can even include a script to treat the sample file as a template, modifying and copying it automatically.
That last part is what I describe a typical content filter driver based on smudge/clean scripts.
Upvotes: 161