refactoring.nvim: eight operators, no keymaps, and a query name for every feature
The Refactoring library based off the Refactoring book by Martin Fowler
At a glance
- What is it?
- A Neovim plugin whose whole design is that the editor should not have to know about languages. Every operation it offers declares the exact tree-sitter queries it needs and whether it needs a language server, so adding a language means writing queries rather than writing Lua, and the feature list doubles as a porting checklist.
- Who is it for?
- This is the plugin to try if you refactor often enough that renaming a variable by hand has become muscle memory, and the evidence for it is the feature list rather than any benchmark: the operations rewrite every reference in a buffer at once, they compose with dot-repeat and with the motions you already use, and nothing is bound behind your back. Two things to know before you rely on it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- ThePrimeagen/refactoring.nvim3,662 ★ · +14
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| ThePrimeagen/refactoring.nvim | 3.6k | 3.7k |
14 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Eight operations, four of them refactorings and four of them print helpers
The feature list is eight items and it divides cleanly in two. Four are refactorings: inline a variable into all of its references, extract an expression and all of its usages into a variable, inline a function into all of its references, and extract text into a function and replace it with a call. Four are debugging helpers: insert a print statement for the location under the cursor, for all occurrences of a variable in the selection, for the selected expression, and clean those print statements back out of a selection. The inliners are the ones with a stated limit, since inlining a function only works when it has a single return statement. The print statements use a marker format that names the enclosing function and a loop, which is what makes the cleanup operation able to find them again.
Every feature names the exact queries it needs
This is the detail that makes the plugin portable, and it is easy to miss on a first read. Every feature in the list has a requirements line, and the requirements are named queries, not descriptions: inlining a variable needs two specific query files, extracting a function needs four, and cleaning up print statements needs exactly one. A reader who wants to know what supporting a new language costs can count the files. The README also points at the bundled queries for the languages already supported, so the starting point for a new language is a directory of files you can read rather than a specification you have to infer.
Two operations need a language server and six do not
Half the feature list names the two language server requests it needs, and half names only queries. The two that need a server are the inliners, because finding every reference to a definition is the one job a parser alone does badly. Everything else works from tree-sitter alone: extracting a variable, extracting a function, and all four print helpers. That split has a practical consequence, because a language only gets a server if its ecosystem has a good one. So the plugin's coverage is uneven by construction, and the honest way to describe its language support is six operations everywhere and eight where a server exists.
They are operators, so your motions and dot-repeat keep working
The plugin does not implement these as commands with their own argument parsing. It registers them as operators, which is the editor's own mechanism for something that transforms a motion or a text object, and that single decision is why the README can claim support for dot-repeat and for any text object or motion. A refactoring is therefore invoked the way you already invoke a deletion, and repeating it is the same keystroke you already use. The header's framing is that the value of an environment with good automated refactorings is that you can trust them, and making them operators is what lets the editor's own composition rules do that work instead of a bespoke keymap layer.
No keymaps are created, and every suggested one is an expression mapping
The plugin deliberately binds nothing. What it offers instead is a single mapping that opens a chooser, and the point of the comment inside it is the whole design:
local keymap = vim.keymap
keymap.set({ "n", "x" }, "<leader>rs", function()
-- this keymap doesn't select any textobject by default, so you may need to provide one each time you use it.
require("refactoring").select_refactor()
end, { desc = "Select refactor" })Because the operations are operators, a mapping that calls one has to be an expression mapping, which is why every example in the documentation sets that option. The alternative the README documents is one mapping per operation, including a variant that appends a text object for the current line and one that extracts into a file. Either way the plugin stays out of your keymap file, and the command it also provides takes extra arguments as input for the operations that need something typed.
Configuration has three scopes, one of them per buffer
The default settings live in a file inside the plugin, and the README says any field can be overridden. What is more interesting is the three scopes it lists. You can override globally by calling the setup function, you can pass overrides to a single call of one operation, and you can set a buffer-local variable to override them for one buffer. That third scope is what makes a plugin that rewrites every reference in a file safe to try on a file where the default behaviour is wrong, and it is the concrete form of the claim that the plugin allows fine-grained customisation while providing reasonable defaults.
A language is added by writing queries in your own config, and living with them
The contribution guide is three steps and the first one is not to send a pull request. You create the required query files for the language in your own configuration directory, using the names the feature list gives you and the structure the bundled queries demonstrate, with the files starting with a modeline directive that extends a parent query. You add the code generation functions the feature needs to your global configuration. Then you use it daily for a while, and only then open a pull request. The stated principle at the end is the whole design in two sentences: the goal is to keep the plugin's own logic generic and language agnostic, which is why all language-specific input arrives from servers and queries, and the better your queries are, the better that language's support will be.
The test target installs three language servers and eleven parsers
The build file is short and it tells you what the project considers its own dependencies. Running the tests means launching the editor headless with a minimal initialisation file and a small test framework, which the file clones on demand into a dependencies directory with the blobs filtered out. The same target then installs three language servers, which is what the two inlining operations need in order to be tested, and then runs the parser installer for eleven languages. The parser list and the supported language list in the README are not quite the same set: the build covers a markup language and two flavours of one language that the supported list groups together. So the build is the more precise document of what is exercised in continuous integration.
Editorial conclusion
This is the plugin to try if you refactor often enough that renaming a variable by hand has become muscle memory, and the evidence for it is the feature list rather than any benchmark: the operations rewrite every reference in a buffer at once, they compose with dot-repeat and with the motions you already use, and nothing is bound behind your back. Two things to know before you rely on it. Two of the eight operations need a language server that answers two specific requests, so a language without one gets you the six tree-sitter-only operations. And the editor requirement is a specific patch release of a recent major version, with one of its two dependencies needed only on the earlier of the two versions it supports.
Frequently asked questions
What is refactoring.nvim?
A Neovim plugin providing eight operators, four of them refactorings and four of them helpers that insert and clean up debug print statements. They are built on language servers and tree-sitter queries rather than on per-language code in the plugin, and the header quotes the book's own thesis about trusting good automated refactorings.
How can I refactor my C# code?
C# is in the supported language list and the project's own dependency target installs a parser for it. The two inlining operations additionally need a language server that answers the reference and definition requests; the extraction operations and all four print helpers need only the parser and queries.
What is the purpose of refactoring?
The README puts the book's argument in its header: if you use an environment that has good automated refactorings, you can trust those refactorings. The plugin's contribution is to make that claim hold in the editor, by rewriting all references in a buffer at once rather than one at a time.
When should code be refactored?
The repository does not discuss timing. Its claim is narrower and mechanical: the operations operate on a selection and rewrite every reference inside it, so they are meant for the places where a rename or an extraction would otherwise be done by hand.
Does refactoring.nvim need any Neovim configuration?
No setup call is required for the plugin to work, and no keymaps are created by default. The README suggests either one mapping per operation or a single mapping that opens a chooser, plus a user command that runs any refactoring with completions and a preview.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/theprimeagen-refactoring-nvim)Star history chart for your README
[](https://hysenlabs.com/projects/theprimeagen-refactoring-nvim)Was this useful?