bug: Docs for OverseerQuickAction->watch

[raffaem]

Neovim version (nvim -v)

0.10.0

Operating system/version

Arch Linux

Describe the bug

Where can I find the documentation for :OverseerQuickAction -> watch?

I found this function described in the tutorial, but other than that there seems to be no official documentation.

What does interrupt do exactly?

What are the possible mode?

How to make paths default to the current file, not the current directory?

And what task does it restart exactly? Just the last task? The tasks run since the last watch? All the tasks since the buffer was opened?

What is the severity of this bug?

minor (annoyance)

Steps To Reproduce

1. Read the tutorial
2. Look for official documentation

Expected Behavior

watch should be documented

Minimal example file

No response

Minimal init.lua

-- DO NOT change the paths and don't remove the colorscheme
local root = vim.fn.fnamemodify("./.repro", ":p")

-- set stdpaths to use .repro
for _, name in ipairs({ "config", "data", "state", "cache" }) do
  vim.env[("XDG_%s_HOME"):format(name:upper())] = root .. "/" .. name
end

-- bootstrap lazy
local lazypath = root .. "/plugins/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git",
    "clone",
    "--filter=blob:none",
    "--single-branch",
    "https://github.com/folke/lazy.nvim.git",
    lazypath,
  })
end
vim.opt.runtimepath:prepend(lazypath)

-- install plugins
local plugins = {
  "folke/tokyonight.nvim",
  { "stevearc/dressing.nvim", config = true },
  {
    "stevearc/overseer.nvim",
    config = function()
      require("overseer").setup({
        -- add your overseer config here
      })
    end,
  },
  -- add any other plugins here
}
require("lazy").setup(plugins, {
  root = root .. "/plugins",
})

vim.cmd.colorscheme("tokyonight")
-- add anything else here

Additional context

No response

[stevearc]

There's some information in :help overseer-actions, but it directs you to lua/overseer/task_list/actions.lua as the source of truth. From there, you can see that the action is adding the restart_on_save component.

https://github.com/stevearc/overseer.nvim/blob/6271cab7ccc4ca840faa93f54440ffae3a3918bd/lua/overseer/task_list/actions.lua#L92-L93

The docs for that component are either at :help restart_on_save or in components.md.

How to make paths default to the current file, not the current directory?

There is currently no way to customize built-in actions. You would need to define your own action that passes in the current file instead of the cwd on this line

https://github.com/stevearc/overseer.nvim/blob/6271cab7ccc4ca840faa93f54440ffae3a3918bd/lua/overseer/task_list/actions.lua#L87

And what task does it restart exactly? Just the last task? The tasks run since the last watch? All the tasks since the buffer was opened?

It will restart the task that you ran the "watch" action on, because that is the task that will get the restart_on_save component added to it.