| git-update-index(1) |
| =================== |
| |
| NAME |
| ---- |
| git-update-index - Register file contents in the working tree to the index |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git update-index' |
| [--add] [--remove | --force-remove] [--replace] |
| [--refresh] [-q] [--unmerged] [--ignore-missing] |
| [(--cacheinfo <mode>,<object>,<file>)...] |
| [--chmod=(+|-)x] |
| [--[no-]assume-unchanged] |
| [--[no-]skip-worktree] |
| [--[no-]ignore-skip-worktree-entries] |
| [--[no-]fsmonitor-valid] |
| [--ignore-submodules] |
| [--[no-]split-index] |
| [--[no-|test-|force-]untracked-cache] |
| [--[no-]fsmonitor] |
| [--really-refresh] [--unresolve] [--again | -g] |
| [--info-only] [--index-info] |
| [-z] [--stdin] [--index-version <n>] |
| [--show-index-version] |
| [--verbose] |
| [--] [<file>...] |
| |
| DESCRIPTION |
| ----------- |
| 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. |
| |
| The way 'git update-index' handles files it is told about can be modified |
| using the various options: |
| |
| OPTIONS |
| ------- |
| --add:: |
| If a specified file isn't in the index already then it's |
| added. |
| Default behaviour is to ignore new files. |
| |
| --remove:: |
| If a specified file is in the index but is missing then it's |
| removed. |
| Default behavior is to ignore removed files. |
| |
| --refresh:: |
| Looks at the current index and checks to see if merges or |
| updates are needed by checking stat() information. |
| |
| -q:: |
| Quiet. If --refresh finds that the index needs an update, the |
| default behavior is to error out. This option makes |
| 'git update-index' continue anyway. |
| |
| --ignore-submodules:: |
| Do not try to update submodules. This option is only respected |
| when passed before --refresh. |
| |
| --unmerged:: |
| If --refresh finds unmerged changes in the index, the default |
| behavior is to error out. This option makes 'git update-index' |
| continue anyway. |
| |
| --ignore-missing:: |
| Ignores missing files during a --refresh |
| |
| --cacheinfo <mode>,<object>,<path>:: |
| --cacheinfo <mode> <object> <path>:: |
| Directly insert the specified info into the index. For |
| backward compatibility, you can also give these three |
| arguments as three separate parameters, but new users are |
| encouraged to use a single-parameter form. |
| |
| --index-info:: |
| Read index information from stdin. |
| |
| --chmod=(+|-)x:: |
| Set the execute permissions on the updated files. |
| |
| --[no-]assume-unchanged:: |
| When this flag is specified, the object names recorded |
| for the paths are not updated. Instead, this option |
| sets/unsets the "assume unchanged" bit for the |
| paths. When the "assume unchanged" bit is on, the user |
| promises not to change the file and allows Git to assume |
| that the working tree file matches what is recorded in |
| the index. If you want to change the working tree file, |
| you need to unset the bit to tell Git. This is |
| sometimes helpful when working with a big project on a |
| filesystem that has a very slow lstat(2) system call |
| (e.g. cifs). |
| + |
| Git will fail (gracefully) in case it needs to modify this file |
| in the index e.g. when merging in a commit; |
| thus, in case the assumed-untracked file is changed upstream, |
| you will need to handle the situation manually. |
| |
| --really-refresh:: |
| Like `--refresh`, but checks stat information unconditionally, |
| without regard to the "assume unchanged" setting. |
| |
| --[no-]skip-worktree:: |
| When one of these flags is specified, the object names recorded |
| for the paths are not updated. Instead, these options |
| 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 names recorded |
| for the paths are not updated. Instead, these options |
| set and unset the "fsmonitor valid" bit for the paths. See |
| section "File System Monitor" below for more information. |
| |
| -g:: |
| --again:: |
| Runs 'git update-index' itself on the paths whose index |
| entries are different from those of the `HEAD` commit. |
| |
| --unresolve:: |
| Restores the 'unmerged' or 'needs updating' state of a |
| file during a merge if it was cleared by accident. |
| |
| --info-only:: |
| Do not create objects in the object database for all |
| <file> arguments that follow this flag; just insert |
| their object IDs into the index. |
| |
| --force-remove:: |
| Remove the file from the index even when the working directory |
| still has such a file. (Implies --remove.) |
| |
| --replace:: |
| By default, when a file `path` exists in the index, |
| 'git update-index' refuses an attempt to add `path/file`. |
| Similarly if a file `path/file` exists, a file `path` |
| cannot be added. With --replace flag, existing entries |
| that conflict with the entry being added are |
| automatically removed with warning messages. |
| |
| --stdin:: |
| Instead of taking a list of paths from the command line, |
| read a list of paths from the standard input. Paths are |
| separated by LF (i.e. one path per line) by default. |
| |
| --verbose:: |
| Report what is being added and removed from the index. |
| |
| --index-version <n>:: |
| Write the resulting index out in the named on-disk format version. |
| Supported versions are 2, 3, and 4. The current default version is 2 |
| or 3, depending on whether extra features are used, such as |
| `git add -N`. With `--verbose`, also report the version the index |
| file uses before and after this command. |
| + |
| Version 4 performs a simple pathname compression that reduces index |
| size by 30%-50% on large repositories, which results in faster load |
| time. Git supports it since version 1.8.0, released in October 2012, |
| and support for it was added to libgit2 in 2016 and to JGit in 2020. |
| Older versions of this manual page called it "relatively young", but |
| it should be considered mature technology these days. |
| |
| --show-index-version:: |
| Report the index format version used by the on-disk index file. |
| See `--index-version` above. |
| |
| -z:: |
| Only meaningful with `--stdin` or `--index-info`; paths are |
| separated with NUL character instead of LF. |
| |
| --split-index:: |
| --no-split-index:: |
| Enable or disable split index mode. If split-index mode is |
| already enabled and `--split-index` is given again, all |
| changes in $GIT_DIR/index are pushed back to the shared index |
| file. |
| + |
| These options take effect whatever the value of the `core.splitIndex` |
| configuration variable (see linkgit:git-config[1]). But a warning is |
| emitted when the change goes against the configured value, as the |
| configured value will take effect next time the index is read and this |
| will remove the intended effect of the option. |
| |
| --untracked-cache:: |
| --no-untracked-cache:: |
| Enable or disable untracked cache feature. Please use |
| `--test-untracked-cache` before enabling it. |
| + |
| These options take effect whatever the value of the `core.untrackedCache` |
| configuration variable (see linkgit:git-config[1]). But a warning is |
| emitted when the change goes against the configured value, as the |
| configured value will take effect next time the index is read and this |
| will remove the intended effect of the option. |
| |
| --test-untracked-cache:: |
| Only perform tests on the working directory to make sure |
| untracked cache can be used. You have to manually enable |
| untracked cache using `--untracked-cache` or |
| `--force-untracked-cache` or the `core.untrackedCache` |
| configuration variable afterwards if you really want to use |
| it. If a test fails the exit code is 1 and a message |
| explains what is not working as needed, otherwise the exit |
| code is 0 and OK is printed. |
| |
| --force-untracked-cache:: |
| Same as `--untracked-cache`. Provided for backwards |
| compatibility with older versions of Git where |
| `--untracked-cache` used to imply `--test-untracked-cache` but |
| this option would enable the extension unconditionally. |
| |
| --fsmonitor:: |
| --no-fsmonitor:: |
| Enable or disable files system monitor feature. These options |
| take effect whatever the value of the `core.fsmonitor` |
| configuration variable (see linkgit:git-config[1]). But a warning |
| is emitted when the change goes against the configured value, as |
| the configured value will take effect next time the index is |
| read and this will remove the intended effect of the option. |
| |
| \--:: |
| Do not interpret any more arguments as options. |
| |
| <file>:: |
| Files to act on. |
| Note that files beginning with '.' are discarded. This includes |
| `./file` and `dir/./file`. If you don't want this, then use |
| cleaner names. |
| The same applies to directories ending '/' and paths with '//' |
| |
| USING --REFRESH |
| --------------- |
| `--refresh` does not calculate a new sha1 file or bring the index |
| up to date for mode/content changes. But what it *does* do is to |
| "re-match" the stat information of a file with the index, so that you |
| can refresh the index for a file that hasn't been changed but where |
| the stat entry is out of date. |
| |
| For example, you'd want to do this after doing a 'git read-tree', to link |
| up the stat index details with the proper files. |
| |
| USING --CACHEINFO OR --INFO-ONLY |
| -------------------------------- |
| `--cacheinfo` is used to register a file that is not in the |
| current working directory. This is useful for minimum-checkout |
| merging. |
| |
| To pretend you have a file at path with mode and sha1, say: |
| |
| ---------------- |
| $ git update-index --add --cacheinfo <mode>,<sha1>,<path> |
| ---------------- |
| |
| `--info-only` is used to register files without placing them in the object |
| database. This is useful for status-only repositories. |
| |
| Both `--cacheinfo` and `--info-only` behave similarly: the index is updated |
| but the object database isn't. `--cacheinfo` is useful when the object is |
| in the database but the file isn't available locally. `--info-only` is |
| useful when the file is available, but you do not wish to update the |
| object database. |
| |
| |
| USING --INDEX-INFO |
| ------------------ |
| |
| `--index-info` is a more powerful mechanism that lets you feed |
| multiple entry definitions from the standard input, and designed |
| specifically for scripts. It can take inputs of three formats: |
| |
| . mode SP type SP sha1 TAB path |
| + |
| 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. |
| |
| For example, starting with this index: |
| |
| ------------ |
| $ git ls-files -s |
| 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0 frotz |
| ------------ |
| |
| you can feed the following input to `--index-info`: |
| |
| ------------ |
| $ git update-index --index-info |
| 0 0000000000000000000000000000000000000000 frotz |
| 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz |
| 100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz |
| ------------ |
| |
| The first line of the input feeds 0 as the mode to remove the |
| path; the SHA-1 does not matter as long as it is well formatted. |
| Then the second and third line feeds stage 1 and stage 2 entries |
| for that path. After the above, we would end up with this: |
| |
| ------------ |
| $ git ls-files -s |
| 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz |
| 100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz |
| ------------ |
| |
| |
| USING ``ASSUME UNCHANGED'' BIT |
| ------------------------------ |
| |
| Many operations in Git depend on your filesystem to have an |
| efficient `lstat(2)` implementation, so that `st_mtime` |
| information for working tree files can be cheaply checked to see |
| if the file contents have changed from the version recorded in |
| the index file. Unfortunately, some filesystems have |
| inefficient `lstat(2)`. If your filesystem is one of them, you |
| can set "assume unchanged" bit to paths you have not changed to |
| cause Git not to do this check. Note that setting this bit on a |
| path does not mean Git will check the contents of the file to |
| see if it has changed -- it makes Git to omit any checking and |
| assume it has *not* changed. When you make changes to working |
| tree files, you have to explicitly tell Git about it by dropping |
| "assume unchanged" bit, either before or after you modify them. |
| |
| In order to set "assume unchanged" bit, use `--assume-unchanged` |
| option. To unset, use `--no-assume-unchanged`. To see which files |
| have the "assume unchanged" bit set, use `git ls-files -v` |
| (see linkgit:git-ls-files[1]). |
| |
| The command looks at `core.ignorestat` configuration variable. When |
| this is true, paths updated with `git update-index paths...` and |
| paths updated with other Git commands that update both index and |
| working tree (e.g. 'git apply --index', 'git checkout-index -u', |
| and 'git read-tree -u') are automatically marked as "assume |
| unchanged". Note that "assume unchanged" bit is *not* set if |
| `git update-index --refresh` finds the working tree file matches |
| 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 |
| -------- |
| To update and refresh only the files already checked out: |
| |
| ---------------- |
| $ git checkout-index -n -f -a && git update-index --ignore-missing --refresh |
| ---------------- |
| |
| On an inefficient filesystem with `core.ignorestat` set:: |
| + |
| ------------ |
| $ git update-index --really-refresh <1> |
| $ git update-index --no-assume-unchanged foo.c <2> |
| $ git diff --name-only <3> |
| $ edit foo.c |
| $ git diff --name-only <4> |
| M foo.c |
| $ git update-index foo.c <5> |
| $ git diff --name-only <6> |
| $ edit foo.c |
| $ git diff --name-only <7> |
| $ git update-index --no-assume-unchanged foo.c <8> |
| $ git diff --name-only <9> |
| M foo.c |
| ------------ |
| + |
| <1> forces lstat(2) to set "assume unchanged" bits for paths that match index. |
| <2> mark the path to be edited. |
| <3> this does lstat(2) and finds index matches the path. |
| <4> this does lstat(2) and finds index does *not* match the path. |
| <5> registering the new version to index sets "assume unchanged" bit. |
| <6> and it is assumed unchanged. |
| <7> even after you edit it. |
| <8> you can tell about the change after the fact. |
| <9> now it checks with lstat(2) and finds it has been changed. |
| |
| |
| SKIP-WORKTREE BIT |
| ----------------- |
| |
| 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. 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 |
| ----------- |
| |
| This mode is designed for repositories with very large indexes, and |
| aims at reducing the time it takes to repeatedly write these indexes. |
| |
| In this mode, the index is split into two files, $GIT_DIR/index and |
| $GIT_DIR/sharedindex.<SHA-1>. Changes are accumulated in |
| $GIT_DIR/index, the split index, while the shared index file contains |
| all index entries and stays unchanged. |
| |
| All changes in the split index are pushed back to the shared index |
| file when the number of entries in the split index reaches a level |
| specified by the splitIndex.maxPercentChange config variable (see |
| linkgit:git-config[1]). |
| |
| Each time a new shared index file is created, the old shared index |
| files are deleted if their modification time is older than what is |
| 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 every time a new split |
| index based on the shared index file is either created or read from. |
| |
| UNTRACKED CACHE |
| --------------- |
| |
| This cache is meant to speed up commands that involve determining |
| untracked files such as `git status`. |
| |
| This feature works by recording the mtime of the working tree |
| directories and then omitting reading directories and stat calls |
| against files in those directories whose mtime hasn't changed. For |
| this to work the underlying operating system and file system must |
| change the `st_mtime` field of directories if files in the directory |
| are added, modified or deleted. |
| |
| You can test whether the filesystem supports that with the |
| `--test-untracked-cache` option. The `--untracked-cache` option used |
| to implicitly perform that test in older versions of Git, but that's |
| no longer the case. |
| |
| If you want to enable (or disable) this feature, it is easier to use |
| the `core.untrackedCache` configuration variable (see |
| linkgit:git-config[1]) than using the `--untracked-cache` 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 to `true` (or `false`) in your `$HOME/.gitconfig` just once |
| and have it affect all repositories you touch. |
| |
| When the `core.untrackedCache` configuration variable is changed, the |
| untracked cache is added to or removed from the index the next time a |
| command reads the index; while when `--[no-|force-]untracked-cache` |
| are used, the untracked cache is immediately added to or removed from |
| the index. |
| |
| Before 2.17, the untracked cache had a bug where replacing a directory |
| with a symlink to another directory could cause it to incorrectly show |
| files tracked by git as untracked. See the "status: add a failing test |
| showing a core.untrackedCache bug" commit to git.git. A workaround for |
| that is (and this might work for other undiscovered bugs in the |
| future): |
| |
| ---------------- |
| $ git -c core.untrackedCache=false status |
| ---------------- |
| |
| This bug has also been shown to affect non-symlink cases of replacing |
| a directory with a file when it comes to the internal structures of |
| the untracked cache, but no case has been reported where this resulted in |
| wrong "git status" output. |
| |
| There are also cases where existing indexes written by git versions |
| before 2.17 will reference directories that don't exist anymore, |
| potentially causing many "could not open directory" warnings to be |
| printed on "git status". These are new warnings for existing issues |
| that were previously silently discarded. |
| |
| As with the bug described above the solution is to one-off do a "git |
| status" run with `core.untrackedCache=false` to flush out the leftover |
| bad data. |
| |
| 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 |
| 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. |
| |
| When used in conjunction with the untracked cache, it can further improve |
| performance by avoiding the cost of scanning the entire working directory |
| 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 |
| 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. |
| |
| When the `core.fsmonitor` configuration variable is changed, the |
| file system monitor is added to or removed from the index the next time |
| a command reads the index. When `--[no-]fsmonitor` are used, the file |
| system monitor is immediately added to or removed from the index. |
| |
| CONFIGURATION |
| ------------- |
| |
| The command honors `core.filemode` configuration variable. If |
| your repository is on a filesystem whose executable bits are |
| unreliable, this should be set to 'false' (see linkgit:git-config[1]). |
| This causes the command to ignore differences in file modes recorded |
| in the index and the file mode on the filesystem if they differ only on |
| executable bit. On such an unfortunate filesystem, you may |
| need to use 'git update-index --chmod='. |
| |
| Quite similarly, if `core.symlinks` configuration variable is set |
| to 'false' (see linkgit:git-config[1]), symbolic links are checked out |
| as plain files, and this command does not modify a recorded file mode |
| from symbolic link to regular file. |
| |
| The command looks at `core.ignorestat` configuration variable. See |
| 'Using "assume unchanged" bit' section above. |
| |
| The command also looks at `core.trustctime` configuration variable. |
| It can be useful when the inode change time is regularly modified by |
| something outside Git (file system crawlers and backup systems use |
| ctime for marking files processed) (see linkgit:git-config[1]). |
| |
| 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], |
| linkgit:git-add[1], |
| linkgit:git-ls-files[1] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |