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