git ls-files --with-tree documentation

[Joey Hess <id@joeyh.name>]

       --with-tree=<tree-ish>
           When using --error-unmatch to expand the user supplied <file> (i.e.
           path pattern) arguments to paths, pretend that paths which were
           removed in the index since the named <tree-ish> are still present.
           Using this option with -s or -u options does not make any sense.

This seems to say that it only affects it when --error-unmatch is used,
but in fact it goes deeper; for example I can use it to list files that
are present in either the current work tree or some other branch:

joey@darkstar:/tmp/v> git checkout foo
joey@darkstar:/tmp/v> git ls-files --with-tree=master
in-foo
in-master
joey@darkstar:/tmp/v> git ls-files
in-foo
joey@darkstar:/tmp/v> git ls-tree master 
100644 blob 0242cc10fdf4e9afdfd0928c2a209d4545780168	in-master

This is very useful behavior, but I'm not sure if I should rely on it
behaving this way in the future, given the documentation.

t/t3060-ls-files-with-tree.sh does indeed test that it
"should add entries from named tree", and it does it without using
--error-unmatch.

How about changing the documentation to something like this to make
more explicit what it does.

       --with-tree=<tree-ish>
           Treat all files in the <tree-ish> as if they were present in the index.
           When using --error-unmatch to expand the user supplied <file> (i.e.
           path pattern) arguments to paths, this has the effect that paths which were
           removed in the index since the named <tree-ish> are still present.
           Using this option with -s or -u options does not make any sense.

-- 
see shy jo