git ls-files --with-tree documentation

       --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.

Joey Hess <id@joeyh.name> writes:

If <tree-ish> has a file F and the index has a file F/1, I do not think the command can pretend that F is present in the index (which requires it to also pretend that F/1 does not exist), so the above description is not quite right---the description needs to be tightened a bit, I am afraid [*1*].

But more importantly, given the fact that we needed piecemeal fix-ups like 4b4e26d2 ("Teach ls-files --with-tree=<tree> to work with options other than -c", 2008-11-16), and the fact that your description above still mentions "incompatible with -s", I strongly suspect that the implementation as-is would still *not* perform the way you describe above. In some modes, it won't pretend as if all of <tree-ish> are present in the index.

And I do not think I care that much to respond to a bug report that claims the above paragraph describes the way the command ought to work, either, but apparently you do care much more than I do, so perhaps you can respond to such bug reports whey they come and I do not have to worry about them too much ;-)

[Footnote]

*1* It actually pretends that entries in <tree-ish> are at stage #1,
    all the originally unmerged entries are at stage #3, and shows
    entries at stage #0 (i.e. merged entries in the original index)
    and stage #1 (i.e. from <tree-ish>), but only those that do not
    have corresponding stage #0 entries.  That is why "-s" won't
    make sense (i.e. from an entry being at stage #3, you cannot
    tell if it were originally at stage #1, #2 or #3), and "-u"
    won't make sense (i.e. ditto---and there is no good explanation
    as to why <tree-ish> entries appear at stage #1, other than the
    real reason: this is only to be able to enumerate all paths that
    are in <tree-ish> and the index, so that error-unmatch can say
    "Ah, that path is in the HEAD so it is not a typo" even for a
    path that has been removed from the index when running "git
    commit <paths>").