overseer.nvim

A task runner and job management plugin for Neovim

<!-- TOC -->

• Features
• Requirements
• Installation
• Quick start
• Tutorials
  • Build a C++ file
  • Run a file on save
• Guides
  • Custom tasks
  • Actions
  • Custom components
  • Task events
  • Customizing built-in tasks
  • Customizing the task appearance in the task list
  • Parsing output
  • Running tasks sequentially
  • VS Code tasks
• Explanation
  • Architecture
  • Task list
  • Task editor
  • Alternatives
  • FAQ
• Third-party integrations
  • Lualine
  • Heirline
  • Neotest
  • DAP
  • Session managers
• Recipes
  • Run a quick command like with :! or :term
  • Restart last task
  • Run shell scripts in the current directory
  • Directory-local tasks with exrc
  • Asynchronous :Make similar to vim-dispatch
  • Asynchronous :Grep command
  • Create a window that displays the most recent task output
• Reference
  • Setup options
  • Commands
  • Highlight groups
  • Lua API
  • Components
  • Strategies
  • Parameters
• Screenshots

<!-- /TOC -->

Features

• Built-in support for many task frameworks (make, npm, cargo, .vscode/tasks.json, etc)
• Simple integration with vim.diagnostic and quickfix
• UI for viewing and managing tasks
• Quick controls for common actions (restart task, rerun on save, or user-defined functions)
• Extreme customizability. Very easy to attach custom logic to tasks
• Define and run complex multi-stage workflows
• Support for preLaunchTask when used with nvim-dap

Requirements

• Neovim 0.11+ (for older versions, use a nvim-0.x branch)

Installation

overseer supports all the usual plugin managers

<details> <summary>lazy.nvim</summary>

{
  'stevearc/overseer.nvim',
  ---@module 'overseer'
  ---@type overseer.SetupOpts
  opts = {},
}

</details> <details> <summary>Packer</summary>

require("packer").startup(function()
  use({
    "stevearc/overseer.nvim",
    config = function()
      require("overseer").setup()
    end,
  })
end)

</details> <details> <summary>Paq</summary>

require("paq")({
  { "stevearc/overseer.nvim" },
})

</details> <details> <summary>vim-plug</summary>

Plug 'stevearc/overseer.nvim'

</details> <details> <summary>dein</summary>

call dein#add('stevearc/overseer.nvim')

</details> <details> <summary>Pathogen</summary>

git clone --depth=1 https://github.com/stevearc/overseer.nvim.git ~/.vim/bundle/

</details> <details> <summary>Neovim native package</summary>

git clone --depth=1 https://github.com/stevearc/overseer.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/overseer/start/overseer.nvim

</details>

Quick start

Add the following to your init.lua

require("overseer").setup()

To get started, all you need to know is :OverseerRun to select and start a task, and :OverseerToggle to open the task list.

https://user-images.githubusercontent.com/506791/189036898-05edcd62-42e7-4bbb-ace2-746b7c8c567b.mp4

If you don't see any tasks from :OverseerRun, it might mean that your task runner is not yet supported. There is currently support for VS Code tasks, make, npm, cargo, and some others.

If you want to define custom tasks for your project, I'd recommend starting with the tutorials.

Tutorials

• Build a C++ file
• Run a file on save

Guides

• Custom tasks
  • Template definition
  • Template providers
• Actions
• Custom components
  • Component aliases
  • Task result
• Task events
• Customizing built-in tasks
• Customizing the task appearance in the task list
• Parsing output
• Running tasks sequentially
• VS Code tasks

Explanation

• Architecture
  • Tasks
  • Components
  • Serializability
  • Templates
• Task list
• Task editor
• Alternatives
• FAQ

Third-party integrations

• Lualine
• Heirline
• Neotest
• DAP
• Session managers
  • resession.nvim
  • Other session managers

Recipes

• Run a quick command like with :! or :term
• Restart last task
• Run shell scripts in the current directory
• Directory-local tasks with exrc
• Asynchronous :Make similar to vim-dispatch
• Asynchronous :Grep command
• Create a window that displays the most recent task output

Reference

• Setup options
• Commands
• Highlight groups
• Lua API
  • setup(opts)
  • new_task(opts)
  • toggle(opts)
  • open(opts)
  • close()
  • list_tasks(opts)
  • run_task(opts, callback)
  • preload_task_cache(opts, cb)
  • clear_task_cache(opts)
  • run_action(task, name)
  • add_template_hook(opts, hook)
  • remove_template_hook(opts, hook)
  • register_template(defn)
  • register_alias(name, components, override)
  • create_task_output_view(winid, opts)
  • overseer.Task
    • Task:serialize()
    • Task:clone()
    • Task:add_component(comp)
    • Task:add_components(components)
    • Task:set_component(comp)
    • Task:set_components(components)
    • Task:get_component(name)
    • Task:remove_component(name)
    • Task:remove_components(names)
    • Task:has_component(name)
    • Task:subscribe(event, callback)
    • Task:unsubscribe(event, callback)
    • Task:is_pending()
    • Task:is_running()
    • Task:is_complete()
    • Task:is_disposed()
    • Task:get_bufnr()
    • Task:open_output(direction)
    • Task:broadcast(name)
    • [Task:dispatch(name)](doc/reference.md#taskdispatchna