Re: [PATCH] submodule: spell out API of submodule_move_head

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

Jonathan Nieder <jrnieder@gmail.com> writes:

>> This is not a new issue (the removed comment did not mention this at
>> all), but is it correct to say that updates to "index and work tree"
>> was as if we did "git -C $path checkout new" (and of course, HEAD in
>> the $path submodule must be at 'old')?
>
> I don't understand the question.  This comment doesn't say it's like
> "git checkout" --- are you saying it should?

No, I am pointing out that this comment does not say what it's like
clearly enough.  s/is it correct/am I correct/ would have been less
prone to get misunderstood, I guess.

> The function is more like "git read-tree -m -u" (or --reset when
> SUBMODULE_MOVE_HEAD_FORCE is passed) than like "git checkout".

If it behaves like two-tree "read-tree -m -u", I'd say that the best
explanation an average developer would understand is that the update
done to "index and work tree" is like using 'git checkout' to switch
to the branch whose tip is 'new'.

> Perhaps what you are hinting at is that read-tree --recurse-submodules
> is not necessarily the right primitive to implement "git checkout"
> with.  But that's a separate issue from documenting the current
> behavior of the function.

No, you are way too ahead in this discussion.  I was merely saying
that what the comment says was unclear and does not allow me to get
that far due to lack of clear information ;-).

>> What should happen if 'old' does not match reality (i.e. old is NULL
>> but HEAD does point at some commit, old and HEAD are different,
>> etc.)?  Should the call be aborted?
>
> No.

... and that is because?

When does it make sense to do a two-tree "read-tree -m -u" giving
the 'old' that is very different from the real 'old' tree-ish that
corresponds to where your index started at?