KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

nvim-recorder

★ 289 Open GitHub ↗

Enhance the usage of macros in Neovim.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nvim-recorder 📹 
<a href="https://dotfyle.com/plugins/chrisgrieser/nvim-recorder">
<img alt="badge" src="https://dotfyle.com/plugins/chrisgrieser/nvim-recorder/shield"/></a>

Enhance the usage of macros in Neovim.

- [Features](#features)
- [Setup](#setup)
    - [Installation](#installation)
    - [Configuration](#configuration)
    - [Status line components](#status-line-components)
- [Basic usage](#basic-usage)
- [Advanced usage](#advanced-usage)
    - [Performance optimizations](#performance-optimizations)
    - [Macro breakpoints](#macro-breakpoints)
    - [Lazy-loading the plugin](#lazy-loading-the-plugin)
- [About the developer](#about-the-developer)

## Features
- **Simplified controls**: One key to start and stop recording, a second key for
  playing the macro. Instead of `qa … q @a @@`, you just do `q … q Q Q`.[^1]
- **Macro Breakpoints** for easier debugging of macros. Breakpoints can also be
  set after the recording and are automatically ignored when triggering a macro
  with a count.
- **Status line components**: Particularly useful if you use `cmdheight=0` where
  the recording status is not visible.
- **Macro-to-Mapping**: Copy a macro, so you can save it as a mapping.
- **Various quality-of-life features**: notifications with macro content, the
  ability to cancel a recording, a command to edit macros,
- **Performance Optimizations for large macros**: When the macro is triggered
  with a high count, temporarily enable some performance improvements.
- Uses up-to-date nvim features like `vim.notify`. This means you can get
  confirmation notices with plugins like
  [nvim-notify](https://github.com/rcarriga/nvim-notify).

## Setup

### Installation

```lua
-- lazy.nvim
{
	"chrisgrieser/nvim-recorder",
	dependencies = "rcarriga/nvim-notify", -- optional
	opts = {}, -- required even with default settings, since it calls `setup()`
},

-- packer
use {
	"chrisgrieser/nvim-recorder",
	requires = "rcarriga/nvim-notify", -- optional
	config = function() require("recorder").setup() end,
}
```

Calling `setup()` (or `lazy`'s `opts`) is **required**.

### Configuration

```lua
-- default values
require("recorder").setup {
	-- Named registers where macros are saved (single lowercase letters only).
	-- The first register is the default register used as macro-slot after
	-- startup.
	slots = { "a", "b" },

-- specify one of options: 
    -- [static]   -> use static slots, this is default behaviour
    -- [rotate]   -> rotates through letters specified in slots[]
    dynamicSlots = "static",

mapping = {
		startStopRecording = "q",
		playMacro = "Q",
		switchSlot = "<C-q>",
		editMacro = "cq",
		deleteAllMacros = "dq",
		yankMacro = "yq",
		-- ⚠️ this should be a string you don't use in insert mode during a macro
		addBreakPoint = "##",
	},

-- Clears all macros-slots on startup.
	clear = false,

-- Log level used for non-critical notifications; mostly relevant for nvim-notify.
	-- (Note that by default, nvim-notify does not show the levels `trace` & `debug`.)
	logLevel = vim.log.levels.INFO, -- :help vim.log.levels

-- If enabled, only essential notifications are sent.
	-- If you do not use a plugin like nvim-notify, set this to `true`
	-- to remove otherwise annoying messages.
	lessNotifications = false,

-- Use nerdfont icons in the status bar components and keymap descriptions
	useNerdfontIcons = true,

-- Performance optimizations for macros with high count. When `playMacro` is
	-- triggered with a count higher than the threshold, nvim-recorder
	-- temporarily changes changes some settings for the duration of the macro.
	performanceOpts = {
		countThreshold = 100,
		lazyredraw = true, -- enable lazyredraw (see `:h lazyredraw`)
		noSystemClipboard = true, -- remove `+`/`*` from clipboard option
		autocmdEventsIgnore = { -- temporarily ignore these autocmd events
			"TextChangedI",
			"TextChanged",
			"InsertLeave",
			"InsertEnter",
			"InsertCharPre",
		},
	},

-- [experimental] partially share keymaps with nvim-dap.
	-- (See README for further explanations.)
	dapSharedKeymaps = false,
}
```

If you want to handle multiple macros or use `cmdheight=0`, it is recommended to
also set up the status line components:

### Status line components

```lua
-- Indicates whether you are currently recording. Useful if you are using
-- `cmdheight=0`, where recording-status is not visible.
require("recorder").recordingStatus()

-- Displays non-empty macro-slots (registers) and indicates the selected ones.
-- Only displayed when *not* recording. Slots with breakpoints get an extra `#`.
require("recorder").displaySlots()
```

> [!TIP]
> Use with the config `clear = true` to see recordings you made this session.

Example for adding the status line components to [lualine](https://github.com/nvim-lualine/lualine.nvim):

```lua
lualine_y = {
	{ require("recorder").displaySlots },
},
lualine_z = {
	{ require("recorder").recordingStatus },
},
```

> [!TIP]
> Put the components in different status line segments, so they have
> a different color, making the recording status more distinguishable
> from saved recordings

## Basic usage
- `startStopRecording`: Starts recording to the current macro slot (so you do
  not need to specify a register). Press again to end the recording.
- `playMacro`: Plays the macro in the current slot (without the need to specify
  a register).
- `switchSlot`: Cycles through the registers you specified in the configuration.
  Also show a notification with the slot and its content. (The currently
  selected slot can be seen in the [status line
  component](#status-line-components).)
- `editMacro`: Edit the macro recorded in the active slot. (Be aware that these
  are the keystrokes in "encoded" form.)
- `yankMacro`: Copies the current macro in decoded form that can be used to
  create a mapping from it. Breakpoints are removed from the copied macro.
- `deleteAllMacros`: Copies the current macro in decoded form that can be used
  to

> [!TIP]
> For recursive macros (playing a macro inside a macro), you can still use
> the default command `@a`.

## Advanced usage

### Performance optimizations
Running macros with a high count can be demanding on the system and result in
lags. For this reason, `nvim-recorder` provides some performance optimizations
that are temporarily enabled when a macro with a high count is run.

Note that these optimizations do have some potential drawbacks.
- [`lazyredraw`](https://neovim.io/doc/user/options.html#'lazyredraw') disables
  redrawing of the screen, which makes it harder to notice edge cases not
  considered in the macro. It may also appear as if the screen is frozen for a
  while.
- Disabling the system clipboard is mostly safe, if you do not intend to copy
  content to it with the macro.
- Ignoring auto-commands is not recommended, when you rely on certain plugin
  functionality during the macro, since it can potentially disrupt those
  plugins' effect.

### Macro breakpoints
`nvim-recorder` allows you to set breakpoints in your macros which can be
helpful for debugging macros. Breakpoints are automatically ignored when you
trigger the macro with a count.

**Setting Breakpoints** 
- *During a recording:* press the `addBreakPoint` key (default: `##`) in normal
   mode
- *After a recording:* use `editMacro` and add or remove the `##` manually.

**Playing Macros with Breakpoints** 
- Using the `playMacro` key, the macro automatically stops at the next
  breakpoint. The next time you press `playMacro`, the next segment of the macro
  is played.
- Starting a new recording, editing a macro, yanking a macro, or switching macro
  slot all reset the sequence, meaning that `playMacro` starts from the
  beginning again.

> [!TIP]
> You can do other things in between playing segments of the macro, like
> moving a few characters to the left or right. That way you can also use
> breakpoints to manually correct irregularities.

**Ignoring Breakpoints** 
When you play the macro with a *count* (for example `50Q`), breakpoints are
automatically ignored.

> [!TIP]
> Add a count of 1 (`1Q`) to play a macro once and still ignore breakpoints.

**Shared Keybindings with `nvim-dap`**  
If you are using [nvim-dap](https://github.com/mfussenegger/nvim-dap), you can
use `dapSharedKeymaps = true` to set up the following shared keybindings:
1. `addBreakPoint` maps to `dap.toggle_breakpoint()` outside
a recording. During a recording, it adds a macro breakpoint instead.
2. `playMacro` maps to `dap.continue()` if there is at least one
DAP-breakpoint. If there is no DAP-breakpoint, plays the current
macro-slot instead.

Note that this feature is experimental, since the [respective API from nvim-dap
is non-public and can be changed without deprecation
notice](https://github.com/mfussenegger/nvim-dap/discussions/810#discussioncomment-4623606).

### Lazy-loading the plugin
`nvim-recorder` is best lazy-loaded on the mappings for `startStopRecording` and
`playMacro`. However, adding the status line components to `lualine` will cause
the plugin to load before you start or play a recording.

To avoid this, the status line components need to be loaded only in the plugin's
`config`. The drawback of this method is that no component is shown when until
you start or play a recording (which you can completely disregard when you set
`clear = true`, though).

Nonetheless, the plugin is pretty lightweight (~400 lines of code), so not
lazy-loading it should not have a big impact.

```lua
-- minimal config for lazy-loading with lazy.nvim
{
	"chrisgrieser/nvim-recorder",
	dependencies = "rcarriga/nvim-notify",
	keys = {
		-- these must match the keys in the mapping config below
		{ "q", desc = " Start Recording" },
		{ "Q", desc = " Play Recording" },
	},
	config = function()
		require("recorder").setup({
			mapping = {
				startStopRecording = "q",
				playMacro = "Q",
			},
		})

local lualineZ = require("lualine").get_config().sections.lualine_z or {}
			local lualineY = require("lualine").get_config().sections.lualine_y or {}
			table.insert(lualineZ, { require("recorder").recordingStatus })
			table.insert(lualineY, { require("recorder").displaySlots })

require("lualine").setup {
				tabline = {
					lualine_y = lualineY,
					lualine_z = lualineZ,
				},
			}
	end,
},
```

## About the developer
In my day job, I am a sociologist studying the social mechanisms underlying the
digital economy. For my PhD project, I investigate the governance of the app
economy and how software ecosystems manage the tension between innovation and
compatibility. If you are interested in this subject, feel free to get in touch.

- [Website](https://chris-grieser.de/)
- [Mastodon](https://pkm.social/@pseudometa)
- [ResearchGate](https://www.researchgate.net/profile/Christopher-Grieser)
- [LinkedIn](https://www.linkedin.com/in/christopher-grieser-ba693b17a/)

If you find this project helpful, you can support me via [🩷 GitHub
Sponsors](https://github.com/sponsors/chrisgrieser?frequency=one-time).

[^1]: As opposed to vim, Neovim already allows you to use `Q` to [play the last
    recorded macro](https://neovim.io/doc/user/repeat.html#Q). Considering this,
    the simplified controls really only save you one keystroke for one-off
    macros. However, as opposed to Neovim's built-in controls, you can still
    keep using `Q` for playing the not-most-recently recorded macro.

nvim-recorder

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README