[PATCH] Documentation/git-update-index: caution about tree objects

From: Greg Troxel <gdt@ir.bbn.com>
Date: Dec 21, 2012, 01:35 UTC
Message-ID: <1356053738-14926-1-git-send-email-gdt@ir.bbn.com>

While one can add tree objects to the index, this is not currently useful. Therefore, use "git ls-tree -r" as the example to be fed to --index-info. Add a section explaining about expected index contents. (Thanks to Junio for explaining this to me in August of 2011.)

Signed-off-by: Greg Troxel <gdt@ir.bbn.com>
---
 Documentation/git-update-index.txt | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 9d0b151..6ce65fa 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -29,6 +29,11 @@ Modifies the index or directory cache. Each file mentioned is updated
 into the index and any 'unmerged' or 'needs updating' state is
 cleared.
 
+Note that update-index does not check that the modifications preserve
+the expected invariants.  In particular, an index normally holds
+regular blobs, executable blobs, symlink blobs, and gitlinks.
+Therefore, adding a tree object is not likely useful.
+
 See also linkgit:git-add[1] for a more user-friendly way to do some of
 the most common operations on the index.
 
@@ -210,7 +215,7 @@ back on 3-way merge.
 
     . mode SP type SP sha1          TAB path
 +
-The second format is to stuff 'git ls-tree' output
+The second format is to stuff 'git ls-tree -r' output
 into the index file.
 
     . mode         SP sha1 SP stage TAB path

-- 
1.8.0.1