# git ls-files --with-tree documentation 2 messages from 2018-10-19 to 2018-10-22. Participants: Joey Hess, Junio C Hamano. Thread: https://gitlist.dev/t/49619 ## Joey Hess, 2018-10-19 18:33 Subject: git ls-files --with-tree documentation Message-ID: <20181019183335.GA12353@kitenet.net> URL: https://gitlist.dev/e/20181019183335.GA12353%40kitenet.net ``` --with-tree= When using --error-unmatch to expand the user supplied (i.e. path pattern) arguments to paths, pretend that paths which were removed in the index since the named 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= Treat all files in the as if they were present in the index. When using --error-unmatch to expand the user supplied (i.e. path pattern) arguments to paths, this has the effect that paths which were removed in the index since the named are still present. Using this option with -s or -u options does not make any sense. -- see shy jo ``` ## Junio C Hamano, 2018-10-22 03:22 Subject: Re: git ls-files --with-tree documentation Message-ID: URL: https://gitlist.dev/e/xmqq8t2qy8br.fsf%40gitster-ct.c.googlers.com In-Reply-To: <20181019183335.GA12353@kitenet.net> ``` Joey Hess writes: > How about changing the documentation to something like this to make > more explicit what it does. > > --with-tree= > Treat all files in the as if they were present in the index. > When using --error-unmatch to expand the user supplied (i.e. > path pattern) arguments to paths, this has the effect that paths which were > removed in the index since the named are still present. > Using this option with -s or -u options does not make any sense. If 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= 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 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 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 ), 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 entries appear at stage #1, other than the real reason: this is only to be able to enumerate all paths that are in 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 "). ```