diff options
Diffstat (limited to 'Documentation/git-update-index.txt')
| -rw-r--r-- | Documentation/git-update-index.txt | 113 |
1 files changed, 81 insertions, 32 deletions
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 4e8e762e68..f4bb9c5daf 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -16,6 +16,7 @@ SYNOPSIS [--chmod=(+|-)x] [--[no-]assume-unchanged] [--[no-]skip-worktree] + [--[no-]ignore-skip-worktree-entries] [--[no-]fsmonitor-valid] [--ignore-submodules] [--[no-]split-index] @@ -29,9 +30,8 @@ SYNOPSIS DESCRIPTION ----------- -Modifies the index or directory cache. Each file mentioned is updated -into the index and any 'unmerged' or 'needs updating' state is -cleared. +Modifies the index. Each file mentioned is updated into the index and +any 'unmerged' or 'needs updating' state is cleared. See also linkgit:git-add[1] for a more user-friendly way to do some of the most common operations on the index. @@ -113,6 +113,11 @@ you will need to handle the situation manually. set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. + +--[no-]ignore-skip-worktree-entries:: + Do not remove skip-worktree (AKA "index-only") entries even when + the `--remove` option was specified. + --[no-]fsmonitor-valid:: When one of these flags is specified, the object name recorded for the paths are not updated. Instead, these options @@ -245,10 +250,10 @@ USING --CACHEINFO OR --INFO-ONLY current working directory. This is useful for minimum-checkout merging. -To pretend you have a file with mode and sha1 at path, say: +To pretend you have a file at path with mode and sha1, say: ---------------- -$ git update-index --cacheinfo <mode>,<sha1>,<path> +$ git update-index --add --cacheinfo <mode>,<sha1>,<path> ---------------- `--info-only` is used to register files without placing them in the object @@ -268,23 +273,20 @@ USING --INDEX-INFO multiple entry definitions from the standard input, and designed specifically for scripts. It can take inputs of three formats: - . mode SP sha1 TAB path -+ -The first format is what "git-apply --index-info" -reports, and used to reconstruct a partial tree -that is used for phony merge base tree when falling -back on 3-way merge. - . mode SP type SP sha1 TAB path + -The second format is to stuff 'git ls-tree' output -into the index file. +This format is to stuff `git ls-tree` output into the index. . mode SP sha1 SP stage TAB path + This format is to put higher order stages into the index file and matches 'git ls-files --stage' output. + . mode SP sha1 TAB path ++ +This format is no longer produced by any Git command, but is +and will continue to be supported by `update-index --index-info`. + To place a higher stage entry to the index, the path should first be removed by feeding a mode=0 entry for the path, and then feeding necessary input lines in the third format. @@ -349,6 +351,10 @@ unchanged". Note that "assume unchanged" bit is *not* set if the index (use `git update-index --really-refresh` if you want to mark them as "assume unchanged"). +Sometimes users confuse the assume-unchanged bit with the +skip-worktree bit. See the final paragraph in the "Skip-worktree bit" +section below for an explanation of the differences. + EXAMPLES -------- @@ -390,22 +396,47 @@ M foo.c SKIP-WORKTREE BIT ----------------- -Skip-worktree bit can be defined in one (long) sentence: When reading -an entry, if it is marked as skip-worktree, then Git pretends its -working directory version is up to date and read the index version -instead. - -To elaborate, "reading" means checking for file existence, reading -file attributes or file content. The working directory version may be -present or absent. If present, its content may match against the index -version or not. Writing is not affected by this bit, content safety -is still first priority. Note that Git _can_ update working directory -file, that is marked skip-worktree, if it is safe to do so (i.e. -working directory version matches index version) +Skip-worktree bit can be defined in one (long) sentence: Tell git to +avoid writing the file to the working directory when reasonably +possible, and treat the file as unchanged when it is not +present in the working directory. + +Note that not all git commands will pay attention to this bit, and +some only partially support it. + +The update-index flags and the read-tree capabilities relating to the +skip-worktree bit predated the introduction of the +linkgit:git-sparse-checkout[1] command, which provides a much easier +way to configure and handle the skip-worktree bits. If you want to +reduce your working tree to only deal with a subset of the files in +the repository, we strongly encourage the use of +linkgit:git-sparse-checkout[1] in preference to the low-level +update-index and read-tree primitives. + +The primary purpose of the skip-worktree bit is to enable sparse +checkouts, i.e. to have working directories with only a subset of +paths present. When the skip-worktree bit is set, Git commands (such +as `switch`, `pull`, `merge`) will avoid writing these files. +However, these commands will sometimes write these files anyway in +important cases such as conflicts during a merge or rebase. Git +commands will also avoid treating the lack of such files as an +intentional deletion; for example `git add -u` will not stage a +deletion for these files and `git commit -a` will not make a commit +deleting them either. Although this bit looks similar to assume-unchanged bit, its goal is -different from assume-unchanged bit's. Skip-worktree also takes -precedence over assume-unchanged bit when both are set. +different. The assume-unchanged bit is for leaving the file in the +working tree but having Git omit checking it for changes and presuming +that the file has not been changed (though if it can determine without +stat'ing the file that it has changed, it is free to record the +changes). skip-worktree tells Git to ignore the absence of the file, +avoid updating it when possible with commands that normally update +much of the working directory (e.g. `checkout`, `switch`, `pull`, +etc.), and not have its absence be recorded in commits. Note that in +sparse checkouts (setup by `git sparse-checkout` or by configuring +core.sparseCheckout to true), if a file is marked as skip-worktree in +the index but is found in the working tree, Git will clear the +skip-worktree bit for that file. SPLIT INDEX ----------- @@ -429,7 +460,7 @@ specified by the splitIndex.sharedIndexExpire config variable (see linkgit:git-config[1]). To avoid deleting a shared index file that is still used, its -modification time is updated to the current time everytime a new split +modification time is updated to the current time every time a new split index based on the shared index file is either created or read from. UNTRACKED CACHE @@ -496,7 +527,9 @@ FILE SYSTEM MONITOR This feature is intended to speed up git operations for repos that have large working directories. -It enables git to work together with a file system monitor (see the +It enables git to work together with a file system monitor (see +linkgit:git-fsmonitor{litdd}daemon[1] +and the "fsmonitor-watchman" section of linkgit:githooks[5]) that can inform it as to what files have been modified. This enables git to avoid having to lstat() every file to find modified files. @@ -507,8 +540,8 @@ looking for new files. If you want to enable (or disable) this feature, it is easier to use the `core.fsmonitor` configuration variable (see -linkgit:git-config[1]) than using the `--fsmonitor` option to -`git update-index` in each repository, especially if you want to do so +linkgit:git-config[1]) than using the `--fsmonitor` option to `git +update-index` in each repository, especially if you want to do so across all repositories you use, because you can set the configuration variable in your `$HOME/.gitconfig` just once and have it affect all repositories you touch. @@ -546,6 +579,22 @@ The untracked cache extension can be enabled by the `core.untrackedCache` configuration variable (see linkgit:git-config[1]). +NOTES +----- + +Users often try to use the assume-unchanged and skip-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. + SEE ALSO -------- linkgit:git-config[1], |