freshlybakedca.ke
Git fork
1git-update-index(1)
2===================
3
4NAME
5----
6git-update-index - Register file contents in the working tree to the index
7
8
9SYNOPSIS
10--------
11[verse]
12'git update-index'
13 [--add] [--remove | --force-remove] [--replace]
14 [--refresh] [-q] [--unmerged] [--ignore-missing]
15 [(--cacheinfo <mode>,<object>,<file>)...]
16 [--chmod=(+|-)x]
17 [--[no-]assume-unchanged]
18 [--[no-]skip-worktree]
19 [--[no-]ignore-skip-worktree-entries]
20 [--[no-]fsmonitor-valid]
21 [--ignore-submodules]
22 [--[no-]split-index]
23 [--[no-|test-|force-]untracked-cache]
24 [--[no-]fsmonitor]
25 [--really-refresh] [--unresolve] [--again | -g]
26 [--info-only] [--index-info]
27 [-z] [--stdin] [--index-version <n>]
28 [--show-index-version]
29 [--verbose]
30 [--] [<file>...]
31
32DESCRIPTION
33-----------
34Modifies the index. Each file mentioned is updated into the index and
35any 'unmerged' or 'needs updating' state is cleared.
36
37See also linkgit:git-add[1] for a more user-friendly way to do some of
38the most common operations on the index.
39
40The way 'git update-index' handles files it is told about can be modified
41using the various options:
42
43OPTIONS
44-------
45--add::
46 If a specified file isn't in the index already then it's
47 added.
48 Default behaviour is to ignore new files.
49
50--remove::
51 If a specified file is in the index but is missing then it's
52 removed.
53 Default behavior is to ignore removed files.
54
55--refresh::
56 Looks at the current index and checks to see if merges or
57 updates are needed by checking stat() information.
58
59-q::
60 Quiet. If --refresh finds that the index needs an update, the
61 default behavior is to error out. This option makes
62 'git update-index' continue anyway.
63
64--ignore-submodules::
65 Do not try to update submodules. This option is only respected
66 when passed before --refresh.
67
68--unmerged::
69 If --refresh finds unmerged changes in the index, the default
70 behavior is to error out. This option makes 'git update-index'
71 continue anyway.
72
73--ignore-missing::
74 Ignores missing files during a --refresh
75
76--cacheinfo <mode>,<object>,<path>::
77--cacheinfo <mode> <object> <path>::
78 Directly insert the specified info into the index. For
79 backward compatibility, you can also give these three
80 arguments as three separate parameters, but new users are
81 encouraged to use a single-parameter form.
82
83--index-info::
84 Read index information from stdin.
85
86--chmod=(+|-)x::
87 Set the execute permissions on the updated files.
88
89--assume-unchanged::
90--no-assume-unchanged::
91 When this flag is specified, the object names recorded
92 for the paths are not updated. Instead, this option
93 sets/unsets the "assume unchanged" bit for the
94 paths. When the "assume unchanged" bit is on, the user
95 promises not to change the file and allows Git to assume
96 that the working tree file matches what is recorded in
97 the index. If you want to change the working tree file,
98 you need to unset the bit to tell Git. This is
99 sometimes helpful when working with a big project on a
100 filesystem that has a very slow lstat(2) system call
101 (e.g. cifs).
102+
103Git will fail (gracefully) in case it needs to modify this file
104in the index e.g. when merging in a commit;
105thus, in case the assumed-untracked file is changed upstream,
106you will need to handle the situation manually.
107
108--really-refresh::
109 Like `--refresh`, but checks stat information unconditionally,
110 without regard to the "assume unchanged" setting.
111
112--skip-worktree::
113--no-skip-worktree::
114 When one of these flags is specified, the object names recorded
115 for the paths are not updated. Instead, these options
116 set and unset the "skip-worktree" bit for the paths. See
117 section "Skip-worktree bit" below for more information.
118
119
120--ignore-skip-worktree-entries::
121--no-ignore-skip-worktree-entries::
122 Do not remove skip-worktree (AKA "index-only") entries even when
123 the `--remove` option was specified.
124
125--fsmonitor-valid::
126--no-fsmonitor-valid::
127 When one of these flags is specified, the object names recorded
128 for the paths are not updated. Instead, these options
129 set and unset the "fsmonitor valid" bit for the paths. See
130 section "File System Monitor" below for more information.
131
132-g::
133--again::
134 Runs 'git update-index' itself on the paths whose index
135 entries are different from those of the `HEAD` commit.
136
137--unresolve::
138 Restores the 'unmerged' or 'needs updating' state of a
139 file during a merge if it was cleared by accident.
140
141--info-only::
142 Do not create objects in the object database for all
143 <file> arguments that follow this flag; just insert
144 their object IDs into the index.
145
146--force-remove::
147 Remove the file from the index even when the working directory
148 still has such a file. (Implies --remove.)
149
150--replace::
151 By default, when a file `path` exists in the index,
152 'git update-index' refuses an attempt to add `path/file`.
153 Similarly if a file `path/file` exists, a file `path`
154 cannot be added. With --replace flag, existing entries
155 that conflict with the entry being added are
156 automatically removed with warning messages.
157
158--stdin::
159 Instead of taking a list of paths from the command line,
160 read a list of paths from the standard input. Paths are
161 separated by LF (i.e. one path per line) by default.
162
163--verbose::
164 Report what is being added and removed from the index.
165
166--index-version <n>::
167 Write the resulting index out in the named on-disk format version.
168 Supported versions are 2, 3, and 4. The current default version is 2
169 or 3, depending on whether extra features are used, such as
170 `git add -N`. With `--verbose`, also report the version the index
171 file uses before and after this command.
172+
173Version 4 performs a simple pathname compression that reduces index
174size by 30%-50% on large repositories, which results in faster load
175time. Git supports it since version 1.8.0, released in October 2012,
176and support for it was added to libgit2 in 2016 and to JGit in 2020.
177Older versions of this manual page called it "relatively young", but
178it should be considered mature technology these days.
179
180--show-index-version::
181 Report the index format version used by the on-disk index file.
182 See `--index-version` above.
183
184-z::
185 Only meaningful with `--stdin` or `--index-info`; paths are
186 separated with NUL character instead of LF.
187
188--split-index::
189--no-split-index::
190 Enable or disable split index mode. If split-index mode is
191 already enabled and `--split-index` is given again, all
192 changes in $GIT_DIR/index are pushed back to the shared index
193 file.
194+
195These options take effect whatever the value of the `core.splitIndex`
196configuration variable (see linkgit:git-config[1]). But a warning is
197emitted when the change goes against the configured value, as the
198configured value will take effect next time the index is read and this
199will remove the intended effect of the option.
200
201--untracked-cache::
202--no-untracked-cache::
203 Enable or disable untracked cache feature. Please use
204 `--test-untracked-cache` before enabling it.
205+
206These options take effect whatever the value of the `core.untrackedCache`
207configuration variable (see linkgit:git-config[1]). But a warning is
208emitted when the change goes against the configured value, as the
209configured value will take effect next time the index is read and this
210will remove the intended effect of the option.
211
212--test-untracked-cache::
213 Only perform tests on the working directory to make sure
214 untracked cache can be used. You have to manually enable
215 untracked cache using `--untracked-cache` or
216 `--force-untracked-cache` or the `core.untrackedCache`
217 configuration variable afterwards if you really want to use
218 it. If a test fails the exit code is 1 and a message
219 explains what is not working as needed, otherwise the exit
220 code is 0 and OK is printed.
221
222--force-untracked-cache::
223 Same as `--untracked-cache`. Provided for backwards
224 compatibility with older versions of Git where
225 `--untracked-cache` used to imply `--test-untracked-cache` but
226 this option would enable the extension unconditionally.
227
228--fsmonitor::
229--no-fsmonitor::
230 Enable or disable files system monitor feature. These options
231 take effect whatever the value of the `core.fsmonitor`
232 configuration variable (see linkgit:git-config[1]). But a warning
233 is emitted when the change goes against the configured value, as
234 the configured value will take effect next time the index is
235 read and this will remove the intended effect of the option.
236
237\--::
238 Do not interpret any more arguments as options.
239
240<file>::
241 Files to act on.
242 Note that files beginning with '.' are discarded. This includes
243 `./file` and `dir/./file`. If you don't want this, then use
244 cleaner names.
245 The same applies to directories ending '/' and paths with '//'
246
247USING --REFRESH
248---------------
249`--refresh` does not calculate a new sha1 file or bring the index
250up to date for mode/content changes. But what it *does* do is to
251"re-match" the stat information of a file with the index, so that you
252can refresh the index for a file that hasn't been changed but where
253the stat entry is out of date.
254
255For example, you'd want to do this after doing a 'git read-tree', to link
256up the stat index details with the proper files.
257
258USING --CACHEINFO OR --INFO-ONLY
259--------------------------------
260`--cacheinfo` is used to register a file that is not in the
261current working directory. This is useful for minimum-checkout
262merging.
263
264To pretend you have a file at path with mode and sha1, say:
265
266----------------
267$ git update-index --add --cacheinfo <mode>,<sha1>,<path>
268----------------
269
270`--info-only` is used to register files without placing them in the object
271database. This is useful for status-only repositories.
272
273Both `--cacheinfo` and `--info-only` behave similarly: the index is updated
274but the object database isn't. `--cacheinfo` is useful when the object is
275in the database but the file isn't available locally. `--info-only` is
276useful when the file is available, but you do not wish to update the
277object database.
278
279
280USING --INDEX-INFO
281------------------
282
283`--index-info` is a more powerful mechanism that lets you feed
284multiple entry definitions from the standard input, and designed
285specifically for scripts. It can take inputs of three formats:
286
287 . mode SP type SP sha1 TAB path
288+
289This format is to stuff `git ls-tree` output into the index.
290
291 . mode SP sha1 SP stage TAB path
292+
293This format is to put higher order stages into the
294index file and matches 'git ls-files --stage' output.
295
296 . mode SP sha1 TAB path
297+
298This format is no longer produced by any Git command, but is
299and will continue to be supported by `update-index --index-info`.
300
301To place a higher stage entry to the index, the path should
302first be removed by feeding a mode=0 entry for the path, and
303then feeding necessary input lines in the third format.
304
305For example, starting with this index:
306
307------------
308$ git ls-files -s
309100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0 frotz
310------------
311
312you can feed the following input to `--index-info`:
313
314------------
315$ git update-index --index-info
3160 0000000000000000000000000000000000000000 frotz
317100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz
318100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz
319------------
320
321The first line of the input feeds 0 as the mode to remove the
322path; the SHA-1 does not matter as long as it is well formatted.
323Then the second and third line feeds stage 1 and stage 2 entries
324for that path. After the above, we would end up with this:
325
326------------
327$ git ls-files -s
328100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz
329100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz
330------------
331
332
333USING ``ASSUME UNCHANGED'' BIT
334------------------------------
335
336Many operations in Git depend on your filesystem to have an
337efficient `lstat(2)` implementation, so that `st_mtime`
338information for working tree files can be cheaply checked to see
339if the file contents have changed from the version recorded in
340the index file. Unfortunately, some filesystems have
341inefficient `lstat(2)`. If your filesystem is one of them, you
342can set "assume unchanged" bit to paths you have not changed to
343cause Git not to do this check. Note that setting this bit on a
344path does not mean Git will check the contents of the file to
345see if it has changed -- it makes Git to omit any checking and
346assume it has *not* changed. When you make changes to working
347tree files, you have to explicitly tell Git about it by dropping
348"assume unchanged" bit, either before or after you modify them.
349
350In order to set "assume unchanged" bit, use `--assume-unchanged`
351option. To unset, use `--no-assume-unchanged`. To see which files
352have the "assume unchanged" bit set, use `git ls-files -v`
353(see linkgit:git-ls-files[1]).
354
355The command looks at `core.ignorestat` configuration variable. When
356this is true, paths updated with `git update-index paths...` and
357paths updated with other Git commands that update both index and
358working tree (e.g. 'git apply --index', 'git checkout-index -u',
359and 'git read-tree -u') are automatically marked as "assume
360unchanged". Note that "assume unchanged" bit is *not* set if
361`git update-index --refresh` finds the working tree file matches
362the index (use `git update-index --really-refresh` if you want
363to mark them as "assume unchanged").
364
365Sometimes users confuse the assume-unchanged bit with the
366skip-worktree bit. See the final paragraph in the "Skip-worktree bit"
367section below for an explanation of the differences.
368
369
370EXAMPLES
371--------
372To update and refresh only the files already checked out:
373
374----------------
375$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
376----------------
377
378On an inefficient filesystem with `core.ignorestat` set::
379+
380------------
381$ git update-index --really-refresh <1>
382$ git update-index --no-assume-unchanged foo.c <2>
383$ git diff --name-only <3>
384$ edit foo.c
385$ git diff --name-only <4>
386M foo.c
387$ git update-index foo.c <5>
388$ git diff --name-only <6>
389$ edit foo.c
390$ git diff --name-only <7>
391$ git update-index --no-assume-unchanged foo.c <8>
392$ git diff --name-only <9>
393M foo.c
394------------
395+
396<1> forces lstat(2) to set "assume unchanged" bits for paths that match index.
397<2> mark the path to be edited.
398<3> this does lstat(2) and finds index matches the path.
399<4> this does lstat(2) and finds index does *not* match the path.
400<5> registering the new version to index sets "assume unchanged" bit.
401<6> and it is assumed unchanged.
402<7> even after you edit it.
403<8> you can tell about the change after the fact.
404<9> now it checks with lstat(2) and finds it has been changed.
405
406
407SKIP-WORKTREE BIT
408-----------------
409
410Skip-worktree bit can be defined in one (long) sentence: Tell git to
411avoid writing the file to the working directory when reasonably
412possible, and treat the file as unchanged when it is not
413present in the working directory.
414
415Note that not all git commands will pay attention to this bit, and
416some only partially support it.
417
418The update-index flags and the read-tree capabilities relating to the
419skip-worktree bit predated the introduction of the
420linkgit:git-sparse-checkout[1] command, which provides a much easier
421way to configure and handle the skip-worktree bits. If you want to
422reduce your working tree to only deal with a subset of the files in
423the repository, we strongly encourage the use of
424linkgit:git-sparse-checkout[1] in preference to the low-level
425update-index and read-tree primitives.
426
427The primary purpose of the skip-worktree bit is to enable sparse
428checkouts, i.e. to have working directories with only a subset of
429paths present. When the skip-worktree bit is set, Git commands (such
430as `switch`, `pull`, `merge`) will avoid writing these files.
431However, these commands will sometimes write these files anyway in
432important cases such as conflicts during a merge or rebase. Git
433commands will also avoid treating the lack of such files as an
434intentional deletion; for example `git add -u` will not stage a
435deletion for these files and `git commit -a` will not make a commit
436deleting them either.
437
438Although this bit looks similar to assume-unchanged bit, its goal is
439different. The assume-unchanged bit is for leaving the file in the
440working tree but having Git omit checking it for changes and presuming
441that the file has not been changed (though if it can determine without
442stat'ing the file that it has changed, it is free to record the
443changes). skip-worktree tells Git to ignore the absence of the file,
444avoid updating it when possible with commands that normally update
445much of the working directory (e.g. `checkout`, `switch`, `pull`,
446etc.), and not have its absence be recorded in commits. Note that in
447sparse checkouts (setup by `git sparse-checkout` or by configuring
448core.sparseCheckout to true), if a file is marked as skip-worktree in
449the index but is found in the working tree, Git will clear the
450skip-worktree bit for that file.
451
452SPLIT INDEX
453-----------
454
455This mode is designed for repositories with very large indexes, and
456aims at reducing the time it takes to repeatedly write these indexes.
457
458In this mode, the index is split into two files, $GIT_DIR/index and
459$GIT_DIR/sharedindex.<SHA-1>. Changes are accumulated in
460$GIT_DIR/index, the split index, while the shared index file contains
461all index entries and stays unchanged.
462
463All changes in the split index are pushed back to the shared index
464file when the number of entries in the split index reaches a level
465specified by the splitIndex.maxPercentChange config variable (see
466linkgit:git-config[1]).
467
468Each time a new shared index file is created, the old shared index
469files are deleted if their modification time is older than what is
470specified by the splitIndex.sharedIndexExpire config variable (see
471linkgit:git-config[1]).
472
473To avoid deleting a shared index file that is still used, its
474modification time is updated to the current time every time a new split
475index based on the shared index file is either created or read from.
476
477UNTRACKED CACHE
478---------------
479
480This cache is meant to speed up commands that involve determining
481untracked files such as `git status`.
482
483This feature works by recording the mtime of the working tree
484directories and then omitting reading directories and stat calls
485against files in those directories whose mtime hasn't changed. For
486this to work the underlying operating system and file system must
487change the `st_mtime` field of directories if files in the directory
488are added, modified or deleted.
489
490You can test whether the filesystem supports that with the
491`--test-untracked-cache` option. The `--untracked-cache` option used
492to implicitly perform that test in older versions of Git, but that's
493no longer the case.
494
495If you want to enable (or disable) this feature, it is easier to use
496the `core.untrackedCache` configuration variable (see
497linkgit:git-config[1]) than using the `--untracked-cache` option to
498`git update-index` in each repository, especially if you want to do so
499across all repositories you use, because you can set the configuration
500variable to `true` (or `false`) in your `$HOME/.gitconfig` just once
501and have it affect all repositories you touch.
502
503When the `core.untrackedCache` configuration variable is changed, the
504untracked cache is added to or removed from the index the next time a
505command reads the index; while when `--[no-|force-]untracked-cache`
506are used, the untracked cache is immediately added to or removed from
507the index.
508
509Before 2.17, the untracked cache had a bug where replacing a directory
510with a symlink to another directory could cause it to incorrectly show
511files tracked by git as untracked. See the "status: add a failing test
512showing a core.untrackedCache bug" commit to git.git. A workaround for
513that is (and this might work for other undiscovered bugs in the
514future):
515
516----------------
517$ git -c core.untrackedCache=false status
518----------------
519
520This bug has also been shown to affect non-symlink cases of replacing
521a directory with a file when it comes to the internal structures of
522the untracked cache, but no case has been reported where this resulted in
523wrong "git status" output.
524
525There are also cases where existing indexes written by git versions
526before 2.17 will reference directories that don't exist anymore,
527potentially causing many "could not open directory" warnings to be
528printed on "git status". These are new warnings for existing issues
529that were previously silently discarded.
530
531As with the bug described above the solution is to one-off do a "git
532status" run with `core.untrackedCache=false` to flush out the leftover
533bad data.
534
535FILE SYSTEM MONITOR
536-------------------
537
538This feature is intended to speed up git operations for repos that have
539large working directories.
540
541It enables git to work together with a file system monitor (see
542linkgit:git-fsmonitor{litdd}daemon[1]
543and the
544"fsmonitor-watchman" section of linkgit:githooks[5]) that can
545inform it as to what files have been modified. This enables git to avoid
546having to lstat() every file to find modified files.
547
548When used in conjunction with the untracked cache, it can further improve
549performance by avoiding the cost of scanning the entire working directory
550looking for new files.
551
552If you want to enable (or disable) this feature, it is easier to use
553the `core.fsmonitor` configuration variable (see
554linkgit:git-config[1]) than using the `--fsmonitor` option to `git
555update-index` in each repository, especially if you want to do so
556across all repositories you use, because you can set the configuration
557variable in your `$HOME/.gitconfig` just once and have it affect all
558repositories you touch.
559
560When the `core.fsmonitor` configuration variable is changed, the
561file system monitor is added to or removed from the index the next time
562a command reads the index. When `--[no-]fsmonitor` are used, the file
563system monitor is immediately added to or removed from the index.
564
565CONFIGURATION
566-------------
567
568The command honors `core.filemode` configuration variable. If
569your repository is on a filesystem whose executable bits are
570unreliable, this should be set to 'false' (see linkgit:git-config[1]).
571This causes the command to ignore differences in file modes recorded
572in the index and the file mode on the filesystem if they differ only on
573executable bit. On such an unfortunate filesystem, you may
574need to use 'git update-index --chmod='.
575
576Quite similarly, if `core.symlinks` configuration variable is set
577to 'false' (see linkgit:git-config[1]), symbolic links are checked out
578as plain files, and this command does not modify a recorded file mode
579from symbolic link to regular file.
580
581The command looks at `core.ignorestat` configuration variable. See
582'Using "assume unchanged" bit' section above.
583
584The command also looks at `core.trustctime` configuration variable.
585It can be useful when the inode change time is regularly modified by
586something outside Git (file system crawlers and backup systems use
587ctime for marking files processed) (see linkgit:git-config[1]).
588
589The untracked cache extension can be enabled by the
590`core.untrackedCache` configuration variable (see
591linkgit:git-config[1]).
592
593NOTES
594-----
595
596Users often try to use the assume-unchanged and skip-worktree bits
597to tell Git to ignore changes to files that are tracked. This does not
598work as expected, since Git may still check working tree files against
599the index when performing certain operations. In general, Git does not
600provide a way to ignore changes to tracked files, so alternate solutions
601are recommended.
602
603For example, if the file you want to change is some sort of config file,
604the repository can include a sample config file that can then be copied
605into the ignored name and modified. The repository can even include a
606script to treat the sample file as a template, modifying and copying it
607automatically.
608
609SEE ALSO
610--------
611linkgit:git-config[1],
612linkgit:git-add[1],
613linkgit:git-ls-files[1]
614
615GIT
616---
617Part of the linkgit:git[1] suite