Re: "stage files" vs "cached files"

[Linus Torvalds <torvalds@osdl.org>]

On Thu, 19 Oct 2006, Jerome Lovy wrote:
> 
> after having read tutorial1+2, I thought the following were more or less
> synonyms: index ~ directory cache ~ staging area
> 
> But then I discover that --cache and --staged are two different things,
> notably when using ls-files.
> 
> The documentation states indeed:
>  "--cached   Show cached files in the output"
>  "--stage    Show stage files in the output"

That is indeed confusing.

It shouldn't be "stage files". It should be "file stages".

The "stage" of a file is something that is meaningful on merges. Normally 
all files are in "stage 0", which means that it's fully merged. So when 
you do

	git ls-files --stage

you'll see a listing of all the files, with their file modes, SHA1's, 
"stage" and filename. And you'll basically always see "0" in the stage 
column.

But if you have had a merge that didn't resolve automatically, you can see 
the same filename listed up to three times, with stages 1, 2 and 3 (a zero 
will never be combined with any other stage - you'll only see a zero 
alone).

That just shows how that particular file came to be: a "stage 1" entry is 
the base branch version (the "common ancestor"), while stages 2 and 3 are 
the first and second branch respectively.

> I'm a bit confused. Is maybe a "stage file" entry missing in the glossary?

That term doesn't exist, so it shouldn't be in the glossary (or in any 
man-pages). But the "merge stage" _of_ a file is a real concept.

			Linus