Junio C Hamano wrote: > Jonathan Nieder <jrnieder@xxxxxxxxx> 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
