docs: centralize documentation into helpdoc (#15)
* docs: centralize documentation into helpdoc Problem: documentation was spread across four files (README.md, doc/oil.txt, doc/api.md, doc/recipes.md) with duplication and gaps. User events were undocumented, and adapter docs only lived in the README. Solution: expand doc/oil.txt with five new sections (introduction, requirements, adapters, recipes, events) from existing content. Trim README to a landing page pointing to :help oil. Delete doc/api.md and doc/recipes.md since their content now lives in the helpdoc. Closes: barrettruth/oil.nvim#6 * build: remove docgen pipeline Problem: the Python docgen pipeline (scripts/generate.py, scripts/main.py, nvim_doc_tools) was designed for upstream's doc layout and is incompatible with the centralized helpdoc structure. It overwrites doc/oil.txt entirely and expects sections in README.md that no longer exist. Solution: delete the pipeline scripts (generate.py, main.py, requirements.txt), remove the update_docs CI job, and clean up the Makefile and .gitignore references. Linting and typechecking remain unchanged.
This commit is contained in:
Barrett Ruth
GitHub
parent
1712b6feb3
commit
3b930636e3
10 changed files with 363 additions and 1361 deletions
356
doc/oil.txt
356
doc/oil.txt
|
|
@ -3,13 +3,47 @@
|
|||
--------------------------------------------------------------------------------
|
||||
CONTENTS *oil-contents*
|
||||
|
||||
1. Config |oil-config|
|
||||
2. Options |oil-options|
|
||||
3. Api |oil-api|
|
||||
4. Columns |oil-columns|
|
||||
5. Actions |oil-actions|
|
||||
6. Highlights |oil-highlights|
|
||||
7. Trash |oil-trash|
|
||||
1. Introduction |oil-introduction|
|
||||
2. Requirements |oil-requirements|
|
||||
3. Config |oil-config|
|
||||
4. Options |oil-options|
|
||||
5. Api |oil-api|
|
||||
6. Columns |oil-columns|
|
||||
7. Actions |oil-actions|
|
||||
8. Highlights |oil-highlights|
|
||||
9. Adapters |oil-adapters|
|
||||
10. Recipes |oil-recipes|
|
||||
11. Events |oil-events|
|
||||
12. Trash |oil-trash|
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
INTRODUCTION *oil-introduction*
|
||||
|
||||
oil.nvim is a file explorer for Neovim in the style of vim-vinegar. It lets
|
||||
you edit your filesystem like a normal buffer: create files and directories by
|
||||
typing new lines, delete them by removing lines, rename or move them by
|
||||
changing the text. When you save the buffer, oil diffs it against the original
|
||||
listing and performs the corresponding filesystem operations.
|
||||
|
||||
Open a directory with `nvim .`, `:edit <path>`, or `:Oil <path>`. Use `<CR>`
|
||||
to open a file or descend into a directory, and `-` to go up. Treat the
|
||||
listing like any other buffer — edit freely, then `:w` to apply changes.
|
||||
|
||||
To open oil in a floating window, use `:Oil --float <path>`.
|
||||
|
||||
To mimic vim-vinegar's parent-directory keymap: >lua
|
||||
vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })
|
||||
<
|
||||
|
||||
File operations work across adapters. You can copy files between your local
|
||||
machine and a remote server over SSH, or between local directories and S3
|
||||
buckets, using the same buffer-editing workflow.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
REQUIREMENTS *oil-requirements*
|
||||
|
||||
- Neovim 0.8+
|
||||
- (optional) mini.icons or nvim-web-devicons for file icons
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
CONFIG *oil-config*
|
||||
|
|
@ -766,6 +800,314 @@ OilTrash *hl-OilTras
|
|||
OilTrashSourcePath *hl-OilTrashSourcePath*
|
||||
Virtual text that shows the original path of file in the trash
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
ADAPTERS *oil-adapters*
|
||||
|
||||
Oil performs all filesystem interaction through an adapter abstraction. This
|
||||
means oil can view and modify files in places beyond the local filesystem, as
|
||||
long as the destination has an adapter implementation. File operations work
|
||||
across adapters — you can copy files between local and remote with the same
|
||||
buffer-editing workflow.
|
||||
|
||||
SSH *oil-adapter-ssh*
|
||||
|
||||
Browse files over SSH, much like netrw. Open a buffer with: >
|
||||
nvim oil-ssh://[username@]hostname[:port]/[path]
|
||||
<
|
||||
This is the same URL format that netrw uses.
|
||||
|
||||
The SSH adapter does not support Windows machines, and it requires the
|
||||
server to have `/bin/sh` as well as standard unix commands (`ls`, `rm`,
|
||||
`mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln`, `echo`).
|
||||
|
||||
S3 *oil-adapter-s3*
|
||||
|
||||
Browse files stored in AWS S3. Make sure `aws` is configured correctly,
|
||||
then open a buffer with: >
|
||||
nvim oil-s3://[bucket]/[path]
|
||||
<
|
||||
Older versions of Neovim (0.11 and earlier) don't support numbers in the
|
||||
URL scheme, so use `oil-sss` instead of `oil-s3`.
|
||||
|
||||
Trash *oil-adapter-trash*
|
||||
|
||||
See |oil-trash| for details on the built-in trash adapter.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
RECIPES *oil-recipes*
|
||||
|
||||
Toggle file detail view ~
|
||||
*oil-recipe-toggle-detail-view*
|
||||
>lua
|
||||
local detail = false
|
||||
require("oil").setup({
|
||||
keymaps = {
|
||||
["gd"] = {
|
||||
desc = "Toggle file detail view",
|
||||
callback = function()
|
||||
detail = not detail
|
||||
if detail then
|
||||
require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
|
||||
else
|
||||
require("oil").set_columns({ "icon" })
|
||||
end
|
||||
end,
|
||||
},
|
||||
},
|
||||
})
|
||||
<
|
||||
|
||||
Show CWD in the winbar ~
|
||||
*oil-recipe-cwd-winbar*
|
||||
>lua
|
||||
function _G.get_oil_winbar()
|
||||
local bufnr = vim.api.nvim_win_get_buf(vim.g.statusline_winid)
|
||||
local dir = require("oil").get_current_dir(bufnr)
|
||||
if dir then
|
||||
return vim.fn.fnamemodify(dir, ":~")
|
||||
else
|
||||
return vim.api.nvim_buf_get_name(0)
|
||||
end
|
||||
end
|
||||
|
||||
require("oil").setup({
|
||||
win_options = {
|
||||
winbar = "%!v:lua.get_oil_winbar()",
|
||||
},
|
||||
})
|
||||
<
|
||||
|
||||
Hide gitignored files and show git tracked hidden files ~
|
||||
*oil-recipe-git-is-hidden*
|
||||
>lua
|
||||
local function parse_output(proc)
|
||||
local result = proc:wait()
|
||||
local ret = {}
|
||||
if result.code == 0 then
|
||||
for line in vim.gsplit(result.stdout, "\n", { plain = true, trimempty = true }) do
|
||||
line = line:gsub("/$", "")
|
||||
ret[line] = true
|
||||
end
|
||||
end
|
||||
return ret
|
||||
end
|
||||
|
||||
local function new_git_status()
|
||||
return setmetatable({}, {
|
||||
__index = function(self, key)
|
||||
local ignore_proc = vim.system(
|
||||
{ "git", "ls-files", "--ignored", "--exclude-standard", "--others", "--directory" },
|
||||
{
|
||||
cwd = key,
|
||||
text = true,
|
||||
}
|
||||
)
|
||||
local tracked_proc = vim.system({ "git", "ls-tree", "HEAD", "--name-only" }, {
|
||||
cwd = key,
|
||||
text = true,
|
||||
})
|
||||
local ret = {
|
||||
ignored = parse_output(ignore_proc),
|
||||
tracked = parse_output(tracked_proc),
|
||||
}
|
||||
|
||||
rawset(self, key, ret)
|
||||
return ret
|
||||
end,
|
||||
})
|
||||
end
|
||||
local git_status = new_git_status()
|
||||
|
||||
local refresh = require("oil.actions").refresh
|
||||
local orig_refresh = refresh.callback
|
||||
refresh.callback = function(...)
|
||||
git_status = new_git_status()
|
||||
orig_refresh(...)
|
||||
end
|
||||
|
||||
require("oil").setup({
|
||||
view_options = {
|
||||
is_hidden_file = function(name, bufnr)
|
||||
local dir = require("oil").get_current_dir(bufnr)
|
||||
local is_dotfile = vim.startswith(name, ".") and name ~= ".."
|
||||
if not dir then
|
||||
return is_dotfile
|
||||
end
|
||||
if is_dotfile then
|
||||
return not git_status[dir].tracked[name]
|
||||
else
|
||||
return git_status[dir].ignored[name]
|
||||
end
|
||||
end,
|
||||
},
|
||||
})
|
||||
<
|
||||
|
||||
Open Telescope file finder in the current oil directory ~
|
||||
*oil-recipe-telescope*
|
||||
|
||||
When using `get_current_dir()` in a keymap that also opens another plugin's UI
|
||||
(like Telescope), capture the directory in a local variable before the call
|
||||
that changes the buffer context.
|
||||
>lua
|
||||
require("oil").setup({
|
||||
keymaps = {
|
||||
["<leader>ff"] = {
|
||||
desc = "Find files in the current directory",
|
||||
callback = function()
|
||||
local dir = require("oil").get_current_dir()
|
||||
if not dir then
|
||||
vim.notify("Could not get oil directory", vim.log.levels.WARN)
|
||||
return
|
||||
end
|
||||
require("telescope.builtin").find_files({ cwd = dir })
|
||||
end,
|
||||
},
|
||||
["<leader>fg"] = {
|
||||
desc = "Live grep in the current directory",
|
||||
callback = function()
|
||||
local dir = require("oil").get_current_dir()
|
||||
if not dir then
|
||||
vim.notify("Could not get oil directory", vim.log.levels.WARN)
|
||||
return
|
||||
end
|
||||
require("telescope.builtin").live_grep({ cwd = dir })
|
||||
end,
|
||||
},
|
||||
},
|
||||
})
|
||||
<
|
||||
|
||||
If you need the directory after an operation that might change the current
|
||||
buffer, pass the buffer number explicitly: >lua
|
||||
local bufnr = vim.api.nvim_get_current_buf()
|
||||
-- ... some operation that changes the current buffer ...
|
||||
local dir = require("oil").get_current_dir(bufnr)
|
||||
<
|
||||
|
||||
Add custom column for file extension ~
|
||||
*oil-recipe-extension-column*
|
||||
>lua
|
||||
local oil_cfg = require "oil.config"
|
||||
local oil_constant = require "oil.constants"
|
||||
local oil_column = require "oil.columns"
|
||||
|
||||
local FIELD_TYPE = oil_constant.FIELD_TYPE
|
||||
local FIELD_NAME = oil_constant.FIELD_NAME
|
||||
|
||||
local function adjust_number(int)
|
||||
return string.format("%03d%s", #int, int)
|
||||
end
|
||||
|
||||
local function format(output)
|
||||
return vim.fn.fnamemodify(output, ":e")
|
||||
end
|
||||
|
||||
oil_column.register("extension", {
|
||||
render = function(entry, _)
|
||||
local field_type = entry[FIELD_TYPE]
|
||||
local name = entry[FIELD_NAME]
|
||||
|
||||
if field_type == "file" then
|
||||
if name then
|
||||
local extension = format(name)
|
||||
|
||||
if not extension:match "%s" then
|
||||
return extension
|
||||
end
|
||||
end
|
||||
end
|
||||
end,
|
||||
parse = function(line, _)
|
||||
return line:match "^(%S+)%s+(.*)$"
|
||||
end,
|
||||
create_sort_value_factory = function(num_entries)
|
||||
if
|
||||
oil_cfg.view_options.natural_order == false
|
||||
or (oil_cfg.view_options.natural_order == "fast" and num_entries > 5000)
|
||||
then
|
||||
return function(entry)
|
||||
return format(entry[FIELD_NAME]:lower())
|
||||
end
|
||||
else
|
||||
local memo = {}
|
||||
|
||||
return function(entry)
|
||||
if memo[entry] == nil and entry[FIELD_TYPE] == "file" then
|
||||
local name = entry[FIELD_NAME]:gsub("0*(%d+)", adjust_number)
|
||||
|
||||
memo[entry] = format(name:lower())
|
||||
end
|
||||
|
||||
return memo[entry]
|
||||
end
|
||||
end
|
||||
end,
|
||||
})
|
||||
|
||||
require("oil").setup({
|
||||
columns = {
|
||||
"size",
|
||||
"extension",
|
||||
"icon",
|
||||
},
|
||||
view_options = {
|
||||
sort = {
|
||||
{ "type", "asc" },
|
||||
{ "extension", "asc" },
|
||||
{ "name", "asc" },
|
||||
},
|
||||
},
|
||||
})
|
||||
<
|
||||
|
||||
Disable dimming of hidden files ~
|
||||
*oil-recipe-no-hidden-dimming*
|
||||
|
||||
By default, hidden files (toggled with `g.`) are dimmed via the `OilHidden`
|
||||
highlight group, which links to `Comment`. To make hidden files look identical
|
||||
to their visible counterparts, relink each hidden group to its non-hidden
|
||||
variant after calling `setup()`:
|
||||
>lua
|
||||
for _, hl in ipairs(require("oil")._get_highlights()) do
|
||||
local base = hl.name:match("^(Oil.+)Hidden$")
|
||||
if base then
|
||||
vim.api.nvim_set_hl(0, hl.name, { link = base })
|
||||
end
|
||||
end
|
||||
<
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
EVENTS *oil-events*
|
||||
|
||||
Oil emits the following |User| autocmd events. Listen for them with
|
||||
|nvim_create_autocmd|: >lua
|
||||
vim.api.nvim_create_autocmd("User", {
|
||||
pattern = "OilEnter",
|
||||
callback = function(args)
|
||||
vim.print("Entered oil buffer: " .. args.data.buf)
|
||||
end,
|
||||
})
|
||||
<
|
||||
|
||||
OilEnter *OilEnter*
|
||||
Fired once per oil buffer, after the initial directory listing has been
|
||||
rendered and the buffer is ready. The `args.data.buf` field contains the
|
||||
buffer number. Use this event for one-time buffer setup such as setting
|
||||
keymaps or window options.
|
||||
|
||||
OilReadPost *OilReadPost*
|
||||
Fired after every successful buffer render, including the initial render
|
||||
and all subsequent re-renders (e.g. after directory changes, refreshes, or
|
||||
mutations). The `args.data.buf` field contains the buffer number. Use this
|
||||
event for logic that must run each time the directory listing updates.
|
||||
|
||||
OilMutationComplete *OilMutationComplete*
|
||||
Fired after all pending mutations (create, delete, rename, move, copy)
|
||||
have been executed and the affected buffers have been re-rendered. No
|
||||
additional data fields. Use this event for post-mutation side effects such
|
||||
as refreshing external status indicators.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
TRASH *oil-trash*
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue