Confusion on the wording of Gdiffsplit with no argument

[RayZ0rr]

From the docs

With no argument, the version in the index or work
tree is used, and the work tree version is always
placed to the right or bottom, depending on available
width.  Use Vim's |do| and |dp| to stage and unstage
changes.

Shouldn't it be "With no argument, the version in the index and worktree is used"?

So my understanding is that we also use index version (which could be staging area or HEAD) on the left and working tree version on the right

[tpope]

From the docs

With no argument, the version in the index or work
tree is used, and the work tree version is always
placed to the right or bottom, depending on available
width.  Use Vim's |do| and |dp| to stage and unstage
changes.

Shouldn't it be "With no argument, the version in the index and worktree is used"?

No. The current buffer is left unchanged, and only one new version is "used" (opened in a split).

index version (which could be staging area or HEAD)

"Index" and "staging area" are synonyms. HEAD is a commit. If you start at a file in HEAD, and call :Gdiffsplit, you'll get the work tree version in a split, and the version in the index won't be open at all.

[RayZ0rr]

No. The current buffer is left unchanged, and only one new version is "used" (opened in a split).

I see how I misinterpreted that.

"Index" and "staging area" are synonyms

Yes. But I'll explain why I use them slightly differently below

the version in the index won't be open at all.

This statement confuses me. Here's the observed behavior:

1. If you :Gdiffsplit a file in HEAD without any edits you'll get your buffer on right and index version (which would be the version on HEAD) on left. There won't be any diff
2. If you edit the file either in the split buffer or separately + using :Gdiffsplit later, then you'll get your buffer on right and index version (which is still HEAD version) on the left. You can see the diff of the difference now
3. If you now add the edited file using git add <filename> and do :Gdiffsplit, similar to step 1 there won't be any diff but instead of HEAD version in the index for the left buffer, it would be the staging area version because the index version will be what's going to be committed.

Overall, the behavior is always index on left and worktree on right

[tpope]

I use "index" the same way Git does: the contents of .git/index. I don't really think there's any room for interpretation here.

[RayZ0rr]

I use "index" the same way Git does: the contents of .git/index. I don't really think there's any room for interpretation here.

I also use it in the same way. I just specified "HEAD" and "staging" to specify which version of the file is in the index.

But the problem in the docs is still there:
the version in the index or work tree is used

^ is confusing because we always diff against index in the no argument case. Let's look at its behavior for a tracked file which is modified after the last commit:

1. Before git add: Index has the version of the file from last commit (which would be the HEAD).
2. After git add: Index has the same version as your working tree (until you modify the file again).

So, its always the index.

If you start at a file in HEAD, and call :Gdiffsplit, you'll get the work tree version in a split, and the version in the index won't be open at all.

The index version will open on left. You can verify by either using <C-g>1 or editing the buffer on right to see diff being created

[tpope]

^ is confusing because we always diff against index in the no argument case.

Try this:

1. :Gedit @~50:% to open the file as it was 50 commits ago.
2. :Gdiffsplit.

You're now diffing the file 50 commits ago against the work tree version. The index version is nowhere to be found.

[RayZ0rr]

^ is confusing because we always diff against index in the no argument case.

Try this:

1. `:Gedit @~50:%` to open the file as it was 50 commits ago.

2. `:Gdiffsplit`.

You're now diffing the file 50 commits ago against the work tree version. The index version is nowhere to be found.

Okay with this it is more clear and the wording in the docs is correct.

I was also confused by your earlier statement (quote below) because I didn't observe that behavior.

If you start at a file in HEAD, and call :Gdiffsplit, you'll get the work tree version in a split, and the version in the index won't be open at all.