mini-visits.md

Track and reuse file system visits

See more details in Features and help file.

---

⦿ This is a part of mini.nvim library. Please use this link if you want to mention this module.

⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.

⦿ See the repository page to learn about common design principles and configuration recipes.

---

If you want to help this project grow but don't know where to start, check out contributing guides of 'mini.nvim' or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.

Demo

demo-visits.mp4

Note: This demo uses custom vim.ui.select() from mini.pick.

Features

• Persistently track file system visits (both files and directories) per project directory. Store visit index is human readable and editable.

• Visit index is normalized on every write to contain relevant information. Exact details can be customized. See *MiniVisits.normalize()*.

• Built-in ability to persistently use label paths for later use. See *MiniVisits.add_label()* and *MiniVisits.remove_label()*.

• Exported functions to reuse visit data:

  • List visited paths/labels with custom filter and sort (uses "robust frecency" by default). Can be used as source for pickers.

    See *MiniVisits.list_paths()* and *MiniVisits.list_labels()*. See *MiniVisits.gen_filter* and *MiniVisits.gen_sort*.

  • Select visited paths/labels using vim.ui.select().

    See *MiniVisits.select_path()* and *MiniVisits.select_labels()*.

  • Iterate through visit paths in target direction ("forward", "backward", "first", "last"). See *MiniVisits.iterate_paths()*.

• Exported functions to manually update visit index allowing persistent track of any user information. See *_index() functions.

Notes:

• All data is stored only in in-session Lua variable (for quick operation) and at config.store.path on disk (for persistent usage).

• It doesn't account for paths being renamed or moved (because there is no general way to detect that). Usually a manual intervention to the visit index is required after the change but before the next writing to disk (usually before closing current session) because it will treat previous path as deleted and remove it from index.

  There is a MiniVisits.rename_in_index() helper for that. If rename/move is done with 'mini.files', index is autoupdated.

For more information, see these tags in help file:

• *MiniVisits-overview*
• *MiniVisits-index-specification*
• *MiniVisits-examples*

Overview

Tracking visits

File system visits (both directory and files) tracking is done in two steps:

• On every dedicated event timer is (re)started to actually register visit after certain amount of time.

• When delay time passes without any dedicated events being triggered (meaning user is "settled" on certain buffer), visit is registered if all of the following conditions are met:

  • Module is not disabled.
  • Buffer is normal with non-empty name (used as visit path).
  • Visit path does not equal to the latest tracked one.

Visit is autoregistered for current directory and leads to increase of count and latest time of visit. See *MiniVisits-index-specification* help tag for more details.

Notes:

• All data is stored only in in-session Lua variable (for quick operation) and in one place on disk (for persistent usage). It is automatically written to disk before every Neovim exit.

• Tracking can be disabled by supplying empty string as track.event. Then it is up to the user to properly call MiniVisits.register_visit().

Reusing visits

Visit data can be reused in at least these ways:

• Get a list of visited paths and use it to visualize/pick/navigate visit history.

• Select one of the visited paths to open it.

• Move along visit history.

• Utilize labels. Any visit can be added one or more labels (like "core", "tmp", etc.). They are bound to the visit and are stored persistently.

  Labels can be used to manually create groups of files and/or directories that have particular interest to the user.

  There is no one right way to use them, though. See *MiniVisits-examples* help tag for some inspiration.

• Utilizing custom data. Visit index can be manipulated manually using _index() set of functions. All "storable" user data inside index is then stored on disk, so it can be used to create any kind of workflow user wants.

See *MiniVisits-examples* help tag for some actual configuration and workflow examples.

Installation

This plugin can be installed as part of 'mini.nvim' library (recommended) or as a standalone Git repository.

There are two branches to install from:

• main (default, recommended) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
• stable will be updated only upon releases with code tested during public beta-testing phase in main branch.

Here are code snippets for some common installation methods (use only one):

With mini.deps

Github repo	Branch	Code snippet
'mini.nvim' library	Main	Follow recommended 'mini.deps' installation
	Stable
Standalone plugin	Main	add('echasnovski/mini.visits')
	Stable	add({ source = 'echasnovski/mini.visits', checkout = 'stable' })

With folke/lazy.nvim

Github repo	Branch	Code snippet
'mini.nvim' library	Main	{ 'echasnovski/mini.nvim', version = false },
	Stable	{ 'echasnovski/mini.nvim', version = '*' },
Standalone plugin	Main	{ 'echasnovski/mini.visits', version = false },
	Stable	{ 'echasnovski/mini.visits', version = '*' },

With junegunn/vim-plug

Github repo	Branch	Code snippet
'mini.nvim' library	Main	Plug 'echasnovski/mini.nvim'
	Stable	Plug 'echasnovski/mini.nvim', { 'branch': 'stable' }
Standalone plugin	Main	Plug 'echasnovski/mini.visits'
	Stable	Plug 'echasnovski/mini.visits', { 'branch': 'stable' }

Important: don't forget to call require('mini.visits').setup() to enable its functionality.

Note: if you are on Windows, there might be problems with too long file paths (like error: unable to create file <some file name>: Filename too long). Try doing one of the following:

• Enable corresponding git global config value: git config --system core.longpaths true. Then try to reinstall.

Default config

-- No need to copy this inside `setup()`. Will be used automatically.
{
  -- How visit index is converted to list of paths
  list = {
    -- Predicate for which paths to include (all by default)
    filter = nil,

    -- Sort paths based on the visit data (robust frecency by default)
    sort = nil,
  },

  -- Whether to disable showing non-error feedback
  silent = false,

  -- How visit index is stored
  store = {
    -- Whether to write all visits before Neovim is closed
    autowrite = true,

    -- Function to ensure that written index is relevant
    normalize = nil,

    -- Path to store visit index
    path = vim.fn.stdpath('data') .. '/mini-visits-index',
  },

  -- How visit tracking is done
  track = {
    -- Start visit register timer at this event
    -- Supply empty string (`''`) to not do this automatically
    event = 'BufEnter',

    -- Debounce delay after event to register a visit
    delay = 1000,
  },
}

Similar plugins

• nvim-telescope/telescope-frecency.nvim
• ThePrimeagen/harpoon