Undo tree

Kakoune keeps track of every modification you make to a buffer.

It does this bookkeeping in a non linear way: it means that if you undo a few changes and then decide to make a new one, it will create a branch in the history tree.

Let's see how it works through a concrete example.

Example

Open a new buffer and insert the text hello. Next make your first change by adding world. Finally you decide this is better to change world to universe. Here's how your history looks:

   hello
     ↓
  modif 1
     ↓
 hello world
     ↓
  modif 2
     ↓
hello universe

By pressing the u key you undo your change and go back to hello world. Now press U to redo your change and get back to hello universe. For now the path is linear, so undo and redo let you move back or forward on this unique branch.

Press u to undo to get back to hello world again. You change your mind and decide to write hello galaxy. By doing so, you've juste created a branch in the history!

           hello
             ↓
           modif 1
             ↓
        hello world
     ↓               ↓ 
   modif 2         modif 3
     ↓               ↓
hello universe   hello galaxy

If you do a simple undo (u), you will get back to hello world and doing a redo (U) will teleport you to hello galaxy. Using only these 2 commands, you're trapped in the new history branch you created, and there seems to be no way to retrieve the hello universe state. Is it really lost forever?

Fear not, there's a way to teleport to it! As you see in the diagram above, each modification has a unique autoincrement id. This number is independent of your current branch. By pressing <c-k> from the hello world state, which has number 3, your go the the state number 2 hello universe. <c-j> goes the opposite direction by incrementing the history id.

So to recap the couple u and U lets you move backward and forward in the last branch while their alternative versions <c-k> <c-j> follow absolute history id which may be located somewhere else in the history tree.

UI and scripting

You can know your position in the tree by looking at the status bar after pressing <c-k> or <c-j>. The message moved to change #3 (11) indicates that you are currently on the history node 3 on a total of 11.

While scripting you have access to the $kak_history_id