telescope-frecency.nvim

A telescope.nvim extension that offers intelligent prioritization when selecting files from your editing history.

Using an implementation of Mozilla's Frecency algorithm (used in Firefox's address bar), files edited frecently are given higher precedence in the list index.

As the extension learns your editing habits over time, the sorting of the list is dynamically altered to priotize the files you're likely to need.

• Scores shown in finder for demonstration purposes - disabled by default

Frecency: Sorting by 'frequency' and 'recency'

'Frecency' is a score given to each unique file indexed in a file history database.

A timestamp is recorded once per session when a file is first loaded into a buffer.

The score is calculated using the age of the 10 most recent timestamps and the total amount of times that the file has been loaded:

Recency values (per timestamp)

Timestamp age	Value
4 hours	100
1 day	80
3 days	60
1 week	40
1 month	20
90 days	10

Score calculation

score = frequency * recency_score / max_number_of_timestamps

What about files that are neither 'recent' or 'frequent'?

Frecency works best on files that have already indexed and have been given a reasonably high score.

New projects or rarely used files with generic names either don't get listed at all or can be buried under results with a higher score.

Frecency tackles this with Workspace Filters:

The Workspace filter feature enables you to select from user defined filter tags that map to a directory or collection of directories. Filters are applied by entering :workspace_tag: anywhere in the query. Filter name completion is available by pressing <Tab> after the first : character.

When a filter is applied, results are reduced to entries whose path is a descendant of the workspace directory. The indexed results are optionally augmented with a listing of all files found in a recurssive search of the workspace directory. Non-indexed files are given a score of zero and appear below the 'frecent' entries. When a non-indexed file is opened, it gains a score value and is available in future 'frecent' search results.

If the active buffer (prior to the finder being launched) is attached to an LSP server, an automatic LSP tag is available, which maps to the workspace directories provided by the language server.

Requirements

• telescope.nvim (required)
• sql.nvim (required)

Timestamps and file records are stored in an SQLite3 database for persistence and speed. This plugin uses sql.nvim to perform the database transactions.

Installation

Packer.nvim

use {
  "nvim-telescope/telescope-frecency.nvim",
  config = function()
    require"telescope".load_extension("frecency")
  end
}

TODO: add installation instructions for other package managers

If no database is found when running Neovim with the plugin installed, a new one is created and entries from shada v:oldfiles are automatically imported.

Usage

:Telescope frecency

..or to map to a key:

vim.api.nvim_set_keymap("n", "<leader><leader>", "<Cmd>lua require('telescope').extensions.frecency.frecency()<CR>", {noremap = true, silent = true})

Filter tags are applied by typing the :tag: name (adding surrounding colons) in the finder query. Entering :<Tab> will trigger omnicompletion for available tags.

Configuration

See default configuration for full details on configuring Telescope.

• ignore_patterns (default: {"*.git/*", "*/tmp/*"})

  Patterns in this table control which files are indexed (and subsequently which you'll see in the finder results).

• show_scores (default : false)

  To see the scores generated by the algorithm in the results, set this to true.

• workspaces (default: {})

  This table contains mappings of workspace_tag -> workspace_directory The key corresponds to the :tag_name used to select the filter in queries. The value corresponds to the top level directory by which results will be filtered.

• show_unindexed (default: true)

Determines if non-indexed files are included in workspace filter results.

Example Configuration:

telescope.setup {
  extensions = {
    frecency = {
      show_scores = false,
      show_unindexed = true,
      ignore_patterns = {"*.git/*", "*/tmp/*"},
      workspaces = {
        ["conf"]    = "/home/my_username/.config",
        ["data"]    = "/home/my_username/.local/share",
        ["project"] = "/home/my_username/projects",
        ["wiki"]    = "/home/my_username/wiki"
      }
    }
  },
}

Highlight Groups

TelescopeBufferLoaded
TelescopePathSeparator
TelescopeFrecencyScores
TelescopeQueryFilter

TODO: describe highlight groups

References

• Mozilla: Frecency algorithm