merge-recursive: Make use of provided bases
[gitweb.git] / Documentation / git-update-index.txt
index 8d55659edefe07fed2fd8dbd0e7bf716c460e998..c74311dabd28f144c06f5f55182269d25691a270 100644 (file)
@@ -1,6 +1,5 @@
 git-update-index(1)
 ===================
-v0.1, May 2005
 
 NAME
 ----
@@ -10,17 +9,19 @@ git-update-index - Modifies the index or directory cache
 SYNOPSIS
 --------
 'git-update-index'
-            [--add] [--remove] [--refresh] [--replace]
-            [--ignore-missing]
-            [--force-remove]
+            [--add] [--remove | --force-remove] [--replace] 
+            [--refresh [-q] [--unmerged] [--ignore-missing]]
             [--cacheinfo <mode> <object> <file>]\*
-            [--info-only]
+            [--chmod=(+|-)x]
+            [--info-only] [--index-info]
+            [-z] [--stdin]
+            [--verbose]
             [--] [<file>]\*
 
 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
@@ -29,29 +30,45 @@ 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 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 index, the default
+        behavior is to error out.  This option makes git-update-index 
+        continue anyway.
+
 --ignore-missing::
        Ignores missing files during a --refresh
 
 --cacheinfo <mode> <object> <path>::
-       Directly insert the specified info into the cache.
+       Directly insert the specified info into the index.
        
+--index-info::
+        Read index information from stdin.
+
+--chmod=(+|-)x::
+        Set the execute permissions on the updated files.        
+
 --info-only::
        Do not create objects in the object database for all
        <file> 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
@@ -65,26 +82,38 @@ OPTIONS
        that conflicts with the entry being added are
        automatically removed with warning messages.
 
+--stdin::
+       Instead of taking list of paths from the command line,
+       read list of paths from the standard input.  Paths are
+       separated by LF (i.e. one path per line) by default.
+
+--verbose::
+        Report what is being added and removed from index.
+
+-z::
+       Only meaningful with `--stdin`; paths are separated with
+       NUL character instead of LF.
+
 --::
        Do not interpret any more arguments as options.
 
 <file>::
        Files to act on.
-       Note that files begining with '.' are discarded. This includes
+       Note that files beginning with '.' are discarded. This includes
        `./file` and `dir/./file`. If you don't want this, then use     
        cleaner names.
        The same applies to directories ending '/' and paths with '//'
 
 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
 --------------------------------
@@ -92,9 +121,11 @@ Using --cacheinfo or --info-only
 current working directory.  This is useful for minimum-checkout
 merging.
 
-  To pretend you have a file with mode and sha1 at path, say:
+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.
@@ -105,11 +136,87 @@ 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
+------------
+
+
 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
+----------------
+
+
+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' (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=`.
+
+
+See Also
+--------
+gitlink:git-repo-config[1]
 
 
 Author