git-ls-files handling of 'missing' files

Jon Nelson· Feb 14, 2006, 03:46 UTC · lore

git-ls-files appears to treat missing files as both removed /and/ modified, neither of which really seems right. Perhaps a new state, 'missing', is worthwhile?

Also, the documentation for git-ls-files is a bit confusing to me:

(aside: I assume that the '?' is a mis-typed '/')

The documentation confuses me when it says that files marked with a 'K' are "to be killed / other" - it don't understand why 'killed' and 'other' are lumped together.

The docs for git-ls-files indicate that a file marked as 'killed' (wrong tense?) is a file that needs to be removed for git-checkout-index to succeed. The manpage doesn't say why git-checkout-index needs to succeed or under what conditions git-checkout-index would be invoked. (ie, "why" should I manually remove this file).

Would it also be worthwhile to change the terminology used? Specifically, it seems that 'unchanged' is more readily understandable than 'cached', and the past tense of 'killed' throws me. I can offer no improvement there, however.

It seems to me that files can also exist in the state 'new' or 'added' (is this the same as unmerged?) Is there a state for 'conflict'?

Sorry for all of the questions, I've really been enjoying using git but every now and again something thows me - tonight it was git-ls-files. ;-)

-- Jon Nelson <jnelson-git@jamponi.net>

Junio C Hamano· Feb 14, 2006, 03:56 UTC · re: Jon Nelson · lore

Re: git-ls-files handling of 'missing' files

Jon Nelson <jnelson-git@jamponi.net> writes:

> The documentation confuses me when it says that files marked with a 'K' 
> are "to be killed / other" - it don't understand why 'killed' and 
> 'other' are lumped together.

I think there is a typo in asciidoc source (probably ?:: is needed). Whenever you see funky things in the documentation please first check the Documentation/that-file.txt to see if you are just seeing a bad rendition of what was meant.

Show 5 quoted lines

> The docs for git-ls-files indicate that a file marked as 'killed' (wrong 
> tense?) is a file that needs to be removed for git-checkout-index to 
> succeed. The manpage doesn't say why git-checkout-index needs to succeed 
> or under what conditions git-checkout-index would be invoked. (ie, "why" 
> should I manually remove this file).

This was from long time ago so I may be misremembering things but it is for D/F conflicts. index has "doc/file1" stored but your working tree has a regular file doc. To check "doc/file1" out you would need to remove that file. Or index has a regular file "path2" stored when you have "path2/file2" on the working tree (hence path2 is a directory), in which case "path2/file2" needs to disappear.

> It seems to me that files can also exist in the state 'new' or 'added' 
> (is this the same as unmerged?) Is there a state for 'conflict'?

Remember, ls-files is about index vs working tree files. It works before your initial commit, and never looks at the HEAD commit. 'new' or 'added' has no meaning. working tree file is either known to be the same (thanks to stat information that is cached in the index), known to be different (ditto), or unknown (when stat information is stale), relative to index.

Unmerged and conflict should be the same, I think.