X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fgit-update-index.txt;h=0a1b0ad56de61bba8f5dd19df79e2e73c4f759b7;hb=20fc9bc5e4fdd4b1f7fd98fbd2e91879f945d7e1;hp=58b9e49af5f269f59b6e884430322cfca8673c75;hpb=14470c0de3d5a4388960f59ea96038206bacd888;p=git.git diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 58b9e49a..0a1b0ad5 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -8,11 +8,14 @@ git-update-index - Modifies the index or directory cache SYNOPSIS -------- +[verse] 'git-update-index' [--add] [--remove | --force-remove] [--replace] [--refresh [-q] [--unmerged] [--ignore-missing]] [--cacheinfo ]\* [--chmod=(+|-)x] + [--assume-unchanged | --no-assume-unchanged] + [--really-refresh] [--info-only] [--index-info] [-z] [--stdin] [--verbose] @@ -21,7 +24,7 @@ SYNOPSIS DESCRIPTION ----------- Modifies the index or directory cache. Each file mentioned is updated -into the cache and any 'unmerged' or 'needs updating' state is +into the index and any 'unmerged' or 'needs updating' state is cleared. The way "git-update-index" handles files it is told about can be modified @@ -30,26 +33,26 @@ using the various options: OPTIONS ------- --add:: - If a specified file isn't in the cache already then it's + 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 cache but is missing then it's + If a specified file is in the index but is missing then it's removed. Default behaviour is to ignore removed file. --refresh:: - Looks at the current cache and checks to see if merges or + 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 cache needs an update, the + 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. --unmerged:: - If --refresh finds unmerged changes in the cache, the default + If --refresh finds unmerged changes in the index, the default behavior is to error out. This option makes git-update-index continue anyway. @@ -57,18 +60,30 @@ OPTIONS Ignores missing files during a --refresh --cacheinfo :: - Directly insert the specified info into the cache. + Directly insert the specified info into the index. --index-info:: - Read index info from stdin. + Read index information from stdin. --chmod=(+|-)x:: Set the execute permissions on the updated files. +--assume-unchanged, --no-assume-unchanged:: + When these flags are specified, the object name recorded + for the paths are not updated. Instead, these options + sets and unsets the "assume unchanged" bit for the + paths. When the "assume unchanged" bit is on, git stops + checking the working tree files for possible + modifications, so you need to manually unset the bit to + tell git when you change the working tree file. This is + sometimes helpful when working with a big project on a + filesystem that has very slow lstat(2) system call + (e.g. cifs). + --info-only:: Do not create objects in the object database for all arguments that follow this flag; just insert - their object IDs into the cache. + their object IDs into the index. --force-remove:: Remove the file from the index even when the working directory @@ -106,14 +121,14 @@ OPTIONS Using --refresh --------------- -'--refresh' does not calculate a new sha1 file or bring the cache +'--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 cache, so that you -can refresh the cache for a file that hasn't been changed but where +"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 cache details with the proper files. +up the stat index details with the proper files. Using --cacheinfo or --info-only -------------------------------- @@ -123,7 +138,9 @@ merging. To pretend you have a file with mode and sha1 at path, say: - $ git-update-index --cacheinfo mode sha1 path +---------------- +$ git-update-index --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. @@ -134,11 +151,130 @@ 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 sha1 TAB path ++ +The first format is what "git-apply --index-info" +reports, and used to reconstruct a partial tree +that is used for phony merge base tree when falling +back on 3-way merge. + + . mode SP type SP sha1 TAB path ++ +The second format is to stuff git-ls-tree output +into the index file. + + . 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. + +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 SHA1 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`. + +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"). + + Examples -------- To update and refresh only the files already checked out: - git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh +---------------- +$ 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. +------------ Configuration @@ -146,12 +282,21 @@ Configuration The command honors `core.filemode` configuration variable. If your repository is on an filesystem whose executable bits are -unreliable, this should be set to 'false'. 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 +unreliable, this should be set to 'false' (see gitlink:git-repo-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=`. +The command looks at `core.ignorestat` configuration variable. See +'Using "assume unchanged" bit' section above. + + +See Also +-------- +gitlink:git-repo-config[1] + + Author ------ Written by Linus Torvalds