github github
stars 81
issues 1
subscribers 2
forks 6



19 hours ago

nvim-chainsaw 🪚

Speed up log creation. Create various kinds of language-specific log statements, such as logs of variables, assertions, or time-measuring.


-- lazy.nvim
{ "chrisgrieser/nvim-chainsaw" },

-- packer
use { "chrisgrieser/nvim-chainsaw" }

It is recommended to use nvim 0.9+ and install the Treesitter parsers for the respective languages, as this improves variable identification. The plugin falls back to the word under the cursor if those requirements are not met.

Built-in language support

  • JavaScript / TypeScript / TypeScriptReact
  • Lua
  • Python
  • Shell
  • AppleScript
  • CSS / SCSS*
  • Ruby
  • Rust

Not every language supports every type of log statement. For details on what is supported, see log-statements-data.lua.

* For CSS, nvim-chainsaw simply uses similar statements with debugging purposes, such as outline: 2px solid red !important; to quickly assess whether a selector is correct or not.


The plugin offers various types of log statements. Bind keymaps for the ones you want to use.

List of Commands

-- log the name and value of the a variable
-- normal mode: treesitter node or word under cursor, visual mode: selection

-- like variableLog, but with syntax specific to inspect an object, such as
-- `console.log(JSON.stringify(foobar))` in javascript

-- assertion statement for the variable under the cursor

-- create log statement, and position the cursor to enter a message

-- prints the stacktrace of the current call

-- Minimal log statement, with an emoji for differentiation. Intended for
-- control flow inspection, i.e. to quickly glance whether a condition was
-- triggered or not. (Inspired by AppleScript's `beep` command.)

-- 1st call: start measuring the time
-- 2nd call: logs the time duration since

-- debug statements like `debugger` in javascript or `breakpoint()` in python


-- remove all log statements created by chainsaw

These features can also be accessed by the user command :ChainSaw.

Each option corresponds to the commands above. For example, :ChainSaw variableLog is same as :lua require("chainsaw").variableLog().

Smart Variable Identification

When the variable under the cursor is an object with fields, chainsaw attempts to automatically select the correct field.

myVariable.myF[i]eld = "foobar"
-- prints: myVariable.myField

myVa[r]iable.myField = "foobar"
-- prints: myVariable

Filetypes currently supporting this feature:

  • Lua
  • Python
  • JavaScript / TypeScript / TypeScriptReact

PRs adding support for more languages are welcome. The relevant code section can be found here.


Basic Configuration

-- default settings
require("chainsaw").setup {
    -- The marker should be a unique string, since `.removeLogs()` will remove
    -- any line with it. Emojis or strings like "[Chainsaw]" are recommended.
    marker = "🪚",

    -- emojis used for `.beepLog()`
    beepEmojis = { "🔵", "🟩", "⭐", "⭕", "💜", "🔲" },

Add your own log statements

Custom log statements are added in the setup() call. The values are formatted lua strings, meaning %s is a placeholder that is dynamically replaced with the actual value. See log-statements-data.lua for examples.

PRs adding log statements for more languages are welcome.

require("chainsaw").setup ({
    logStatements = {
        variableLog = {
            javascript = 'console.log("%s %s:", %s);',
            otherFiletype = … -- <-- add the statement for your filetype here
        -- the same way for the other statement types

Have your formatter ignore the log statements

A common problem is that formatters like prettier break up the log statements, making them hard to read and also breaking removeLogs(), which relies on each line containing the marker emoji.

The simplest method to deal with this is to customize the log statement in your configuration to include /* prettier-ignore */:

require("chainsaw").setup {
    logStatements = {
        variableLog = {
            javascript = {
                "/* prettier-ignore */ // %s", -- adding this line
                'console.log("%s %s:", %s);',

Similar Lua Plugins

The other plugins are more feature-rich, while, while nvim-chainsaw tries to achieve the core functionality in a far more lightweight manner to keep maintenance minimal.


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.

I also occasionally blog about vim: Nano Tips for Vim