Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/debugloop/telescope-undo.nvim
A telescope extension to view and search your undo tree 🌴
https://github.com/debugloop/telescope-undo.nvim
neovim neovim-plugin neovim-plugins nvim nvim-plugin nvim-plugins nvim-telescope telescope-extension
Last synced: 14 days ago
JSON representation
A telescope extension to view and search your undo tree 🌴
- Host: GitHub
- URL: https://github.com/debugloop/telescope-undo.nvim
- Owner: debugloop
- License: mit
- Created: 2022-12-16T16:01:05.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-18T04:11:18.000Z (4 months ago)
- Last Synced: 2024-07-31T20:51:42.563Z (3 months ago)
- Topics: neovim, neovim-plugin, neovim-plugins, nvim, nvim-plugin, nvim-plugins, nvim-telescope, telescope-extension
- Language: Lua
- Homepage:
- Size: 60.5 KB
- Stars: 578
- Watchers: 8
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - debugloop/telescope-undo.nvim - A telescope extension to visualize your undo tree and fuzzy-search changes in it. (Editing Support / Scrollbar)
- my-neovim-pluginlist - debugloop/telescope-undo.nvim - undo.nvim)   (Other Standard Feature Enhancement / Undo)
README
# 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 `,` 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 `` or `` to revert to
that state. If you'd rather not change your whole buffer, you can use `` to yank the additions
of this undo state into your default register (use `` or `` to yank the deletions).
## Installation
Install with your favorite Neovim package manager.
As part of your Telescope plugin spec for [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
"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", "u", "Telescope undo")
end,
},
```
If you prefer standalone Lazy plugin specs (my personal recommendation), here's how you do that with
some more options as an example:
```lua
{
"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
"u",
"Telescope undo",
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:
```viml
" 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", "u", "Telescope undo")
" using legacy Vim script
:nmap u Telescope undo
```
## Configuration
The available configuration values are:
* `use_delta`, which controls whether [delta](https://github.com/dandavison/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](https://www.lua.org/pil/22.1.html).
* `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:
```lua
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](https://github.com/debugloop/telescope-undo.nvim/blob/main/lua/telescope/_extensions/undo.lua#L6).
My personal recommendation is the following, which maximizes the width of the preview to enable
side-by-side diffs:
```lua
opts = {
extensions = {
undo = {
side_by_side = true,
layout_strategy = "vertical",
layout_config = {
preview_height = 0.8,
},
},
},
}
```
## Mappings
By default, the following mappings are enabled.
```lua
require("telescope").setup({
extensions = {
undo = {
mappings = {
i = {
[""] = require("telescope-undo.actions").yank_additions,
[""] = require("telescope-undo.actions").yank_deletions,
[""] = require("telescope-undo.actions").restore,
-- alternative defaults, for users whose terminals do questionable things with modified
[""] = require("telescope-undo.actions").yank_deletions,
[""] = 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:
```lua
opts = {
extensions = {
undo = {
mappings = {
-- Wrapping the actions inside a function prevents the error due to telescope-undo being not
-- yet loaded.
i = {
[""] = 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`.
```lua
opts = {
extensions = {
undo = {
mappings = {
i = {
[""] = 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.