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