X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fgit-update-index.txt;h=c74311dabd28f144c06f5f55182269d25691a270;hb=39c015c556f285106931e0500f301de462b0e46e;hp=52874c85623cd50f94219243cce4fbf61a4f2331;hpb=f7a2eb735982e921ae4379f1dcf5f7a023610393;p=git.git

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 52874c85..c74311da 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -60,7 +60,7 @@ OPTIONS
 	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.        
@@ -123,7 +123,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 +136,70 @@ 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
@@ -146,12 +207,18 @@ 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=`.
 
+
+See Also
+--------
+gitlink:git-repo-config[1]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>