Why does g+ sometimes skip a leaf of the undo tree?

Question

I'm trying to understand how to move in the undo tree with the following default mappings:
u, <C-R>, g- and g+

Here's my understanding of things, which is probably wrong or incomplete. Each time we make a new edit, a new leaf is created in the undo tree. The more we make edits, the more leafs are added along a branch.

To move along the branch, we can use u to go back to the original version of the buffer, and <C-R> to go forward to the newest version.

This can be confirmed with the simple following test:

• create an empty buffer,
• insert the number 1,
• hit <C-A> to increment it to 2, again to 3 and again to 4

Using u and <C-R>, we can go back to each state of the buffer: empty, 1, 2, 3 and 4.

If at one point, we go backward and make a new edit from a past leaf, we create a new branch. The leafs which are not between the root of the tree (the original buffer) and the beginning of the new branch (the last edit we just made) can't be accessed with u and <C-R>.
Going back to the example, this can be confirmed:

• from the buffer's version 4, hit u to go back to 3
• hit r5 to replace 3 with 5
• hit u to undo the last edit

The last u doesn't bring us back to 4 but to 3.
We can't go back anymore to 4 with u and <C-R> because they only move along the shortest path between the root of the tree and the most recent version of the buffer which we've visited.
4 is not on the shortest path between the original empty buffer and 5, because 5 was created from 3.

To go back to any leaf of the undo tree, we can use g- and g+. Contrary to u and <C-R>, they move along a time axis on which every leaf is placed in the order it was created.

To confirm this:

• undo with u up to the original empty buffer
• hit g+ 5 times to reach 1, 2, 3, 4 and 5
• hit g- 5 times to get back to 4, 3, 2, 1 and the empty buffer

However, there's one case I don't understand. If from 5, we hit u to get back to 3, then g+, we get 5. But on the time axis, the nearest leaf from 3 is not 5, it's 4.

So why does Vim bring us to 5 instead of 4?

Answer 1

I find the default mappings/commands for navigating through the undo tree very complex and hard to memorize. If your intention is to use it on regular editing (instead of writing some custom command for a specific task), I'd recommend using a plugin, such as the undo tree plugin, which provides a great visual representation:

It makes it very easy to find a previous point on the undo tree; among several options, it allows for toggling the relative time to absolute time. There are several alternative plugins; for instance, on the link above there is a feature comparison of the undo tree plugin against the Gundo plugin.

Obviously the navigation through plugins will be slower than through the built-in plugins. But I believe that navigating the undo tree should be an exception, so for me it isn't worth spending time and effort learning/memorizing commands to gain a few seconds per week/month. If it does make sense for your workflow, then you can use the representation provided by plugins to aid your learning, to understand how the default commands moved you through the undo tree.