What does "commit owning the current file mean"?

[benknoble]

Background

:help fugitive-object says:

! The commit owning the current file

AFAICT:

• in a commit buffer: ! = the commit
• in a commit:file: ! = the commit
• in a worktree buffer: ! = HEAD

Questions

• Is my understanding right?
• Are there more things I can do with ! or other ways I can understand it?
• Which (if any) of these uses should be documented?

Context

The shorthand for diffing a file against the parent w/ Fugitive is :Gdiff !^, not :Gdiff ^ (which I found out when :Gdiffsplit! didn't do what I expected since it's supposed to diff against direct ancestors). Needing ! is mentioned here, but that’s really about ~. Using HEAD^ works just fine, as does @^. I was surprised ^ alone doesn’t, and then spent way too much time trying to understand what ! does in the code. I did find fd83fca (Support expansion flags, 2018-08-28), but that didn’t help much.

[tpope]

• Is my understanding right?

Yes. You're not the first to get confused, so I'll try swapping in some different wording there.

• Are there more things I can do with ! or other ways I can understand it?

Many things you can do but they're all pretty mundane. For example, you can use :Gedit ! to navigate to the commit for the historical buffer you're looking at, or :Glog ! -- % to see a log for that file starting at the revision you're looking at.

• Which (if any) of these uses should be documented?

I haven't been sure how to talk about it in the documentation because I don't want to give the impression it's super important.

The shorthand for diffing a file against the parent w/ Fugitive is :Gdiff !^, not :Gdiff ^

Early versions of Fugitive did what you expected, but it was just too overloaded, especially for @ (which can mean different things in different positions) and ~ (which by itself usually means "home directory" in Vim).

Where did you get the impression :Gdiff ^ would do that? git diff ^ doesn't do that. Old docs somewhere?

(which I found out when :Gdiffsplit! didn't do what I expected since it's supposed to diff against direct ancestors).

Is your confusion that you called :Gdiffsplit! in a work tree file and expected it to diff against @^ but instead it diffed against @? The docs are a little misleading about that.

[benknoble]

• Is my understanding right?

Yes. You're not the first to get confused, so I'll try swapping in some different wording there.

Ah, ok! I wondered if maybe there was a hidden corner of Git I didn't know about ;)

• Are there more things I can do with ! or other ways I can understand it?

Many things you can do but they're all pretty mundane. For example, you can use :Gedit ! to navigate to the commit for the historical buffer you're looking at, or :Glog ! -- % to see a log for that file starting at the revision you're looking at.

Right—I suppose I meant "any other odd notations involving ! I should know about, though if I read the code well, some of them are internal incantations that you probably don't want to document. Neat.

[snip docs, makes sense]

The shorthand for diffing a file against the parent w/ Fugitive is :Gdiff !^, not :Gdiff ^

Early versions of Fugitive did what you expected, but it was just too overloaded, especially for @ (which can mean different things in different positions) and ~ (which by itself usually means "home directory" in Vim).

Where did you get the impression :Gdiff ^ would do that? git diff ^ doesn't do that. Old docs somewhere?

Maybe an ancient habit or a misunderstanding. It's true that I can't track down now what lead me to believe that would work, so that's my mistake! My apologies for the confusion.

I'll remind myself to use !^ or @~ (the latter of which I type normally for the shell anyway).

(which I found out when :Gdiffsplit! didn't do what I expected since it's supposed to diff against direct ancestors).

Is your confusion that you called :Gdiffsplit! in a work tree file and expected it to diff against @^ but instead it diffed against @? The docs are a little misleading about that.

You've precisely understood my confusion; sorry for not laying that out more clearly. It would be convenient if there was a quick way to diff the worktree against it's ancestor, but (when a file has modifications) diffing against HEAD makes total sense. Now that I consider it, I'm not sure what notation could best distinguish those except Git's own.

Still, it's hard for me to conceptualize HEAD as the direct ancestor of the worktree 🤔 I'll look forward to any coming clarifications, thanks!