Skip to content

Commit

Permalink
doc: document some configuration options (#283)
Browse files Browse the repository at this point in the history
  • Loading branch information
@stevearc
stevearc committed Jan 21, 2024
1 parent 0ef49e4 commit f0315c1
Show file tree
Hide file tree
Showing 4 changed files with 87 additions and 12 deletions.
3 changes: 2 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,10 @@ require("oil").setup({
},
-- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
delete_to_trash = false,
-- Skip the confirmation popup for simple operations
-- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
skip_confirm_for_simple_edits = false,
-- Selecting a new/moved/renamed file or directory will prompt you to save changes first
-- (:help prompt_save_on_select_new_entry)
prompt_save_on_select_new_entry = true,
-- Oil will automatically delete hidden buffers after this delay
-- You can set the delay to false to disable cleanup entirely
Expand Down
53 changes: 44 additions & 9 deletions doc/oil.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,16 @@
--------------------------------------------------------------------------------
CONTENTS *oil-contents*

1. Options |oil-options|
2. Api |oil-api|
3. Columns |oil-columns|
4. Actions |oil-actions|
5. Highlights |oil-highlights|
6. Trash |oil-trash|
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|

--------------------------------------------------------------------------------
OPTIONS *oil-options*
CONFIG *oil-config*

>lua
require("oil").setup({
Expand Down Expand Up @@ -44,9 +45,10 @@ OPTIONS *oil-option
},
-- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
delete_to_trash = false,
-- Skip the confirmation popup for simple operations
-- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
skip_confirm_for_simple_edits = false,
-- Selecting a new/moved/renamed file or directory will prompt you to save changes first
-- (:help prompt_save_on_select_new_entry)
prompt_save_on_select_new_entry = true,
-- Oil will automatically delete hidden buffers after this delay
-- You can set the delay to false to disable cleanup entirely
Expand Down Expand Up @@ -160,6 +162,39 @@ OPTIONS *oil-option
})
<

--------------------------------------------------------------------------------
OPTIONS *oil-options*


skip_confirm_for_simple_edits *oil.skip_confirm_for_simple_edits*
type: `boolean` default: `false`
Before performing filesystem operations, Oil displays a confirmation popup to ensure
that all operations are intentional. When this option is `true`, the popup will be
skipped if the operations:
* contain no deletes
* contain no cross-adapter moves or copies (e.g. from local to ssh)
* contain at most one copy or move
* contain at most five creates

prompt_save_on_select_new_entry *oil.prompt_save_on_select_new_entry*
type: `boolean` default: `true`
There are two cases where this option is relevant:
1. You copy a file to a new location, then you select it and make edits before
saving.
2. You copy a directory to a new location, then you enter the directory and make
changes before saving.

In case 1, when you edit the file you are actually editing the original file because
oil has not yet moved/copied it to its new location. This means that the original
file will, perhaps unexpectedly, also be changed by any edits you make.

Case 2 is similar; when you edit the directory you are again actually editing the
original location of the directory. If you add new files, those files will be
created in both the original location and the copied directory.

When this option is `true`, Oil will prompt you to save before entering a file or
directory that is pending within oil, but does not exist on disk.

--------------------------------------------------------------------------------
API *oil-api*

Expand Down Expand Up @@ -515,7 +550,7 @@ Mac:
(instead of being able to see files that were trashed from a directory).

Windows:
Oil supports the Recycle bin. All features should work.
Oil does not yet support the Windows trash. PRs are welcome!

================================================================================
vim:tw=80:ts=2:ft=help:norl:syntax=help:
3 changes: 2 additions & 1 deletion lua/oil/config.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ local default_config = {
},
-- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
delete_to_trash = false,
-- Skip the confirmation popup for simple operations
-- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
skip_confirm_for_simple_edits = false,
-- Selecting a new/moved/renamed file or directory will prompt you to save changes first
-- (:help prompt_save_on_select_new_entry)
prompt_save_on_select_new_entry = true,
-- Oil will automatically delete hidden buffers after this delay
-- You can set the delay to false to disable cleanup entirely
Expand Down
40 changes: 39 additions & 1 deletion scripts/generate.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ class ColumnDef:


def get_options_vimdoc() -> "VimdocSection":
section = VimdocSection("options", "oil-options")
section = VimdocSection("config", "oil-config")
config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
opt_lines = read_section(config_file, r"^local default_config =", r"^}$")
lines = ["\n", ">lua\n", ' require("oil").setup({\n']
Expand All @@ -174,6 +174,43 @@ def get_options_vimdoc() -> "VimdocSection":
return section


def get_options_detail_vimdoc() -> "VimdocSection":
section = VimdocSection("options", "oil-options")
section.body.append(
"""
skip_confirm_for_simple_edits *oil.skip_confirm_for_simple_edits*
type: `boolean` default: `false`
Before performing filesystem operations, Oil displays a confirmation popup to ensure
that all operations are intentional. When this option is `true`, the popup will be
skipped if the operations:
* contain no deletes
* contain no cross-adapter moves or copies (e.g. from local to ssh)
* contain at most one copy or move
* contain at most five creates
prompt_save_on_select_new_entry *oil.prompt_save_on_select_new_entry*
type: `boolean` default: `true`
There are two cases where this option is relevant:
1. You copy a file to a new location, then you select it and make edits before
saving.
2. You copy a directory to a new location, then you enter the directory and make
changes before saving.
In case 1, when you edit the file you are actually editing the original file because
oil has not yet moved/copied it to its new location. This means that the original
file will, perhaps unexpectedly, also be changed by any edits you make.
Case 2 is similar; when you edit the directory you are again actually editing the
original location of the directory. If you add new files, those files will be
created in both the original location and the copied directory.
When this option is `true`, Oil will prompt you to save before entering a file or
directory that is pending within oil, but does not exist on disk.
"""
)
return section


def get_highlights_vimdoc() -> "VimdocSection":
section = VimdocSection("Highlights", "oil-highlights", ["\n"])
highlights = read_nvim_json('require("oil")._get_highlights()')
Expand Down Expand Up @@ -269,6 +306,7 @@ def generate_vimdoc():
doc.sections.extend(
[
get_options_vimdoc(),
get_options_detail_vimdoc(),
VimdocSection("API", "oil-api", render_vimdoc_api("oil", funcs)),
get_columns_vimdoc(),
get_actions_vimdoc(),
Expand Down

0 comments on commit f0315c1

Please sign in to comment.