Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(help): clean up formatting #403

Merged
merged 1 commit into from
Sep 21, 2024
Merged

docs(help): clean up formatting #403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 46 additions & 37 deletions doc/telescope-file-browser.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,6 @@ The `file_browser` picker comes pre-configured with several keymaps:
• `<C-s>/s`: Toggle all entries ignoring `./` and `../`
• `<bs>/` : Goes to parent dir if prompt is empty, otherwise acts normally


The file browser picker can be configured with the following options:

*telescope-file-browser.PickerOpts*
Expand Down Expand Up @@ -232,11 +231,11 @@ fb_actions.create({prompt_bufnr})
• Finder:
• file_browser: create a file in the currently opened directory
• folder_browser: create a file in the currently selected directory
• Notes:
• You can create folders by ending the name in the path separator of
your OS, e.g. "/" on Unix systems
• You can implicitly create new folders by passing
$/CWD/new_folder/filename.lua

Note: ~
• You can create folders by ending the name in the path separator of your OS,
e.g. "/" on Unix systems
• You can implicitly create new folders by passing $/CWD/new_folder/filename.lua

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand All @@ -245,11 +244,11 @@ fb_actions.create({prompt_bufnr})
fb_actions.create_from_prompt({prompt_bufnr})
Creates a new file or dir via prompt in the current directory of the
|telescope-file-browser.picker.file_browser|.
• Notes:
• You can create folders by ending the name in the path separator of
your OS, e.g. "/" on Unix systems
• You can implicitly create new folders by passing
$/CWD/new_folder/filename.lua

Note: ~
• You can create folders by ending the name in the path separator of your OS,
e.g. "/" on Unix systems
• You can implicitly create new folders by passing $/CWD/new_folder/filename.lua

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand All @@ -258,23 +257,23 @@ fb_actions.create_from_prompt({prompt_bufnr})
fb_actions.rename({prompt_bufnr})
Rename files or folders for |telescope-file-browser.picker.file_browser|.

Notes:
• Triggering renaming with multi selections opens `Batch Rename` window in
which the user can rename/move files multi-selected files at once
• In `Batch Rename`, the number of paths must persist: keeping a file name
means keeping the line unchanged
Note: ~
• Triggering renaming with multi selections opens `Batch Rename` window
• in which the user can rename/move files multi-selected files at once
• In `Batch Rename`, the number of paths must persist: keeping a file name means
keeping the line unchanged

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr

fb_actions.move({prompt_bufnr}) *telescope-file-browser.actions.move()*
Move multi-selected files or folders to current directory in
|telescope-file-browser.picker.file_browser|.
• Notes:

Note: ~
• Performs a blocking synchronized file-system operation.
• Moving multi-selections is sensitive to order of selection, which
potentially unpacks files from parent(s) dirs if files are selected
first.
• Moving multi-selections is sensitive to order of selection, which potentially
unpacks files from parent(s) dirs if files are selected first.

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand All @@ -296,7 +295,8 @@ fb_actions.remove({prompt_bufnr})
Remove file or folders recursively for
|telescope-file-browser.picker.file_browser|.

Note: Performs a blocking synchronized file-system operation.
Note: ~
• Performs a blocking synchronized file-system operation.

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand All @@ -318,14 +318,15 @@ fb_actions.toggle_respect_gitignore({prompt_bufnr})

fb_actions.open() *telescope-file-browser.actions.open()*
Opens the file or folder with the default application.
• Notes:

Note: ~
• map fb_actions.open + fb_actions.close if you want to close the picker
post-action
• OS: make sure your OS links against the desired applications:
• Linux: induces application via `xdg-open`
• macOS: relies on `open` to start the program
• Windows: defaults to default applications through `start` @pram
prompt_bufnr number: The prompt bufnr
• make sure your OS links against the desired applications:
• Linux: induces application via `xdg-open`
• macOS: relies on `open` to start the program
• Windows: defaults to default applications through `start` ram
prompt_bufnr number: The prompt bufnr

*telescope-file-browser.actions.goto_parent_dir()*
fb_actions.goto_parent_dir({prompt_bufnr}, {bypass})
Expand Down Expand Up @@ -371,8 +372,10 @@ fb_actions.toggle_browser({prompt_bufnr})
fb_actions.toggle_all({prompt_bufnr})
Toggles all selections akin to |telescope.actions.toggle_all| but ignores
parent & current directory
• Note: if the parent or current directory were selected, they will be
ignored (manually unselect with `<TAB>`)

