nvim-justice ⚖️

Lightweight integration of just in nvim.

Table of contents

• Features
• Installation
• Configuration
• Usage
• Using progress bars and streaming output
• About the author

Features

• Quick-select recipes via keys shown at the left of the window. Running recipes thus requires only 2–3 keystrokes.
• Runs asynchronously and outputs results in a notification window.
• Supports streaming output (e.g., for recipes that display a progress bar).
• Can alternatively run asynchronously and send individual recipe results to the quickfix list.
• Inspect recipes and variable values.
• Hide specific recipes, useful to always exclude recipes that require user input.

Installation

Requirements

• nvim 0.10+
• just
• optional: snacks.nvim (required for streaming output)
• optional: Treesitter parser for syntax highlighting (:TSInstall just)

-- lazy.nvim
{
	"chrisgrieser/nvim-justice",
	keys = {
		{ "<leader>j", function() require("justice").select() end, desc = "Justice" },
	},
},

-- packer
use {
	"chrisgrieser/nvim-justice",
}
vim.keymap.set("n", "<leader>j", function() require("justice").select() end, { desc = "Justice" })

Configuration

The setup call is optional.

-- default settings
require("justice").setup {
	recipes = {
		-- All strings are checked via `string.find`, that is as lua patterns.
		-- (Note that in lua patterns, a `-` needs to escaped as `%-`.)
		ignore = { -- hides them from the nvim-justice selection window
			name = { "fzf", "^_" }, -- ...if the name contains "fzf" or starts with "_"
			comment = { "interactive" }, -- ...if the comment contains "interactive"
		},
		streaming = { -- streams output, e.g. for progress bars (requires `snacks.nvim`)
			name = { "download" },
			comment = { "streaming", "curl" }, -- comment with "streaming" or "curl"
		},
		quickfix = { -- runs synchronously and sends output to quickfix list
			name = { "%-qf$" }, -- name ending with "-qf"
			comment = { "quickfix" },
		},
	},
	keymaps = {
		next = "<Tab>",
		prev = "<S-Tab>",
		runRecipe = "<CR>",
		closeWin = { "q", "<Esc>" },
		quickSelect = { "f", "d", "s", "a" },
		showRecipe = "<Space>",
		showVariables = "?",
	},
	window = {
		border = "rounded",
		recipeCommentMaxLen = 35,
	},
	highlights = {
		quickSelect = "Conditional",
		icons = "Function",
	},
	icons = {
		just = "󰖷",
		streaming = "ﲋ",
		quickfix = "",
		ignore = "󰈉",
	},
}

Usage

-- basic usage
require("justice").select()

-- optionally set parameters
require("justice").select({
	justfile = "path/to/custom/justfile", -- passed to `--justfile=`
})

• Navigate the window via <Tab> & <S-Tab>, select with <CR>.
• Quick-select recipes via keys shown at the left of the window.
• Show recipe via <Space>.

Using progress bars and streaming output

Here is an example of a just recipe that displays a simple progress bar.

This kind of progress bar works the same when triggered in the terminal via just demo-progressbar and via nivm-justic.

# streaming <-- makes nvim-justice stream the output
demo-progressbar:
    #!/usr/bin/env zsh
    char="+"
    progress=""
    for i in {1..20}; do
        progress="$progress$char"
		printf "\33[2K\r" # `\33[2K` fully erase the line, `\r` moves to the BoL
        printf "$progress" # printf (or `echo -n`) needed to not create a newline
        sleep 0.1
    done
    printf "\33[2K\r"
    echo "Done."

Note this version of a progress bar works in the terminal, but will not work in nvim-justice, since the plugin prints every unit of data individually.

# streaming
progressbar_not_working_in_nvim-justice:
    #!/usr/bin/env zsh
    char="+"
    for i in {1..20}; do
        printf "$char"
        sleep 0.1
    done
    printf "\33[2K\r"
    echo "Done."

About the author

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

• Website
• Mastodon
• ResearchGate
• LinkedIn