From f0315c101ffb32788a349380eb160a702b83c75c Mon Sep 17 00:00:00 2001 From: Steven Arcangeli Date: Sun, 21 Jan 2024 09:34:28 -0800 Subject: [PATCH] doc: document some configuration options (#283) --- README.md | 3 ++- doc/oil.txt | 53 +++++++++++++++++++++++++++++++++++++-------- lua/oil/config.lua | 3 ++- scripts/generate.py | 40 +++++++++++++++++++++++++++++++++- 4 files changed, 87 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 80325cf..2c023fd 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/oil.txt b/doc/oil.txt index 9659d1d..7b04940 100644 --- a/doc/oil.txt +++ b/doc/oil.txt @@ -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({ @@ -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 @@ -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* @@ -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: diff --git a/lua/oil/config.lua b/lua/oil/config.lua index eab0adc..e8fc62b 100644 --- a/lua/oil/config.lua +++ b/lua/oil/config.lua @@ -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 diff --git a/scripts/generate.py b/scripts/generate.py index 114af0b..99c590b 100755 --- a/scripts/generate.py +++ b/scripts/generate.py @@ -164,7 +164,7 @@ COL_DEFS = [ 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'] @@ -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()') @@ -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(),