GutterMarks.nvim

A Neovim plugin that displays marks in the buffer gutter as signs. Keep track of your marks visually with customizable appearance and behavior.

Features

Display local marks (a-z) in the gutter
Display global marks (A-Z) in the gutter
Optional display of special marks (numbers, symbols)
Configurable sign text and highlight groups
Automatic refresh on text changes
Utility actions for enhanced marks workflow

Why this plugin

Read the launch blog post

I've been using marks.nvim and others to display marks in the gutter, but I don't need all the extra bells and whistles that those other plugins added. This is a fast, simple implementation that doesn't get in the way, and does not change nvim default behavior. Further, I worked a bit to benchmark and make sure this plugin is fast and the implementation does not impact Neovim performances.

Installation

Using vim.pack (Neovim 0.12+)

vim.pack.add({
  'https://github.com/dimtion/guttermarks.nvim',
})

Using lazy.nvim

{
  "dimtion/guttermarks.nvim",
  event = { "BufReadPost", "BufNewFile", "BufWritePre", "FileType" },
}

Using vim-plug

Plug 'dimtion/guttermarks.nvim'

Configuration

Optionally use setup(opts) function to configure the plugin:

require("guttermarks").setup({
  global_mark = { enabled = false },
})

See full default configuration:

{   local_mark = {     enabled = true,     sign = nil,     highlight_group = "GutterMarksLocal",     priority = 10,   },   global_mark = {     enabled = true,     sign = nil,     highlight_group = "GutterMarksGlobal",     priority = 11,   },   special_mark = {     enabled = false,     sign = nil,     marks = { "'", "^", ".", "[", "]", "<", ">", '"', "&quot;, &quot;0&quot;, &quot;1&quot;, &quot;2&quot;, &quot;3&quot;, &quot;4&quot;, &quot;5&quot;, &quot;6&quot;, &quot;7&quot;, &quot;8&quot;, &quot;9&quot; },     highlight_group = &quot;GutterMarksSpecial&quot;,     priority = 10,   },   excluded_filetypes = { &quot;NvimTree&quot;, &quot;&quot; },   excluded_buftypes = { &quot;terminal&quot;, &quot;prompt&quot;, &quot;quickfix&quot; },   -- Advanced: Customize Autocmd events that trigger a refresh   autocmd_triggers = {     &quot;BufEnter&quot;,     &quot;BufWritePost&quot;,     &quot;TextChanged&quot;,     &quot;TextChangedI&quot;,   }, }</code></pre>
Commands
| Command | Description | |---------|-------------| | :GutterMarks toggle | Toggle guttermarks display on/off | | :GutterMarks enable | Enable guttermarks display | | :GutterMarks disable | Disable guttermarks display | | :GutterMarks refresh | Force refresh guttermarks display |

Customizing Highlights
You can customize the default highlight groups in your colorscheme or init.lua:

<pre><code class="lang-lua">vim.api.nvimsethl(0, &quot;GutterMarksLocal&quot;, { fg = &quot;#ffff00&quot; }) vim.api.nvimsethl(0, &quot;GutterMarksGlobal&quot;, { fg = &quot;#ff0000&quot;, bold = true }) vim.api.nvimsethl(0, &quot;GutterMarksSpecial&quot;, { fg = &quot;#00ff00&quot;, italic = true })</code></pre>
Advanced Configuration
Enable Special Marks (disabled by default)

<pre><code class="lang-lua">require(&quot;guttermarks&quot;).setup({   special_mark = { enabled = true }, })</code></pre>
Enable Extra Special Marks
By default, even with specialmark enabled, some extra_ special marks are not
enabled, those are "{", "}", "(", ")" marks which move with every cusor
movement. To avoid refreshing the gutter at each movement those are disabled by
default. However, they can be re-enabled manually with the following config:
<pre><code class="lang-lua">require(&quot;guttermarks&quot;).setup({   special_mark = {     enabled = true,     marks = { &quot;&#39;&quot;, &quot;^&quot;, &quot;.&quot;, &quot;[&quot;, &quot;]&quot;, &quot;&lt;&quot;, &quot;&gt;&quot;, &#39;&quot;&#39;, &quot;", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "{", "}", "(", ")" },   },   autocmd_triggers = {     "BufEnter",     "BufWritePost",     "TextChanged",     "TextChangedI",     "CursorMoved",   }, })

Using Custom Signs

require("guttermarks").setup({
  local_mark = { sign = "▶" },
  global_mark = { sign = "▲" },
  special_mark = {
    enabled = true,
    sign = "●",
  },
})

Local Marks Only

require("guttermarks").setup({
  global_mark = { enabled = false },
  special_mark = { enabled = false },
})

Function Passed For Sign

require("guttermarks").setup({
  global_mark = {
    sign = function(mark)
      -- Show the mark letter with a prefix
      return "G" .. mark.mark
    end,
  },
})

GutterMarks Actions

To make marks more effective in vim, GutterMarks comes with a few actions that can be used by creating key mappings:

vim.keymap.set("n", "m;", require("guttermarks.actions").delete_mark, { desc = "Delete mark under cursor" })
vim.keymap.set("n", "]m", require("guttermarks.actions").nextbufmark, { desc = "Next mark in current buffer" }) vim.keymap.set("n", "[m", require("guttermarks.actions").prevbufmark, { desc = "Previous mark in current buffer" })
vim.keymap.set("n", "<leader>mq", function()     require("guttermarks.actions").markstoquickfix()     vim.cmd("copen") end, { desc = "Send marks to quickfix" })
vim.keymap.set("n", "<leader>mQ", function()     require("guttermarks.actions").markstoquickfix({         special_mark = true,     })     vim.cmd("copen") end, { desc = "Send marks to quickfix (include special marks)" })

Vim Marks cheat-sheet

Use ma to set local mark 'a', mA for global mark 'A'
Jump to marks with 'a (local) or 'A (global)
Use ` a ` to jump to exact position (line and column) of mark 'a'

Delete mark 'a' with :delmarks a`

🔗 More in this category