[PATCH] Documentation/git-ls-tree.txt: Add a caveat about prefixing pathspec

From: Petr Baudis <pasky@suse.cz>
Date: Jul 21, 2008, 07:56 UTC
Message-ID: <20080721075618.14163.45309.stgit@localhost>
In-Reply-To: <20080720233956.GH10151@machine.or.cz>

When run in a working copy subdirectory, git-ls-tree will automagically add the prefix to the pathspec, which can result in an unexpected behavior when the tree object accessed is not the root tree object.

This was originally pointed out and described in a patch by Steve Frénaux <code@istique.net>, this is a shot at clearer and more accurate description.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/git-ls-tree.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 1cdec22..8bb1864 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -21,6 +21,15 @@ though - 'paths' denote just a list of patterns to match, e.g. so specifying
 directory name (without '-r') will behave differently, and order of the
 arguments does not matter.
 
+Note that within a subdirectory of the working copy, 'git ls-tree'
+will automatically prepend the subdirectory prefix to the specified
+paths and assume just the prefix was specified in case no paths were
+given --- no matter what the tree object is!
+Thus, within a subdirectory, 'git ls-tree' behaves as expected
+only when run on a root tree object (e.g. with a 'HEAD' tree-ish,
+but not anymore when passed 'HEAD:Documentation' instead).
+
+
 OPTIONS
 -------
 <tree-ish>::