From 4faddc352300c7acf5527692ce9bdf378727b006 Mon Sep 17 00:00:00 2001 From: bhagwan Date: Sun, 22 Dec 2024 20:45:33 -0800 Subject: [PATCH] docs: adding my 2 cents regarding the README refactor (#1601) --- README.md | 253 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 192 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index f0d1c3fd..af73a327 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,35 @@ ![Neovim version](https://img.shields.io/badge/Neovim-0.5-57A143?style=flat-square&logo=neovim) -[Installation](#installation) • [Quickstart](#quickstart) • [Commands](#commands) • [Customization](#options) • [Wiki](https://github.com/ibhagwan/fzf-lua/wiki) +[Quickstart](#quickstart) • [Installation](#installation) • [Usage](#usage) • [Commands](#commands) • [Customization](#customization) • [Wiki](https://github.com/ibhagwan/fzf-lua/wiki) ![Demo](https://raw.githubusercontent.com/wiki/ibhagwan/fzf-lua/demo.gif) -> “because you can and you love `fzf`” ([@junegunn](https://github.com/junegunn)) +“because you can and you love fzf” - [@junegunn](https://github.com/junegunn) -> [fzf](https://github.com/junegunn/fzf) is the single most impactful tool for my command line workflow, it changed my life and it can change yours too, if you allow it. +"[fzf](https://github.com/junegunn/fzf) changed my command life, it can change +yours too, if you allow it" - @ibhagwan +## Quickstart + +To quickly test this plugin without changing your configuration run (will run in it's own sandbox +with the default keybinds below): +> [!NOTE] +> it's good practice to first +> [read the script](https://github.com/ibhagwan/fzf-lua/blob/main/scripts/mini.sh) +> before running `sh -c` directly from the web +```sh +sh -c "$(curl -s https://raw.githubusercontent.com/ibhagwan/fzf-lua/main/scripts/mini.sh)" +``` + +| Key | Command | Key | Command | +| ----------| ------------------| ----------| ------------------| +| `` | buffers | `` | files | +| `` | grep | `` | live_grep | +| `` | builtin commands | `` | neovim help | + ## Installation [![LuaRocks](https://img.shields.io/luarocks/v/ibhagwan/fzf-lua?logo=lua&color=purple)](https://luarocks.org/modules/ibhagwan/fzf-lua) @@ -25,10 +44,9 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim) "ibhagwan/fzf-lua", -- optional for icon support dependencies = { "nvim-tree/nvim-web-devicons" }, - config = function() - -- calling `setup` is optional for customization - require("fzf-lua").setup({}) - end + -- or if using mini.icons/mini.nvim + -- dependencies = { "echasnovski/mini.icons" }, + opts = {} } ``` @@ -39,9 +57,9 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim) - [`neovim`](https://github.com/neovim/neovim/releases) version > `0.5.0` - [`fzf`](https://github.com/junegunn/fzf) version > `0.25` - **or** [`skim`](https://github.com/skim-rs/skim) binary installed + or [`skim`](https://github.com/skim-rs/skim) binary installed - [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) - **or** [mini.icons](https://github.com/echasnovski/mini.icons) + or [mini.icons](https://github.com/echasnovski/mini.icons) (optional) ### Optional dependencies @@ -57,9 +75,8 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim) - [nvim-treesitter-context](https://github.com/nvim-treesitter/nvim-treesitter-context) - for viewing treesitter context within the previewer - [render-markdown.nvim](https://github.com/MeanderingProgrammer/render-markdown.nvim) or - [markview.nvim](https://github.com/OXY2DEV/markview.nvim - for rendering markdown + [markview.nvim](https://github.com/OXY2DEV/markview.nvim) - for rendering markdown files in the previewer - ) Below are a few optional dependencies for viewing media files (which you need to configure in `previewer.builtin.extensions`): @@ -87,7 +104,7 @@ to configure in `previewer.builtin.extensions`): -## Quickstart +## Usage Fzf-lua aims to be as plug and play as possible with sane defaults, you can run any fzf-lua command like this: @@ -111,7 +128,7 @@ Choose among the many pickers we offer!!👇 ## Commands
-Browse commands! +Buffers and Files ### Buffers and Files @@ -130,6 +147,10 @@ Choose among the many pickers we offer!!👇 | `tabs` | open tabs | | `args` | argument list | +
+
+Search + ### Search | Command | List | @@ -151,6 +172,10 @@ Choose among the many pickers we offer!!👇 | `live_grep_glob` | live_grep with `rg --glob` support | | `live_grep_native` | performant version of `live_grep` | +
+
+Tags + ### Tags | Command | List | @@ -163,6 +188,10 @@ Choose among the many pickers we offer!!👇 | `tags_grep_visual` | `tags_grep` visual selection | | `tags_live_grep` | live grep project tags | +
+
+Git + ### Git | Command | List | @@ -176,6 +205,10 @@ Choose among the many pickers we offer!!👇 | `git_tags` | git tags | | `git_stash` | git stash | +
+
+LSP / Diagnostics + ### LSP/Diagnostics | Command | List | @@ -197,6 +230,10 @@ Choose among the many pickers we offer!!👇 | `lsp_document_diagnostics` | alias to `diagnostics_document` | | `lsp_workspace_diagnostics` | alias to `diagnostics_workspace` | +
+
+Misc + ### Misc | Command | List | @@ -224,6 +261,10 @@ Choose among the many pickers we offer!!👇 | `spell_suggest` | spelling suggestions | | `packadd` | :packadd | +
+
+Neovim API + ### Neovim API > `:help vim.ui.select` for more info @@ -233,6 +274,10 @@ Choose among the many pickers we offer!!👇 | `register_ui_select` | register fzf-lua as the UI interface for `vim.ui.select` | | `deregister_ui_select` | de-register fzf-lua with `vim.ui.select` | +
+
+nvim-dap + ### nvim-dap > Requires [`nvim-dap`](https://github.com/mfussenegger/nvim-dap) @@ -245,12 +290,20 @@ Choose among the many pickers we offer!!👇 | `dap_variables` | active session variables | | `dap_frames` | active session jump to frame | +
+
+Tmux + ### tmux | Command | List | | -------------- | ----------------------- | | `tmux_buffers` | list tmux paste buffers | +
+
+Completion Functions + ### Completion Functions | Command | List | @@ -261,9 +314,8 @@ Choose among the many pickers we offer!!👇 | `complete_bline` | complete line (current buffer only) |
-
-Resume commands! +Resume Resuming work from where you left off is as easy as: @@ -281,33 +333,48 @@ Alternatively, resuming work on a specific provider: :FzfLua files resume=true ``` +> [!NOTE] +> By default pressing esc or ctrl-c terminates the fzf process, +> as such resume is not perfect and is limited to resuming the +> picker/query and sometimes additional parameters such as regex +> in grep, etc, for a more "complete" resume press alt-esc to +> hide the fzf process instead, this will keep the fzf process +> running in the background and thus will restore the process +> entirely including cursor position and selection. +> To configure hiding by default: +> ```lua +> require("fzf-lua").setup({ keymap = { builtin = { true, [""] = "hide" } } }) +> ``` + +
## Options ```lua -require('fzf-lua').setup{ - fzf_bin = 'sk', -- use skim instead of fzf, or skip it to use fzf - winopts = { - ... - }, - keymap = { - ... - }, - actions = { - ... - }, +require("fzf-lua").setup{ + -- fzf_bin = "sk", -- Uncomment to use skim instead of fzf + winopts = { ... }, -- UI options + keymap = { ... }, -- Window/fzf keybinds, + actions = { ... }, -- "accept" keybinds + fzf_opts = { ... }, -- fzf CLI flags + fzf_colors = { ... }, -- fzf colors + hls = { ... }, -- UI Highlights + previewers = { ... }, -- Previewer(s) options + -- = { ... },-- Picker specific options + -- padding can help kitty term users with double-width icon rendering file_icon_padding = '', -- uncomment if your terminal/font does not support unicode character -- 'EN SPACE' (U+2002), the below sets it to 'NBSP' (U+00A0) instead -- nbsp = '\xc2\xa0', - hls = { - ... - } } ``` -where each of the above sections can be fully configured as below: +Where each of the above sections can be fully configured as below: + +> [!NOTE] +> Refer to [OPTIONS](https://github.com/ibhagwan/fzf-lua/blob/main/OPTIONS.md) +> to see detailed usage notes and a comprehensive list of yet more(!) available options.
winopts @@ -492,6 +559,68 @@ fzf_tmux_opts = { ["-p"] = "80%,80%", ["--margin"] = "0,0" },
+
+fzf_colors + +```lua + -- + -- Set fzf's terminal colorscheme (optional) + -- + -- Set to `true` to automatically generate an fzf's colorscheme from + -- Neovim's current colorscheme: + -- fzf_colors = true, + -- + -- Building a custom colorscheme, has the below specifications: + -- If rhs is of type "string" rhs will be passed raw, e.g.: + -- `["fg"] = "underline"` will be translated to `--color fg:underline` + -- If rhs is of type "table", the following convention is used: + -- [1] "what" field to extract from the hlgroup, i.e "fg", "bg", etc. + -- [2] Neovim highlight group(s), can be either "string" or "table" + -- when type is "table" the first existing highlight group is used + -- [3+] any additional fields are passed raw to fzf's command line args + -- Example of a "fully loaded" color option: + -- `["fg"] = { "fg", { "NonExistentHl", "Comment" }, "underline", "bold" }` + -- Assuming `Comment.fg=#010101` the resulting fzf command line will be: + -- `--color fg:#010101:underline:bold` + -- NOTE: to pass raw arguments `fzf_opts["--color"]` or `fzf_args` + -- NOTE: below is an example, not the defaults: + fzf_colors = { + true, -- inherit fzf colors that aren't specified below from + -- the auto-generated theme similar to `fzf_colors=true` + ["fg"] = { "fg", "CursorLine" }, + ["bg"] = { "bg", "Normal" }, + ["hl"] = { "fg", "Comment" }, + ["fg+"] = { "fg", "Normal", "underline" }, + ["bg+"] = { "bg", { "CursorLine", "Normal" } }, + ["hl+"] = { "fg", "Statement" }, + ["info"] = { "fg", "PreProc" }, + ["prompt"] = { "fg", "Conditional" }, + ["pointer"] = { "fg", "Exception" }, + ["marker"] = { "fg", "Keyword" }, + ["spinner"] = { "fg", "Label" }, + ["header"] = { "fg", "Comment" }, + ["gutter"] = "-1", + }, +``` + +
+ +
+hls + +```lua +hls = { + normal = "..." -- highlight group for normal bg + preview_normal = "..." -- highlight group for preview bg + ... +} +``` + +> [!NOTE] +> See the [highlights](#highlights) section below for all available highlight groups. + +
+
previewers @@ -588,13 +717,10 @@ previewers = {
-providers setups +picker options ```lua - - - -- PROVIDERS SETUP - -- use `defaults` (table or function) if you wish to set "global-provider" defaults + -- use `defaults` (table or function) if you wish to set "global-picker" defaults -- for example, using "mini.icons" globally and open the quickfix list at the top -- defaults = { -- file_icons = "mini", @@ -1101,51 +1227,43 @@ previewers = { -- previewer hidden by default winopts = { preview = { hidden = "hidden" } }, }, + -- uncomment to use fzf native previewers + -- (instead of using a neovim floating window) + -- manpages = { previewer = "man_native" }, + -- helptags = { previewer = "help_native" }, ```
-
-hls +If you wish to customise only specific calls without modifying the global config, you can +be individually sent as inline paramters to the function calls, examples below: -```lua -hls = { - normal = "..." -- highlight group for normal bg - preview_normal = "..." -- highlight group for preview bg - ... -} -``` - -where all the available highlight groups are listed in the [highlights](#highlights) section below. - -
- -If still not enough, check a more comprehensive list of [options](https://github.com/ibhagwan/fzf-lua/blob/main/OPTIONS.md) and detailed usage! - -If you wish to customise only specific calls without changing the general behaviours, you can individually send option parameters inline to the function calls: see the examples below +> [!NOTE] +> Refer to [OPTIONS](https://github.com/ibhagwan/fzf-lua/blob/main/OPTIONS.md) +> for yet more examples.
-Examples of inline customisation +Examples of inline customization -> Different `fzf` layout: +Different `fzf` layout: ```lua :lua require('fzf-lua').files({ fzf_opts = {['--layout'] = 'reverse-list'} }) ``` -> Using `files` with a different command and working directory: +Using `files` with a different command and working directory: ```lua :lua require'fzf-lua'.files({ prompt="LS> ", cmd = "ls", cwd="~/" }) ``` -> Using `live_grep` with `git grep`: +Using `live_grep` with `git grep`: ```lua :lua require'fzf-lua'.live_grep({ cmd = "git grep --line-number --column --color=always" }) ``` -> `colorschemes` with non-default window size: +`colorschemes` with non-default window size: ```lua :lua require'fzf-lua'.colorschemes({ winopts = { height=0.33, width=0.33 } }) @@ -1155,7 +1273,8 @@ If you wish to customise only specific calls without changing the general behavi ### Profiles -Conveniently, fzf-lua comes with a set of preconfigured profiles if you do not want to tinker with customisation: +Conveniently, fzf-lua comes with a set of preconfigured profiles if you do not want to tinker with +customization:
Browse profiles! @@ -1197,13 +1316,24 @@ the first argument: :lua require"fzf-lua".setup({{"telescope","fzf-native"},winopts={fullscreen=true}}) ``` -See [profiles](https://github.com/ibhagwan/fzf-lua/tree/main/lua/fzf-lua/profiles) for more info. +#### Coming from fzf.vim? + +Easy! run `:FzfLua setup_fzfvim_cmds` and use the same familiar commands +used by fzf.vim, i.e. `:Files`, `:Rg`, etc. + +> Using the builtin `fzf-vim` profile will also create fzf.vim's user +> commands, i.e. `require("fzf-lua").setup({ "fzf-vim" })` + +**See [profiles](https://github.com/ibhagwan/fzf-lua/tree/main/lua/fzf-lua/profiles) for more +info.** + ### Extensibility -Fzf-lua can be easily extended and customised for your own needs: have a look at a full list of examples and plugins browsing the 💡[Wiki](https://github.com/ibhagwan/fzf-lua/wiki/Advanced) 💡! +Fzf-lua can be easily extended and customised for your own needs: have a look at a full list of +examples and plugins browsing the 💡[Wiki](https://github.com/ibhagwan/fzf-lua/wiki/Advanced) 💡 -Have you gotten any ideas for new pickers, plugins or extensions? Create a plugin and add it to the wiki! +Have ideas for new pickers, plugins or extensions? Create a plugin and add it to the wiki! ### Advanced completion modes @@ -1350,6 +1480,7 @@ Big thank you to all those I borrowed code/ideas from, I read so many configs and plugin codes that I probably forgot where I found some samples from so if I missed your name feel free to contact me and I'll add it below: ++ [@junegunn](https://github.com/junegunn/) for creating the magical fzf - [@vijaymarupudi](https://github.com/vijaymarupudi/) for his wonderful [nvim-fzf](https://github.com/vijaymarupudi/nvim-fzf) plugin which is at the core of this plugin