repository·master·Indexed 23 days ago
https://github.com/stevearc/overseer.nvimA task runner and job management plugin for Neovim that allows users to run, manage, and automate complex workflows through a customizable UI and API. It features built-in support for frameworks like make, npm, cargo, and .vscode/tasks.json, and utilizes an Entity Component System (ECS) architecture to attach custom logic to tasks, such as output parsing, automatic restarts on save, and integration with vim.diagnostic, quickfix, and nvim-dap.
overseer.nvim is a task runner and job management plugin for Neovim. Key features include:
make, npm, cargo, and .vscode/tasks.json.vim.diagnostic and quickfix.preLaunchTask when used with nvim-dap.A component alias is a string that resolves to a list of components.
default: The standard group of components used for all tasks if none are specified.default_vscode: The standard group for VS Code task integration.You can define your own aliases in setup({ component_aliases = { ... } }).
Important: When adding components to a task, if a component already exists, adding it again is a no-op. To override parameters of a component within an alias, list your specific component before the alias.
local task = require("overseer").new_task({
cmd = "g++ " .. vim.fn.expand("%"),
components = {
-- Add on_complete_notify first with customized 'statuses' parameter
{ "on_complete_notify", statuses = { "SUCCESS" } },
-- The default group also adds on_complete_notify, but it will be ignored because it's second
"default"
}
})There are two primary ways to handle task sequencing in Overseer:
dependencies componentAdd a dependencies component to a task. Setting sequential = true ensures the listed tasks run one after another before the main task proceeds.
orchestrator strategyDefine a task with the orchestrator strategy. This creates a single orchestration task that manages a list of tasks (which can be strings or task objects) in the specified order. This is useful for complex workflows (e.g., Clean $\rightarrow$ Build $\rightarrow$ Serve).
Note: You can also use VS Code's .vscode/tasks.json dependsOn keyword, which Overseer will automatically translate into one of these methods.
-- Method 1: dependencies component
overseer.run_task({ name = "npm serve", autostart = false }, function(task)
if task then
task:add_component({
"dependencies",
tasks = {
"npm build",
{ cmd = "sleep 10" },
},
sequential = true,
})
task:start()
end
end)
-- Method 2: orchestrator strategy
local task = overseer.new_task({
name = "Build and serve app",
strategy = {
"orchestrator",
tasks = {
"make clean",
{
"npm build",
{ cmd = { "lessc", "styles.less", "styles.css" },
},
"npm serve",
},
},
})
task:start()The Task result is a table used by components and actions. While there is no strict schema, two specific keys have built-in functionality:
diagnostics: A list of quickfix items (compatible with :help setqflist) used for displaying errors/warnings.error: Used to store internal Overseer errors encountered while running the task.Overseer uses an Entity Component System (ECS) architecture to manage jobs:
new_task() method or, more commonly, via Templates.To customize behavior, you should use components rather than modifying the core task logic.
Template providers allow you to generate multiple templates at runtime (e.g., generating a task for every target in a Makefile). They are defined similarly to templates but use a generator function instead of a builder.
generator returns a list of tasks.callback argument in the generator to perform async work (like vim.system) and return results via the callback.cache_key to provide a function that returns a key (like a config file path). Overseer will cache the results and clear them when the file changes.condition to restrict when the provider is active (e.g., specific filetypes).---@type overseer.TemplateFileProvider
return {
generator = function(search, callback)
do_some_work(function(err)
if err then
callback(err)
return
end
callback({...})
end)
end,
condition = {
filetype = { "c" },
},
cache_key = function(opts)
return vim.fs.find("Makefile", { upward = true, type = "file", path = opts.dir })[1]
end,
}terminal, which passes the task cmd to vim.fn.termopen(). Strategies can be used as drop-in replacements for terminal with different features (like jobstart) or can fundamentally change task behavior (like orchestrator).For advanced parsing requirements that a simple function cannot handle, implement the overseer.OutputParser interface. An OutputParser requires the following methods:
parse(line): Processes a single line of output.get_result(): Returns a table of results. To interact with diagnostics-related components, ensure your table includes a diagnostics key containing the list of parsed entries.reset(): Resets the parser's internal state (e.g., clearing the results list).local parser = {
_result = {},
---Parse a single line of output
---@param line string
parse = function(self, line)
local fname, lnum, msg = line:match("^(.*):(%d+): (.*)$")
if fname
table.insert(self._result, {
filename = fname,
lnum = tonumber(lnum),
text = msg
})
end
end,
---Get the results for the task
---@return table<string, any>
get_result = function(self)
-- The task result is an arbitrary key-value table, but most of the time for output parsing
-- you will want to set the `diagnostics` key. This is the special key that interacts with
-- all the diagnostics-related components.
-- Note that the other parser types (function, problem matcher, errorformat) automatically put
-- their results in the `diagnostics` key.
return { diagnostics = self._result }
end,
---This is called when the task is reset
reset = function(self)
self._result = {}
end,
}:OverseerRun command, the available options are populated from your defined templates. Use templates instead of manual new_task() calls for most use cases to ensure tasks are easily discoverable and repeatable.The task editor allows you to manually tweak or experiment with a task's components on the fly.
How to use it:
<CR>.edit action.Editing workflow:
<C-x><C-o>) to autocomplete possible values.dd).o).:w to confirm and submit your changes.Overseer can read and execute tasks defined in .vscode/tasks.json. When you run :OverseerRun, these tasks will appear in the list.
Supported Features:
process, shell, typescript, node.${input:variableID}).$tsc, $jshint-stylish).dependsOrder = sequence).group (supports BUILD, RUN, TEST, CLEAN) and isDefault.launch.json via DAP.Unsupported Features:
gulp, grunt, jake.${workspacefolder:*}, ${config:*}, ${command:*}, ${defaultBuildTask}.The task list displays all created tasks, including their status, name, and a summary of output.
Commands:
:OverseerOpen: Open the task list.:OverseerClose: Close the task list.:OverseerToggle: Toggle the task list visibility.Interactions within the list:
?: Show a list of all available keybindings.<CR> (Enter): Open a menu of available actions for the selected task.Customization:
You can customize the display of the task list by providing a custom task_list.render function in your overseer.setup() configuration.