What exactly is a "initial checkout"

What exactly is a "initial checkout"

[Christian Halstrick]

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". I can imagine that the first checkout you do after
you have cloned a repo is a initial checkout but: What exactly defines
a "initial checkout"? It can't be an empty or non-existing index
because native git behaves like in a non-initial-checkout even if the
index is empty (see example below).

Here are some commands explaining my case. Git is facing an empty
index, HEAD and MERGE (the commit you checkout) have the some content
for path 'p'  and still git is neither updating index nor workingtree
file during checkout.

git init
mkdir p
echo initial >p/a
git add p/a
git commit -m initial
touch p2
git add p2
git commit -m followup
git rm -r p p2
echo "important data" >p
git checkout HEAD~ # successful checkout leaving p dirty
cat p # prints "important data", so 'p' is not updated during the checkout
git ls-files -sv  # empty -> index is empty

[1] https://www.eclipse.org/jgit/
[2] https://github.com/git/git/blob/master/Documentation/git-read-tree.txt#L187

Re: What exactly is a "initial checkout"

[Jeff King]

On Tue, Nov 06, 2018 at 01:38:45PM +0100, Christian Halstrick wrote:

> 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". I can imagine that the first checkout you do after
> you have cloned a repo is a initial checkout but: What exactly defines
> a "initial checkout"? It can't be an empty or non-existing index
> because native git behaves like in a non-initial-checkout even if the
> index is empty (see example below).
> 
> Here are some commands explaining my case. Git is facing an empty
> index, HEAD and MERGE (the commit you checkout) have the some content
> for path 'p'  and still git is neither updating index nor workingtree
> file during checkout.

Without looking at the code, I'd assume that an empty HEAD is different
than "there is no HEAD at all". I.e., what we call an "unborn branch"
elsewhere.

So perhaps try:

  git init
  git fetch ../some/other/repo HEAD:tmp
  git checkout tmp

where you'd truly have no HEAD.

Though peeking at the code, it looks like we set the unpack_trees
initial_checkout flag based on is_cache_unborn(), which looks for a
totally missing index file (not just an empty one). That would trigger
in the above case, too, though, because of course we have no index there
either.

-Peff

Re: What exactly is a "initial checkout"

[Junio C Hamano]

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

Re: What exactly is a "initial checkout"

[Christian Halstrick]

Ok, I know understand the problems which are solved by this
special behaviour of a "initial checkout". And also important I understand
when exactly I should do a "initial checkout" - when the index file does
not exist. I'll share my new knowledge with JGit :-)

Re: What exactly is a "initial checkout"

[Philip Oakley]

On 07/11/2018 08:50, Christian Halstrick wrote:
> Ok, I know understand the problems which are solved by this
> special behaviour of a "initial checkout". And also important I understand
> when exactly I should do a "initial checkout" - when the index file does
> not exist. I'll share my new knowledge with JGit :-)
> 
Given that the initial query was about the lack of documentation for the 
term "initial checkout", do you have any suggestion of how it might best 
be incorporated into the documentation to assist future reader?
-- 
Philip