git-ls-files handling of 'missing' files

git-ls-files handling of 'missing' files

[Jon Nelson]

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>

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

[Junio C Hamano]

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.

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