broot.nvim.txt Broot integration for Neovim.
https://github.com/9999years/broot.nvim
Type gO to see the table of contents.
================================================================================
broot.nvim broot.nvim
broot.nvim is a Broot integration plugin for Neovim. Learn more about Broot
here: https://github.com/Canop/broot
Use broot.nvim by lua-requireing it:
-- Configure `broot.nvim`.
require("broot").setup {
config_files = {
"~/.config/broot/conf.toml",
"~/.config/broot/nvim.toml",
},
-- ...
}
-- Launch `broot`.
require("broot").broot()
================================================================================
Getting started broot-getting-started
To use broot.nvim, you'll need to tell it where your configuration files
are with broot.setup(), and to define an nvim.toml or nvim.hjson file
with something like this:
[[verbs]]
key = "enter"
invocation = "edit"
shortcut = "e"
apply_to = "file"
external = "broot.nvim edit +{line} {file}"
from_shell = true
broot doesn't offer an extension point for opening or selecting a file, so
you'll need to define a verb like this (or multiple verbs for :split and
friends). (See broot-defining-verbs for more details on using broot.nvim
in the external attribute.)
After adding an edit verb or similar, you'll be able to use the :Broot
command or broot.broot() to open broot and edit files.
================================================================================
Defining verbs for Broot broot-defining-verbs
When you define and use a verb with an external execution, Broot writes that
command to the --outcmd file to tell broot.nvim (or, more commonly, your
shell) to execute it.
If the first word (the program) in the --outcmd file is broot.nvim, the
remaining arguments will be executed in Neovim as an ex-command. Separately,
cd commands will be translated into a :cd commands (this makes the cd
verb work), and other commands will be run as :! commands in 'shell'.
================================================================================
Lua interface broot-lua
The broot module contains the broot.setup() and broot.broot() functions.
================================================================================
Configuration broot-configuring
broot.setup(opts: table|nil) broot.setup()
Configure broot.nvim.
Parameters:
opts: table|nil
Configuration options. The following keys are supported, all optional:
broot.config.broot_binary
• `broot_binary: string` The name of the broot binary to launch.
Default: broot.
• `extra_args: string[]` Extra arguments to pass to broot.
broot.config.config_files
• `config_files: string[]` The paths to configuration files to pass to
broot with the --conf argument.
Values are passed to expand() before being stored, so you can use
environment variables and ~ in them.
Default:
• ~/.config/broot/conf.toml
• ~/.config/broot/nvim.toml
broot.config.default_directory
• `default_directory: fun(): string?` broot.broot() calls this
function to determine the directory to launch broot in if the user
doesn't give one explicitly.
Default: vim.fn.getcwd()
If the default_directory function returns luaref-nil, the
current-directory is used instead.
The require("broot.default_directory") module contains a few
useful values for this configuration key:
• git_root returns the Git repository root of the current-file.
• current_file returns the directory of the current-file.
broot.config.create_user_commands
• create_user_commands: (boolean) If true, the :Broot command will
be defined.
================================================================================
Launching Broot broot-launching
broot.broot(opts = {}) broot.broot()
Launch the broot binary in a terminal in a new api-floatwin window.
Parameters:
opts: table
Options for launching broot. The following keys are supported, all
optional:
• `extra_args: string[]` Extra arguments to pass to the broot
binary. These arguments are used in addition to, rather than instead
of, the global broot.config.extra_args.
• `directory: string` The directory to launch broot in.
Note: The directory is set using the cwd of the started process,
rather than being passed as an argument to broot.
Default: broot.config.default_directory
================================================================================
User commands broot-commands
:Broot [directory] :Broot
Open broot in the given directory, or the
broot.config.default_directory if none is given.
The :Broot command only supports choosing the directory to launch
broot in; for other options (like extra_args), use broot.broot()
directly.
The :Broot command is only defined if broot.setup() is called with
`create_user_commands = true`.
vim:tw=80:ts=8:et:ft=help:norl: