telescope-undo.nvim

Visualize your undo tree and fuzzy-search changes in it. For those days where committing early and often doesn't work out.

Usage

After invoking telescope-undo you can browse the current buffer's undo tree in a text-based tree representation by using telescope's move_selection_next/previous actions. These are mapped to arrow keys or <C-n>,<C-p> by default. Inserted text is fuzzy matched against the additions and deletions in each undo state in your undo tree and the finder will limit the results accordingly. While this obviously breaks the tree visuals, you can freely search in your undo states. The previewer will always show the diff of the current selection with some context according to the config or your scrolloff value.

If you have found the undo state you were looking for, you can use <C-cr> or <C-r> to revert to that state. If you'd rather not change your whole buffer, you can use <cr> to yank the additions of this undo state into your default register (use <S-cr> or <C-y> to yank the deletions).

Installation

Install with your favorite Neovim package manager.

As part of your Telescope plugin spec for lazy.nvim:

{
  "nvim-telescope/telescope.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "debugloop/telescope-undo.nvim",
  },
  config = function()
    require("telescope").setup({
      -- the rest of your telescope config goes here
      extensions = {
        undo = {
          -- telescope-undo.nvim config, see below
        },
        -- other extensions:
        -- file_browser = { ... }
      },
    })
    require("telescope").load_extension("undo")
    -- optional: vim.keymap.set("n", "<leader>u", "<cmd>Telescope undo<cr>")
  end,
},

If you prefer standalone Lazy plugin specs (my personal recommendation), here's how you do that with some more options as an example:

{
  "debugloop/telescope-undo.nvim",
  dependencies = { -- note how they're inverted to above example
    {
      "nvim-telescope/telescope.nvim",
      dependencies = { "nvim-lua/plenary.nvim" },
    },
  },
  keys = {
    { -- lazy style key map
      "<leader>u",
      "<cmd>Telescope undo<cr>",
      desc = "undo history",
    },
  },
  opts = {
    -- don't use `defaults = { }` here, do this in the main telescope spec
    extensions = {
      undo = {
        -- telescope-undo.nvim config, see below
      },
      -- no other extensions here, they can have their own spec too
    },
  },
  config = function(_, opts)
    -- Calling telescope's setup from multiple specs does not hurt, it will happily merge the
    -- configs for us. We won't use data, as everything is in it's own namespace (telescope
    -- defaults, as well as each extension).
    require("telescope").setup(opts)
    require("telescope").load_extension("undo")
  end,
},

Invoke using:

" Directly by calling it through Telescope's extension interface:

" using lua
:lua require("telescope").extensions.undo.undo()

" using custom options for just this call
:lua require("telescope").extensions.undo.undo({ side_by_side = true })

" using legacy Vim script
:Telescope undo

" Using the optional mapping:

" using lua
:lua vim.keymap.set("n", "<leader>u", "<cmd>Telescope undo<cr>")
" using legacy Vim script
:nmap <leader>u <cmd>Telescope undo<cr>

Configuration

The available configuration values are:

• use_delta, which controls whether delta is used for fancy diffs in the preview section. If set to false, telescope-undo will not use delta even when available and fall back to a plain diff with treesitter highlights.
• use_custom_command, which can be used to use an unsupported diff tool other than delta
• side_by_side, which tells delta to render diffs side-by-side. Thus, requires delta to be used. Be aware that delta always uses its own configuration, so it might be that you're getting the side-by-side view even if this is set to false.
• vim_diff_opts, defaults to all of :help vim.diff default options, but sets ctxlen to your scrolloff value.
• entry_format, defaults to "state #$ID, $STAT, $TIME"", which contains the three supported variables.
• time_format, defaults to "" for a timeago-style representation. Can be set to a Lua date format string.
• saved_only, defaults to false, but can be used to limit shown undo states to those that have been saved to disk.

Further, the undo telescope should accept any of the usual telescope attributes as well as the special theme key which auto-extends the telescope theme on top of any of your explicitly provided config. Of course, you might also want to remap some of the default keys.

This is what the defaults look like with some additional explanations:

opts = {
  extensions = {
    undo = {
      use_delta = true,
      use_custom_command = nil, -- setting this implies `use_delta = false`. Accepted format is: { "bash", "-c", "echo '$DIFF' | delta" }
      side_by_side = false,
      vim_diff_opts = {
        ctxlen = vim.o.scrolloff,
      },
      entry_format = "state #$ID, $STAT, $TIME",
      time_format = "",
      saved_only = false,
    },
  },
},

The full list will always be available in the code providing the defaults here.

My personal recommendation is the following, which maximizes the width of the preview to enable side-by-side diffs:

opts = {
  extensions = {
    undo = {
      side_by_side = true,
      layout_strategy = "vertical",
      layout_config = {
        preview_height = 0.8,
      },
    },
  },
}

Mappings

By default, the following mappings are enabled.

require("telescope").setup({
  extensions = {
    undo = {
      mappings = {
        i = {
          ["<cr>"] = require("telescope-undo.actions").yank_additions,
          ["<S-cr>"] = require("telescope-undo.actions").yank_deletions,
          ["<C-cr>"] = require("telescope-undo.actions").restore,
          -- alternative defaults, for users whose terminals do questionable things with modified <cr>
          ["<C-y>"] = require("telescope-undo.actions").yank_deletions,
          ["<C-r>"] = require("telescope-undo.actions").restore,
        },
        n = {
          ["y"] = require("telescope-undo.actions").yank_additions,
          ["Y"] = require("telescope-undo.actions").yank_deletions,
          ["u"] = require("telescope-undo.actions").restore,
        },
      },
    },
  },
})

Important

Note how above example uses the call to telescope's setup(). This is due to the fact that directly requiring these actions needs telescope-undo to be available already, which it is not inside lazy's opts key when using above "standalone" spec. See the next example for how to do it inside opts.

There is one more mapping available, yank_larger. This yanks either the additions or the deletions based on their line count, with the additions winning in case of a tie. This is how you configure this mapping, or remap any of the default actions for that matter:

opts = {
  extensions = {
    undo = {
      mappings = {
        -- Wrapping the actions inside a function prevents the error due to telescope-undo being not
        -- yet loaded.
        i = {
          ["<cr>"] = function(bufnr)
            return require("telescope-undo.actions").yank_larger(bufnr)
          end,
        },
        n = {
          ["y"] = function(bufnr)
            return require("telescope-undo.actions").yank_larger(bufnr)
          end,
        },
      },
    },
  },
}

If you wish to disable one of the default mappings, just set it to false.

opts = {
  extensions = {
    undo = {
      mappings = {
        i = {
          ["<C-y>"] = false,
        },
      },
    },
  },
}

Contributions

Suggestions, issues and patches are very much welcome. There are some TODOs sprinkeled into the code that need addressing, but could also use some input and opinions.