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

[Junio C Hamano <gitster@pobox.com>]

Petr Baudis <pasky@suse.cz> writes:

> +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!

Don't be negative upfront.  Explain why this is a good thing first.

	... were given.  This is useful when you are deep in a
	subdirectory and want to inspect the list of files in an arbitrary
	commit.  E.g.

		$ cd some/deep/path
		$ git ls-tree --name-only -r HEAD~20

	will list the files in some/deep/path (i.e. where you are) 20
	commits ago, just like running "/bin/ls" there will give you the
	list of files you have right now.

> +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>::