Documentation/git-update-index.txt

   1 git-update-index(1)
   2 ===================
   3
   4 NAME
   5 ----
   6 git-update-index - Register file contents in the working tree to the index
   7
   8
   9 SYNOPSIS
  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              [--assume-unchanged | --no-assume-unchanged]
  18              [--ignore-submodules]
  19              [--really-refresh] [--unresolve] [--again | -g]
  20              [--info-only] [--index-info]
  21              [-z] [--stdin]
  22              [--verbose]
  23              [--] [<file>]\*
  24
  25 DESCRIPTION
  26 -----------
  27 Modifies the index or directory cache. Each file mentioned is updated
  28 into the index and any 'unmerged' or 'needs updating' state is
  29 cleared.
  30
  31 See also linkgit:git-add[1] for a more user-friendly way to do some of
  32 the most common operations on the index.
  33
  34 The way "git-update-index" handles files it is told about can be modified
  35 using the various options:
  36
  37 OPTIONS
  38 -------
  39 --add::
  40         If a specified file isn't in the index already then it's
  41         added.
  42         Default behaviour is to ignore new files.
  43
  44 --remove::
  45         If a specified file is in the index but is missing then it's
  46         removed.
  47         Default behavior is to ignore removed file.
  48
  49 --refresh::
  50         Looks at the current index and checks to see if merges or
  51         updates are needed by checking stat() information.
  52
  53 -q::
  54         Quiet.  If --refresh finds that the index needs an update, the
  55         default behavior is to error out.  This option makes
  56         git-update-index continue anyway.
  57
  58 --ignore-submodules:
  59         Do not try to update submodules.  This option is only respected
  60         when passed before --refresh.
  61
  62 --unmerged::
  63         If --refresh finds unmerged changes in the index, the default
  64         behavior is to error out.  This option makes git-update-index
  65         continue anyway.
  66
  67 --ignore-missing::
  68         Ignores missing files during a --refresh
  69
  70 --cacheinfo <mode> <object> <path>::
  71         Directly insert the specified info into the index.
  72
  73 --index-info::
  74         Read index information from stdin.
  75
  76 --chmod=(+|-)x::
  77         Set the execute permissions on the updated files.
  78
  79 --assume-unchanged, --no-assume-unchanged::
  80         When these flags are specified, the object name recorded
  81         for the paths are not updated.  Instead, these options
  82         sets and unsets the "assume unchanged" bit for the
  83         paths.  When the "assume unchanged" bit is on, git stops
  84         checking the working tree files for possible
  85         modifications, so you need to manually unset the bit to
  86         tell git when you change the working tree file. This is
  87         sometimes helpful when working with a big project on a
  88         filesystem that has very slow lstat(2) system call
  89         (e.g. cifs).
  90
  91 --again, -g::
  92         Runs `git-update-index` itself on the paths whose index
  93         entries are different from those from the `HEAD` commit.
  94
  95 --unresolve::
  96         Restores the 'unmerged' or 'needs updating' state of a
  97         file during a merge if it was cleared by accident.
  98
  99 --info-only::
 100         Do not create objects in the object database for all
 101         <file> arguments that follow this flag; just insert
 102         their object IDs into the index.
 103
 104 --force-remove::
 105         Remove the file from the index even when the working directory
 106         still has such a file. (Implies --remove.)
 107
 108 --replace::
 109         By default, when a file `path` exists in the index,
 110         git-update-index refuses an attempt to add `path/file`.
 111         Similarly if a file `path/file` exists, a file `path`
 112         cannot be added.  With --replace flag, existing entries
 113         that conflicts with the entry being added are
 114         automatically removed with warning messages.
 115
 116 --stdin::
 117         Instead of taking list of paths from the command line,
 118         read list of paths from the standard input.  Paths are
 119         separated by LF (i.e. one path per line) by default.
 120
 121 --verbose::
 122         Report what is being added and removed from index.
 123
 124 -z::
 125         Only meaningful with `--stdin`; paths are separated with
 126         NUL character instead of LF.
 127
 128 \--::
 129         Do not interpret any more arguments as options.
 130
 131 <file>::
 132         Files to act on.
 133         Note that files beginning with '.' are discarded. This includes
 134         `./file` and `dir/./file`. If you don't want this, then use
 135         cleaner names.
 136         The same applies to directories ending '/' and paths with '//'
 137
 138 Using --refresh
 139 ---------------
 140 '--refresh' does not calculate a new sha1 file or bring the index
 141 up-to-date for mode/content changes. But what it *does* do is to
 142 "re-match" the stat information of a file with the index, so that you
 143 can refresh the index for a file that hasn't been changed but where
 144 the stat entry is out of date.
 145
 146 For example, you'd want to do this after doing a "git-read-tree", to link
 147 up the stat index details with the proper files.
 148
 149 Using --cacheinfo or --info-only
 150 --------------------------------
 151 '--cacheinfo' is used to register a file that is not in the
 152 current working directory.  This is useful for minimum-checkout
 153 merging.
 154
 155 To pretend you have a file with mode and sha1 at path, say:
 156
 157 ----------------
 158 $ git-update-index --cacheinfo mode sha1 path
 159 ----------------
 160
 161 '--info-only' is used to register files without placing them in the object
 162 database.  This is useful for status-only repositories.
 163
 164 Both '--cacheinfo' and '--info-only' behave similarly: the index is updated
 165 but the object database isn't.  '--cacheinfo' is useful when the object is
 166 in the database but the file isn't available locally.  '--info-only' is
 167 useful when the file is available, but you do not wish to update the
 168 object database.
 169
 170
 171 Using --index-info
 172 ------------------
 173
 174 `--index-info` is a more powerful mechanism that lets you feed
 175 multiple entry definitions from the standard input, and designed
 176 specifically for scripts.  It can take inputs of three formats:
 177
 178     . mode         SP sha1          TAB path
 179 +
 180 The first format is what "git-apply --index-info"
 181 reports, and used to reconstruct a partial tree
 182 that is used for phony merge base tree when falling
 183 back on 3-way merge.
 184
 185     . mode SP type SP sha1          TAB path
 186 +
 187 The second format is to stuff git-ls-tree output
 188 into the index file.
 189
 190     . mode         SP sha1 SP stage TAB path
 191 +
 192 This format is to put higher order stages into the
 193 index file and matches git-ls-files --stage output.
 194
 195 To place a higher stage entry to the index, the path should
 196 first be removed by feeding a mode=0 entry for the path, and
 197 then feeding necessary input lines in the third format.
 198
 199 For example, starting with this index:
 200
 201 ------------
 202 $ git ls-files -s
 203 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 0       frotz
 204 ------------
 205
 206 you can feed the following input to `--index-info`:
 207
 208 ------------
 209 $ git update-index --index-info
 210 0 0000000000000000000000000000000000000000      frotz
 211 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1       frotz
 212 100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2       frotz
 213 ------------
 214
 215 The first line of the input feeds 0 as the mode to remove the
 216 path; the SHA1 does not matter as long as it is well formatted.
 217 Then the second and third line feeds stage 1 and stage 2 entries
 218 for that path.  After the above, we would end up with this:
 219
 220 ------------
 221 $ git ls-files -s
 222 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1       frotz
 223 100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2       frotz
 224 ------------
 225
 226
 227 Using ``assume unchanged'' bit
 228 ------------------------------
 229
 230 Many operations in git depend on your filesystem to have an
 231 efficient `lstat(2)` implementation, so that `st_mtime`
 232 information for working tree files can be cheaply checked to see
 233 if the file contents have changed from the version recorded in
 234 the index file.  Unfortunately, some filesystems have
 235 inefficient `lstat(2)`.  If your filesystem is one of them, you
 236 can set "assume unchanged" bit to paths you have not changed to
 237 cause git not to do this check.  Note that setting this bit on a
 238 path does not mean git will check the contents of the file to
 239 see if it has changed -- it makes git to omit any checking and
 240 assume it has *not* changed.  When you make changes to working
 241 tree files, you have to explicitly tell git about it by dropping
 242 "assume unchanged" bit, either before or after you modify them.
 243
 244 In order to set "assume unchanged" bit, use `--assume-unchanged`
 245 option.  To unset, use `--no-assume-unchanged`.
 246
 247 The command looks at `core.ignorestat` configuration variable.  When
 248 this is true, paths updated with `git-update-index paths...` and
 249 paths updated with other git commands that update both index and
 250 working tree (e.g. `git-apply --index`, `git-checkout-index -u`,
 251 and `git-read-tree -u`) are automatically marked as "assume
 252 unchanged".  Note that "assume unchanged" bit is *not* set if
 253 `git-update-index --refresh` finds the working tree file matches
 254 the index (use `git-update-index --really-refresh` if you want
 255 to mark them as "assume unchanged").
 256
 257
 258 Examples
 259 --------
 260 To update and refresh only the files already checked out:
 261
 262 ----------------
 263 $ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
 264 ----------------
 265
 266 On an inefficient filesystem with `core.ignorestat` set::
 267 +
 268 ------------
 269 $ git update-index --really-refresh              <1>
 270 $ git update-index --no-assume-unchanged foo.c   <2>
 271 $ git diff --name-only                           <3>
 272 $ edit foo.c
 273 $ git diff --name-only                           <4>
 274 M foo.c
 275 $ git update-index foo.c                         <5>
 276 $ git diff --name-only                           <6>
 277 $ edit foo.c
 278 $ git diff --name-only                           <7>
 279 $ git update-index --no-assume-unchanged foo.c   <8>
 280 $ git diff --name-only                           <9>
 281 M foo.c
 282 ------------
 283 +
 284 <1> forces lstat(2) to set "assume unchanged" bits for paths that match index.
 285 <2> mark the path to be edited.
 286 <3> this does lstat(2) and finds index matches the path.
 287 <4> this does lstat(2) and finds index does *not* match the path.
 288 <5> registering the new version to index sets "assume unchanged" bit.
 289 <6> and it is assumed unchanged.
 290 <7> even after you edit it.
 291 <8> you can tell about the change after the fact.
 292 <9> now it checks with lstat(2) and finds it has been changed.
 293
 294
 295 Configuration
 296 -------------
 297
 298 The command honors `core.filemode` configuration variable.  If
 299 your repository is on an filesystem whose executable bits are
 300 unreliable, this should be set to 'false' (see linkgit:git-config[1]).
 301 This causes the command to ignore differences in file modes recorded
 302 in the index and the file mode on the filesystem if they differ only on
 303 executable bit.   On such an unfortunate filesystem, you may
 304 need to use `git-update-index --chmod=`.
 305
 306 Quite similarly, if `core.symlinks` configuration variable is set
 307 to 'false' (see linkgit:git-config[1]), symbolic links are checked out
 308 as plain files, and this command does not modify a recorded file mode
 309 from symbolic link to regular file.
 310
 311 The command looks at `core.ignorestat` configuration variable.  See
 312 'Using "assume unchanged" bit' section above.
 313
 314
 315 See Also
 316 --------
 317 linkgit:git-config[1],
 318 linkgit:git-add[1]
 319
 320
 321 Author
 322 ------
 323 Written by Linus Torvalds <torvalds@osdl.org>
 324
 325 Documentation
 326 --------------
 327 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 328
 329 GIT
 330 ---
 331 Part of the linkgit:git[7] suite