🔖 Recall

Recall refines the use of Neovim marks by focusing on global marks, streamlining their usage and enhancing their visibility and navigability.

• Emphasizes global marks for cross-file functionality.
• Utilizes a consistent visual indicator in the sign column: a single sign character for all marks.
• Facilitates global mark navigation with :RecallNext and :RecallPrevious, circumventing the need for direct letter references.
• Simplifies mark setting and removal with :RecallToggle, abstracting away the burden of choosing and remembering specific letters.

Recall attempts to eliminate the cognitive overhead associated with mark management, enabling you to focus on your workflow, not on mark administration. Its enhancements are strictly additive to Neovim's existing mark features, which you can continue to use to their fullest potential.

Recall showing two global marks and available commands.

Telescope integration using :Telescope recall theme=ivy.

• Installation
  • Telescope integration
  • Project-specific global marks
  • The wshada option
  • Usage commands
    • Navigation logic
• Inspirations
• Contributions
• Licensing

Installation

Recall requires no configuration:

require("recall").setup({})

But you can customize it. Here are the default options:

require("recall").setup({
  sign = "",
  sign_highlight = "@comment.note",

  telescope = {
    autoload = true,
    mappings = {
      unmark_selected_entry = {
        normal = "dd",
        insert = "<M-d>",
      },
    },
  },

  wshada = vim.fn.has("nvim-0.10") == 0,
})

Recall ships with no mappings by default. Add your own, using the Lua API or the user commands that ship with it.

Example mappings

-- Using commands:
vim.keymap.set("n", "<leader>mm", ":RecallToggle<CR>", { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mn", ":RecallNext<CR>", { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mp", ":RecallPrevious<CR>", { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mc", ":RecallClear<CR>", { noremap = true, silent = true })
vim.keymap.set("n", "<leader>ml", ":Telescope recall<CR>", { noremap = true, silent = true })

-- Using the Lua API:
local recall = require("recall")

vim.keymap.set("n", "<leader>mm", recall.toggle, { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mn", recall.goto_next, { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mp", recall.goto_prev, { noremap = true, silent = true })
vim.keymap.set("n", "<leader>mc", recall.clear, { noremap = true, silent = true })
vim.keymap.set("n", "<leader>ml", ":Telescope recall<CR>", { noremap = true, silent = true })

Example lazy.nvim plugin spec

{
  "fnune/recall.nvim",
  version = "*",
  config = function()
    local recall = require("recall")

    recall.setup({})

    vim.keymap.set("n", "<leader>mm", recall.toggle, { noremap = true, silent = true })
    vim.keymap.set("n", "<leader>mn", recall.goto_next, { noremap = true, silent = true })
    vim.keymap.set("n", "<leader>mp", recall.goto_prev, { noremap = true, silent = true })
    vim.keymap.set("n", "<leader>mc", recall.clear, { noremap = true, silent = true })
    vim.keymap.set("n", "<leader>ml", ":Telescope recall<CR>", { noremap = true, silent = true })
  end
}

Telescope integration

If you have Telescope installed, Recall will loads its extension so that you can use :Telescope recall. Within the Recall Telescope picker, you can use dd in normal mode or <M-d> in insert mode to delete the selected global mark.

To open the Recall Telescope picker, use :Telecope recall. You can pass a theme option with a Telescope built-in theme such as :Telescope recall theme=ivy.

To change or unset the default mappings, use an empty string:

require("recall").setup({
  telescope = {
    mappings = {
      unmark_selected_entry = {
        normal = "d",
        insert = "",
      },
    },
  },
})

If you prefer loading the Recall Telescope extension manually, do this:

require("recall").setup({
  telescope = {
    autoload = false,
  },
})

require("telescope").load_extension("recall")

Project-specific global marks

Neovim stores global mark information in the shada file. The option shadafile allows you to the path where the shada file will be created. This can be combined with the option exrc in order to load a project-specific Lua configuration file for Neovim. Here is an example:

-- In your Neovim configuration:
vim.opt.exrc = true
vim.opt.secure = true

-- /path/to/your/project/.nvim.lua:
vim.opt.shadafile = ".vim/project.shada"

-- Optionally, in the project's .gitignore or ~/.config/git/ignore:
.vim

Read more about exrc: :h exrc.

The wshada option

It is only necessary to set wshada to true on Neovim versions older than 0.10. Recall's default configuration does this for you. When enabled, this option will call :wshada! after every change to global marks in order to guarantee their persistence in the shada file.

⚠️ Writing to the shada file with :wshada! may overwrite data such as location list entries from Neovim instances other than your current one. See :h wshada for more details.

To learn more about this, see the related issue and pull request including a fix that ships with Neovim 0.10.

Usage commands

• :RecallMark - Mark the current line.
• :RecallUnmark - Unmark the current line.
• :RecallToggle - Mark or unmark the current line.
• :RecallNext/:RecallPrevious - Navigate through marks linearly, respecting the sequence A-Z and wrapping accordingly.
• :RecallClear - Clear all global marks.

Navigation logic

• Recall identifies the 'latest' mark by picking the current cursor position if it's a global mark, or using the jump list to find the latest-jumped-to mark.
• To navigate, Recall advances sequentially through the letters with inherent looping from Z to A and vice versa.

Inspirations

I've used most of these plug-ins at some point, and they have helped me materialize the ideas for Recall.

• otavioschwanck/arrow.nvim
• ThePrimeagen/harpoon
• chentoast/marks.nvim
• jeetsukumaran/vim-markology
• kshenoy/vim-signature

Contributions

You're welcome to contribute pull requests and well-crafted issues to Recall!

Recall ships with a flake.nix and .envrc to set up a development shell with development dependencies. You need Nix in order to use it. If you're not using Nix, then simply read the dependencies listed in flake.nix and install them on your system, or use .github/workflows/test.yml as a guide.

To format the code in this repository, run ./format.sh.

Licensing

The MIT license.