Re: What exactly is a "initial checkout"

[Junio C Hamano <gitster@pobox.com>]

Christian Halstrick <christian.halstrick@gmail.com> writes:

> I am trying to teach JGit [1] to behave like native git regarding some
> corner cases during "git checkout". I am reading the "git read-tree"
> documentation and I am not sure about the case [2]. Git should behave
> differently during a normal checkout than when you are doing a
> "initial checkout".

When you are starting from commit H and checking out a different
commit M, and when a path in the index does not match what is
recorded in commit H, usually Git tries to keep the state of the
path you have in your index as a "local change", as long as the data
recorded for the path is the same between H and M.  A path in the
index that matches what is recorded in commit H and with different
data recorded for it in commit M gets M's version in the index and
the working file is updated to match (but it requires that either
the working tree file is missing, or the working tree version
matches what is in the original index, to avoid data loss).

But imagine you have just cloned and are trying to finish that
process.  What Git has done so far would include creating an empty
repository, populating the object database and pointing branches at
various commits.  HEAD now points at the branch (usually 'master'),
the index file does not exist (you haven't checked out anything),
and we want to populate the index and the working tree files to
match what is recorded in HEAD.  We do so by starting from commit
HEAD and checking out commit HEAD.

This situation presents conflicting goals to the above "keep the
local change" rule.  To the rule, this situation looks as if you
removed each and every path from the index (as the index hasn't been
populated yet---in fact, the index file does not even exist yet in
this state), but the data recorded for each path are the same
between commit H and commit M (as H==M==HEAD in this case), so "keep
the local change" rule would leave the index and the working tree
empty X-<.

That is rescued by the "initial checkout behaves differently and
forces the index and the working tree match what is recorded in
commit M" exception.  It probably should be obvious to the readers
by now that the absense of .git/index is used as the clue for this
exception to kick in from the above use case.

And that is exactly the condition that is checked by
read-cache.c::is_index_unborn().