Note: ~
• if the parent or current directory were selected, they will be ignored
(manually unselect with `<TAB>`)

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand All @@ -381,27 +384,31 @@ fb_actions.toggle_all({prompt_bufnr})
fb_actions.select_all({prompt_bufnr})
Multi select all entries akin to |telescope.actions.select_all| but
ignores parent & current directory
• Note:

Note: ~
• selected entries may include results not visible in the results popup.
• if the parent or current directly was previously selected, they will
be ignored in the selected state (manually unselect with `<TAB>`)
• if the parent or current directly was previously selected, they will be
ignored in the selected state (manually unselect with `<TAB>`)

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr

*telescope-file-browser.actions.sort_by_size()*
fb_actions.sort_by_size({prompt_bufnr})
Toggle sorting by size of the entry.
Note: initially sorts descendingly in size.

Note: ~
• initially sorts descendingly in size.

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr

*telescope-file-browser.actions.sort_by_date()*
fb_actions.sort_by_date({prompt_bufnr})
Toggle sorting by last change to the entry.
Note: initially sorts desendingly from most to least recently changed
entry.

Note: ~
• initially sorts desendingly from most to least recently changed entry.

Parameters: ~
• {prompt_bufnr} (`number`) The prompt bufnr
Expand Down Expand Up @@ -447,7 +454,8 @@ The file browser finders power the picker with both a file and folder browser.
*telescope-file-browser.finders.browse_files()*
fb_finders.browse_files({opts})
Returns a finder that is populated with files and folders in `path`.
• Notes:

Note: ~
• Uses `fd` if available for more async-ish browsing and speed-ups

Parameters: ~
Expand All @@ -457,7 +465,8 @@ fb_finders.browse_files({opts})
*telescope-file-browser.finders.browse_folders()*
fb_finders.browse_folders({opts})
Returns a finder that is populated with (sub-)folders of `cwd`.
• Notes:

Note: ~
• Uses `fd` if available for more async-ish browsing and speed-ups

Parameters: ~
Expand Down
57 changes: 25 additions & 32 deletions lua/telescope/_extensions/file_browser/actions.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,11 +137,10 @@ end

--- Creates a new file or dir in the current directory of the |telescope-file-browser.picker.file_browser|.
--- - Finder:
--- - file_browser: create a file in the currently opened directory
--- - folder_browser: create a file in the currently selected directory
--- - Notes:
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
--- - file_browser: create a file in the currently opened directory
--- - folder_browser: create a file in the currently selected directory
---@note You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
---@note You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
---@param prompt_bufnr number: The prompt bufnr
fb_actions.create = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand All @@ -162,9 +161,8 @@ fb_actions.create = function(prompt_bufnr)
end

--- Creates a new file or dir via prompt in the current directory of the |telescope-file-browser.picker.file_browser|.
--- - Notes:
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
---@note You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
---@note You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
---@param prompt_bufnr number: The prompt bufnr
fb_actions.create_from_prompt = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -278,10 +276,9 @@ end

--- Rename files or folders for |telescope-file-browser.picker.file_browser|.
---
--- Notes:
--- - Triggering renaming with multi selections opens `Batch Rename` window
--- in which the user can rename/move files multi-selected files at once
--- - In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged
---@note Triggering renaming with multi selections opens `Batch Rename` window
---@note in which the user can rename/move files multi-selected files at once
---@note In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged
---@param prompt_bufnr number: The prompt bufnr
fb_actions.rename = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -345,11 +342,9 @@ end

--- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|.
---
--- - Notes:
--- - Performs a blocking synchronized file-system operation.
--- - Moving multi-selections is sensitive to order of selection,
--- which potentially unpacks files from parent(s) dirs
--- if files are selected first.
---@note Performs a blocking synchronized file-system operation.
---@note Moving multi-selections is sensitive to order of selection, which
--- potentially unpacks files from parent(s) dirs if files are selected first.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.move = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -403,8 +398,8 @@ end
--- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|.
---
--- - Finder:
--- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
--- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
--- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
--- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
---@param prompt_bufnr number: The prompt bufnr
fb_actions.copy = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -500,7 +495,7 @@ end

--- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|.
---
--- Note: Performs a blocking synchronized file-system operation.
---@note Performs a blocking synchronized file-system operation.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.remove = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -601,12 +596,11 @@ end

--- Opens the file or folder with the default application.
---
--- - Notes:
--- - map fb_actions.open + fb_actions.close if you want to close the picker post-action
--- - OS: make sure your OS links against the desired applications:
--- - Linux: induces application via `xdg-open`
--- - macOS: relies on `open` to start the program
--- - Windows: defaults to default applications through `start`
---@note map fb_actions.open + fb_actions.close if you want to close the picker post-action
---@note make sure your OS links against the desired applications:
--- - Linux: induces application via `xdg-open`
--- - macOS: relies on `open` to start the program
--- - Windows: defaults to default applications through `start`
---@pram prompt_bufnr number: The prompt bufnr
fb_actions.open = function(prompt_bufnr)
local quiet = action_state.get_current_picker(prompt_bufnr).finder.quiet
Expand Down Expand Up @@ -720,7 +714,7 @@ fb_actions.toggle_browser = function(prompt_bufnr, opts)
end

--- Toggles all selections akin to |telescope.actions.toggle_all| but ignores parent & current directory
--- - Note: if the parent or current directory were selected, they will be ignored (manually unselect with `<TAB>`)
---@note if the parent or current directory were selected, they will be ignored (manually unselect with `<TAB>`)
---@param prompt_bufnr number: The prompt bufnr
fb_actions.toggle_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand All @@ -742,9 +736,8 @@ fb_actions.toggle_all = function(prompt_bufnr)
end

--- Multi select all entries akin to |telescope.actions.select_all| but ignores parent & current directory
--- - Note:
--- - selected entries may include results not visible in the results popup.
--- - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
---@note selected entries may include results not visible in the results popup.
---@note if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
---@param prompt_bufnr number: The prompt bufnr
fb_actions.select_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
Expand Down Expand Up @@ -789,7 +782,7 @@ local sort_by = function(prompt_bufnr, sorter_fn)
end

--- Toggle sorting by size of the entry.<br>
--- Note: initially sorts descendingly in size.
---@note initially sorts descendingly in size.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.sort_by_size = function(prompt_bufnr)
local finder = action_state.get_current_picker(prompt_bufnr).finder
Expand All @@ -813,7 +806,7 @@ fb_actions.sort_by_size = function(prompt_bufnr)
end

--- Toggle sorting by last change to the entry.<br>
--- Note: initially sorts desendingly from most to least recently changed entry.
---@note initially sorts desendingly from most to least recently changed entry.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.sort_by_date = function(prompt_bufnr)
local finder = action_state.get_current_picker(prompt_bufnr).finder
Expand Down
6 changes: 2 additions & 4 deletions lua/telescope/_extensions/file_browser/finders.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,7 @@ local function git_args()
end

--- Returns a finder that is populated with files and folders in `path`.
--- - Notes:
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@note Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
fb_finders.browse_files = function(opts)
opts = opts or {}
Expand Down Expand Up @@ -136,8 +135,7 @@ fb_finders.browse_files = function(opts)
end

--- Returns a finder that is populated with (sub-)folders of `cwd`.
--- - Notes:
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@note Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
fb_finders.browse_folders = function(opts)
opts = opts or {}
Expand Down
12 changes: 6 additions & 6 deletions lua/telescope/_extensions/file_browser/picker.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
--- - `<bs>/` : Goes to parent dir if prompt is empty, otherwise acts normally
---
---
--- <br>The file browser picker can be configured with the following options:
--- The file browser picker can be configured with the following options:

local pickers = require "telescope.pickers"
local conf = require("telescope.config").values
Expand Down Expand Up @@ -103,11 +103,11 @@ local fb_picker = {}
---
--- Notes:
--- - display_stat:
--- - A table that can currently hold `date` and/or `size` as keys -- order matters!
--- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
--- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
--- - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }`
--- - See make_entry.lua for an example on how to further customize
--- - A table that can currently hold `date` and/or `size` as keys -- order matters!
--- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
--- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
--- - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }`
--- - See make_entry.lua for an example on how to further customize
---@class telescope-file-browser.PickerOpts : telescope.picker.opts
---@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
---@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
Expand Down
Loading