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

[Jonathan Nieder <jrnieder@gmail.com>]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Junio C Hamano wrote:

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

No problem.  I think a word or two about how it's like read-tree
in the docstring could be an improvement.

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

If it says it's like "git checkout", then I fear that can just lead to
more confusion, since "git checkout" does a number of things (e.g.
updating the HEAD symref) that this function does not do.

It could say that it's like "git reset --keep", I suppose.

[...]
>>> 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?

Because that is not the purpose of the function.

The caller is responsible for setting 'old' appropriately.  A word or
two in that direction would not be a terrible thing.

All that said, I want this function to go away completely. :)
Documenting how it currently behaves is just a good way to understand
what is happening when doing so.

Thanks,
Jonathan