retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-fuzzy.txt

@@ -0,0 +1,160 @@
+*mini.fuzzy* Fuzzy matching
+
+MIT License Copyright (c) 2021 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                     *MiniFuzzy*
+Features:
+- Minimal and fast fuzzy matching algorithm which prioritizes match width.
+
+- Functions to for common fuzzy matching operations:
+    - |MiniFuzzy.match()|.
+    - |MiniFuzzy.filtersort()|.
+    - |MiniFuzzy.process_lsp_items()|.
+
+- Generator of sorter (|MiniFuzzy.get_telescope_sorter()|) for
+  [nvim-telescope/telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
+
+# Setup ~
+
+This module doesn't need setup, but it can be done to improve usability.
+Setup with `require('mini.fuzzy').setup({})` (replace `{}` with your
+`config` table). It will create global Lua table `MiniFuzzy` which you can
+use for scripting or manually (with `:lua MiniFuzzy.*`).
+
+See |MiniFuzzy.config| for `config` structure and default values.
+
+You can override runtime config settings locally to buffer inside
+`vim.b.minifuzzy_config` which should have same structure as
+`MiniFuzzy.config`.
+See |mini.nvim-buffer-local-config| for more details.
+
+# Notes ~
+
+1. Currently there is no explicit design to work with multibyte symbols,
+   but simple examples should work.
+2. Smart case is used: case insensitive if input word (which is usually a
+   user input) is all lower case. Case sensitive otherwise.
+
+------------------------------------------------------------------------------
+                                                           *MiniFuzzy-algorithm*
+General design uses only width of found match and index of first letter
+match. No special characters or positions (like in fzy and fzf) are used.
+
+Given non-empty input `word` and target `candidate`:
+- The goal is to find matching between letters in `word` and letters in
+  `candidate` which minimizes certain score. It is assumed that order of
+  letters in `word` and those matched in `candidate` should be the same.
+
+- Matching is represented by matched positions: an array `positions` of
+  integers with length equal to number of letters in `word`. The following
+  should be always true in case of a match: `candidate` letter at index
+  `positions[i]` is `letters[i]` for all valid `i`.
+
+- Matched positions are evaluated based only on two features: their width
+  (number of indexes between first and last positions) and first match
+  (index of first letter match). There is a global setting `cutoff` for
+  which all feature values greater than it can be considered "equally bad".
+
+- Score of matched positions is computed with following explicit formula:
+  `cutoff * min(width, cutoff) + min(first, cutoff)`. It is designed to be
+  equivalent to first comparing widths (lower is better) and then comparing
+  first match (lower is better). For example, if `word = 'time'`:
+    - `_time` (width 4) will have a better match than `t_ime` (width 5).
+    - `time_a` (width 4, first 1) will have a better match than `a_time`
+      (width 4, first 3).
+
+- Final matched positions are those which minimize score among all possible
+  matched positions of `word` and `candidate`.
+
+------------------------------------------------------------------------------
+                                                             *MiniFuzzy.setup()*
+                          `MiniFuzzy.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniFuzzy.config|.
+
+Usage ~
+>lua
+  require('mini.fuzzy').setup() -- use default config
+  -- OR
+  require('mini.fuzzy').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                              *MiniFuzzy.config*
+                               `MiniFuzzy.config`
+Defaults ~
+>lua
+  MiniFuzzy.config = {
+    -- Maximum allowed value of match features (width and first match). All
+    -- feature values greater than cutoff can be considered "equally bad".
+    cutoff = 100,
+  }
+<
+------------------------------------------------------------------------------
+                                                             *MiniFuzzy.match()*
+                     `MiniFuzzy.match`({word}, {candidate})
+Compute match data
+
+Parameters ~
+{word} `(string)` Input word (usually user input).
+{candidate} `(string)` Target word (usually with which matching is done).
+
+Return ~
+`(table)` Matching information:
+  - <positions> `(table|nil)` - array with letter indexes inside `candidate`
+    which matched to corresponding letters in `word`. It is empty array if
+    `word` is empty string and `nil` if no match.
+  - <score> `number` - positive number representing how good the match is
+    (lower is better). It is `-1` if no match or word is empty string.
+
+------------------------------------------------------------------------------
+                                                        *MiniFuzzy.filtersort()*
+               `MiniFuzzy.filtersort`({word}, {candidate_array})
+Filter string array
+
+- Keep only input elements which match `word`.
+- Sort from best to worst matches (based on score and index in original
+  array, both lower is better).
+
+Parameters ~
+{word} `(string)` String which will be searched.
+{candidate_array} `(table)` Lua array of strings inside which word will be
+  searched.
+
+Return ~
+`(...)` Arrays of matched candidates and their indexes in original input.
+
+------------------------------------------------------------------------------
+                                                 *MiniFuzzy.process_lsp_items()*
+                 `MiniFuzzy.process_lsp_items`({items}, {base})
+Fuzzy matching for `lsp_completion.process_items` of |MiniCompletion.config|
+
+Parameters ~
+{items} `(table)` Array with LSP `'textDocument/completion'` response items.
+{base} `(string)` Word to complete.
+
+Return ~
+`(table)` Array of items with text (`filterText` or `label`) fuzzy matching `base`.
+
+------------------------------------------------------------------------------
+                                              *MiniFuzzy.get_telescope_sorter()*
+                    `MiniFuzzy.get_telescope_sorter`({opts})
+Custom getter for `telescope.nvim` sorter
+
+Designed as a value for file and generic sorter of `telescope.nvim`.
+
+Parameters ~
+{opts} `(table|nil)` Options (currently not used).
+
+Usage ~
+>lua
+  require('telescope').setup({
+    defaults = {
+      generic_sorter = require('mini.fuzzy').get_telescope_sorter
+    }
+  })
+<
+
+ vim:tw=78:ts=8:noet:ft=help:norl:

package/nvim/plugins/mini.nvim/doc/mini-git.txt

@@ -0,0 +1,425 @@
+*mini.git* Git integration
+
+MIT License Copyright (c) 2024 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                       *MiniGit*
+Features:
+
+- Automated tracking of Git related data: root path, status, HEAD, etc.
+  Exposes buffer-local variables for convenient use in statusline.
+  See |MiniGit.enable()| and |MiniGit.get_buf_data()| for more information.
+
+- |:Git| command for executing any `git` call inside file's repository root with
+  deeper current instance integration (show output as notification/buffer,
+  use to edit commit messages, etc.).
+
+- Helper functions to inspect Git history:
+    - |MiniGit.show_range_history()| shows how certain line range evolved.
+    - |MiniGit.show_diff_source()| shows file state as it was at diff entry.
+    - |MiniGit.show_at_cursor()| shows Git related data depending on context.
+
+What it doesn't do:
+
+- Replace fully featured Git client. Rule of thumb: if feature does not rely
+  on a state of current Neovim (opened buffers, etc.), it is out of scope.
+  For more functionality, use either |mini.diff| or fully featured Git client.
+
+Sources with more details:
+- |:Git|
+- |MiniGit-examples|
+- |MiniGit.enable()|
+- |MiniGit.get_buf_data()|
+
+# Setup ~
+
+This module needs a setup with `require('mini.git').setup({})` (replace `{}` with
+your `config` table). It will create global Lua table `MiniGit` which you can use
+for scripting or manually (with `:lua MiniGit.*`).
+
+See |MiniGit.config| for `config` structure and default values.
+
+# Comparisons ~
+
+- [tpope/vim-fugitive](https://github.com/tpope/vim-fugitive):
+    - Mostly a dedicated Git client, while this module is not (by design).
+    - Provides buffer-local Git data only through fixed statusline component,
+      while this module has richer data in the form of a Lua table.
+    - Both provide |:Git| command with `vim-fugitive` treating some cases
+      extra specially (like `:Git blame`, etc.), while this module mostly
+      treats all cases the same. See |MiniGit-examples| for how they can be
+      manually customized.
+      Also this module provides slightly different (usually richer)
+      completion suggestions.
+
+- [NeogitOrg/neogit](https://github.com/NeogitOrg/neogit):
+    - Similar to `tpope/vim-fugitive`, but without `:Git` command.
+
+- [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim):
+    - Provides buffer-local Git data with emphasis on granular diff status,
+      while this module is more oriented towards repository and file level
+      data (root, HEAD, file status, etc.). Use |mini.diff| for diff tracking.
+
+# Disabling ~
+
+To prevent buffer(s) from being tracked, set `vim.g.minigit_disable` (globally)
+or `vim.b.minigit_disable` (for a buffer) to `true`. Considering high number of
+different scenarios and customization intentions, writing exact rules for
+disabling module's functionality is left to user.
+See |mini.nvim-disabling-recipes| for common recipes.
+
+------------------------------------------------------------------------------
+                                                              *MiniGit-examples*
+# Statusline component ~
+
+Tracked buffer data can be used in statusline via `vim.b.minigit_summary_string`
+buffer-local variable. It is expected to be used as is. To show another info,
+tweak buffer-local variable directly inside `MiniGitUpdated` `User` event: >lua
+
+  -- Use only HEAD name as summary string
+  local format_summary = function(data)
+    -- Utilize buffer-local table summary
+    local summary = vim.b[data.buf].minigit_summary
+    vim.b[data.buf].minigit_summary_string = summary.head_name or ''
+  end
+
+  local au_opts = { pattern = 'MiniGitUpdated', callback = format_summary }
+  vim.api.nvim_create_autocmd('User', au_opts)
+<
+# Tweaking command output ~
+
+Buffer output of |:Git| command can be tweaked inside autocommand for
+`MiniGitCommandSplit` `User` event (see |MiniGit-command-events|).
+For example, to make `:vertical Git blame -- %` align blame output with the
+current window state, use the following code: >lua
+
+  local align_blame = function(au_data)
+    if au_data.data.git_subcommand ~= 'blame' then return end
+
+    -- Align blame output with source
+    local win_src = au_data.data.win_source
+    vim.wo.wrap = false
+    vim.fn.winrestview({ topline = vim.fn.line('w0', win_src) })
+    vim.api.nvim_win_set_cursor(0, { vim.fn.line('.', win_src), 0 })
+
+    -- Bind both windows so that they scroll together
+    vim.wo[win_src].scrollbind, vim.wo.scrollbind = true, true
+  end
+
+  local au_opts = { pattern = 'MiniGitCommandSplit', callback = align_blame }
+  vim.api.nvim_create_autocmd('User', au_opts)
+<
+# History navigation ~
+
+Function |MiniGit.show_at_cursor()| is specifically exported to make Git
+history navigation easier. Here are some different ways it can be used:
+
+- Call inside buffer for already committed file to show the evolution of
+  the current line (or visually selected range) through history.
+  It is essentially a `:Git log HEAD` with proper `-L` flag.
+  This also works inside output of |MiniGit.show_diff_source()|.
+
+- Call with cursor on commit hash to inspect that commit in full.
+  This is usually helpful in the output of `:Git log`.
+
+- Call with cursor inside diff entry to inspect its file in the state how it
+  was at certain commit. By default it shows state after commit, unless cursor
+  is on the "deleted" line (i.e. line starting with "-") in which case
+  state before commit is shown.
+
+This workflow can be made more interactive when used with mapping, like this: >lua
+
+  local rhs = '<Cmd>lua MiniGit.show_at_cursor()<CR>'
+  vim.keymap.set({ 'n', 'x' }, '<Leader>gs', rhs, { desc = 'Show at cursor' })
+<
+------------------------------------------------------------------------------
+                                                                          *:Git*
+The `:Git` user command runs `git` CLI call with extra integration for currently
+opened Neovim process:
+- Command is executed inside repository root of the currently active file
+  (or |current-directory| if file is not tracked by this module).
+
+- Command output is shown either in dedicated buffer in window split or as
+  notification via |vim.notify()|. Which method is used depends on whether
+  particular Git subcommand is supposed to show data for user to inspect
+  (like `log`, `status`, etc.) or not (like `commit`, `push`, etc.). This is
+  determined automatically based on the data Git itself provides.
+  Split window is made current after command execution.
+
+  Use split-related |:command-modifiers| (|:vertical|, |:horizontal|, or |:tab|)
+  to force output in a particular type of split. Default split direction is
+  controlled by `command.split` in |MiniGit.config|.
+
+  Use |:silent| command modifier to not show any output.
+
+  Errors and warnings are always shown as notifications.
+
+  See |MiniGit-examples| for the example of tweaking command output.
+
+- Editor for tasks that require interactive user input (like `:Git commit` or
+  `:Git rebase --interactive`) is opened inside current session in a separate
+  split. Make modifications as in regular buffer, |:write| changes followed by
+  |:close| / |:quit| for Git CLI command to resume.
+
+Examples of usage:
+- `:Git log --oneline` - show compact log of current repository.
+- `:vert Git blame -- %` - show latest commits per line in vertical split.
+- `:Git help rebase` - show help page for `rebase` subcommand.
+- `:Git -C <cwd> status` - execute `git status` inside |current-directory|.
+
+There is also a context aware completion which can be invoked with `<Tab>`:
+- If completed word starts with "-", options for the current Git subcommand
+  are shown. Like completion at `:Git log -` will suggest `-L`, `--oneline`, etc.
+- If there is an explicit " -- " to the cursor's left, incremental path
+  suggestions will be shown.
+- If there is no recognized Git subcommand yet, show list of subcommands.
+  Otherwise for some common subcommands list of its targets will be suggested:
+  like for `:Git branch` it will be list of branches, etc.
+
+Notes:
+- Paths are always treated as relative to command's execution directory
+  (file's repository root or |current-directory| if absent).
+- Don't use quotes for entries containing space, escape it with `\` directly.
+  Like `:Git commit -m Hello\ world` and not `:Git commit -m 'Hello world'`
+  (which treats `'Hello` and `world'` as separate arguments).
+
+# Events ~
+*MiniGit-command-events*
+
+There are several `User` events triggered during command execution:
+
+- `MiniGitCommandDone` - after command is done executing. For Lua callbacks it
+  provides a special `data` table with the following fields:
+    - <cmd_input> `(table)` - structured data about executed command.
+      Has same structure as Lua function input in |nvim_create_user_command()|.
+    - <cwd> `(string)` - directory path inside which Git command was executed.
+    - <exit_code> `(number)` - exit code of CLI process.
+    - <git_command> `(table)` - array with arguments of full executed command.
+    - <git_subcommand> `(string)` - detected Git subcommand (like "log", etc.).
+    - <stderr> `(string)` - `stderr` process output.
+    - <stdout> `(string)` - `stdout` process output.
+
+- `MiniGitCommandSplit` - after command showed its output in a split. Triggered
+  after `MiniGitCommandDone` and provides similar `data` table with extra fields:
+    - <win_source> `(number)` - window identifier of "source" window (current at
+      the moment before command execution).
+    - <win_stdout> `(number)` - window identifier of command output.
+
+------------------------------------------------------------------------------
+                                                               *MiniGit.setup()*
+                           `MiniGit.setup`({config})
+Module setup
+
+Besides general side effects (see |mini.nvim|), it also:
+- Sets up auto enabling in every normal buffer for an actual file on disk.
+- Creates |:Git| command.
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniGit.config|.
+
+Usage ~
+>lua
+  require('mini.git').setup() -- use default config
+  -- OR
+  require('mini.git').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                                *MiniGit.config*
+                                `MiniGit.config`
+Defaults ~
+>lua
+  MiniGit.config = {
+    -- General CLI execution
+    job = {
+      -- Path to Git executable
+      git_executable = 'git',
+
+      -- Timeout (in ms) for each job before force quit
+      timeout = 30000,
+    },
+
+    -- Options for `:Git` command
+    command = {
+      -- Default split direction
+      split = 'auto',
+    },
+  }
+<
+# Job ~
+
+`config.job` contains options for customizing CLI executions.
+
+`job.git_executable` defines a full path to Git executable. Default: "git".
+
+`job.timeout` is a duration (in ms) from job start until it is forced to stop.
+Default: 30000.
+
+# Command ~
+
+`config.command` contains options for customizing |:Git| command.
+
+`command.split` defines default split direction for |:Git| command output. Can be
+one of "horizontal", "vertical", "tab", or "auto". Value "auto" uses |:vertical|
+if only |mini.git| buffers are shown in the tabpage and |:tab| otherwise.
+Default: "auto".
+
+------------------------------------------------------------------------------
+                                                      *MiniGit.show_at_cursor()*
+                        `MiniGit.show_at_cursor`({opts})
+Show Git related data at cursor
+
+- If inside |mini.deps| confirmation buffer, show in split relevant commit data.
+- If there is a commit-like |<cword>|, show it in split.
+- If possible, show diff source via |MiniGit.show_diff_source()|.
+- If possible, show range history via |MiniGit.show_range_history()|.
+- Otherwise throw an error.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible values:
+  - <split> `(string)` - split direction. One of "horizontal", "vertical",
+    "tab", or "auto" (default). Value "auto" uses |:vertical| if only |mini.git|
+    buffers are shown in the tabpage and |:tab| otherwise.
+  - Fields appropriate for forwarding to other functions.
+
+------------------------------------------------------------------------------
+                                                    *MiniGit.show_diff_source()*
+                       `MiniGit.show_diff_source`({opts})
+Show diff source
+
+When buffer contains text formatted as unified patch (like after
+`:Git log --patch`, `:Git diff`, or |MiniGit.show_range_history()|),
+show state of the file at the particular state. Target commit/state, path,
+and line number are deduced from cursor position.
+
+Notes:
+- Needs |current-directory| to be the Git root for relative paths to work.
+- Needs cursor to be inside hunk lines or on "---" / "+++" lines with paths.
+- Only basic forms of `:Git diff` output is supported: `:Git diff`,
+  `:Git diff --cached`, and `:Git diff <commit>`.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible values:
+  - <split> `(string)` - split direction. One of "horizontal", "vertical",
+    "tab", or "auto" (default). Value "auto" uses |:vertical| if only |mini.git|
+    buffers are shown in the tabpage and |:tab| otherwise.
+  - <target> `(string)` - which file state to show. One of "before", "after",
+    "both" (both states in vertical split), "auto" (default). Value "auto"
+    shows "before" state if cursor line starts with "-", otherwise - "after".
+
+------------------------------------------------------------------------------
+                                                  *MiniGit.show_range_history()*
+                      `MiniGit.show_range_history`({opts})
+Show range history
+
+Compute and show in split data about how particular line range in current
+buffer evolved through Git history. Essentially a `git log` with `-L` flag.
+
+Notes:
+- Works well with |MiniGit.diff_foldexpr()|.
+- Does not work if there are uncommitted changes, as there is no easy way to
+  compute effective range line numbers.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible fields:
+  - <line_start> `(number)` - range start line.
+  - <line_end> `(number)` - range end line.
+    If both <line_start> and <line_end> are not supplied, they default to
+    current line in Normal mode and visual selection in Visual mode.
+  - <log_args> `(table)` - array of options to append to `git log` call.
+  - <split> `(string)` - split direction. One of "horizontal", "vertical",
+    "tab", or "auto" (default). Value "auto" uses |:vertical| if only |mini.git|
+    buffers are shown in the tabpage and |:tab| otherwise.
+
+------------------------------------------------------------------------------
+                                                       *MiniGit.diff_foldexpr()*
+                        `MiniGit.diff_foldexpr`({lnum})
+Fold expression for Git logs
+
+Folds contents of hunks, file patches, and log entries in unified diff.
+Useful for filetypes "diff" (like after `:Git diff`) and "git" (like after
+`:Git log --patch` or `:Git show` for commit).
+Works well with |MiniGit.show_range_history()|.
+
+General idea of folding levels (use |zr| and |zm| to adjust interactively):
+- At level 0 there is one line per whole patch or log entry.
+- At level 1 there is one line per patched file.
+- At level 2 there is one line per hunk.
+- At level 3 there is no folds.
+
+For automated setup, set the following for "git" and "diff" filetypes (either
+inside |FileType| autocommand or |ftplugin|): >vim
+
+  setlocal foldmethod=expr foldexpr=v:lua.MiniGit.diff_foldexpr()
+<
+Parameters ~
+{lnum} `(number|nil)` Line number for which fold level is computed.
+  Default: |v:lnum|.
+
+Return ~
+`(number|string)` Line fold level. See |fold-expr|.
+
+------------------------------------------------------------------------------
+                                                              *MiniGit.enable()*
+                           `MiniGit.enable`({buf_id})
+Enable Git tracking in a file buffer
+
+Tracking is done by reacting to changes in file content or file's repository
+in the form of keeping buffer data up to date. The data can be used via:
+- |MiniGit.get_buf_data()|. See its help for a list of actually tracked data.
+- `vim.b.minigit_summary` (table) and `vim.b.minigit_summary_string` (string)
+  buffer-local variables which are more suitable for statusline.
+  `vim.b.minigit_summary_string` contains information about HEAD, file status,
+  and in progress action (see |MiniGit.get_buf_data()| for more details).
+  See |MiniGit-examples| for how it can be tweaked and used in statusline.
+
+Note: this function is called automatically for all new normal buffers.
+Use it explicitly if buffer was disabled.
+
+`User` event `MiniGitUpdated` is triggered whenever tracking data is updated.
+Note that not all data listed in |MiniGit.get_buf_data()| can be present (yet)
+at the point of event being triggered.
+
+Parameters ~
+{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
+
+------------------------------------------------------------------------------
+                                                             *MiniGit.disable()*
+                          `MiniGit.disable`({buf_id})
+Disable Git tracking in buffer
+
+Parameters ~
+{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
+
+------------------------------------------------------------------------------
+                                                              *MiniGit.toggle()*
+                           `MiniGit.toggle`({buf_id})
+Toggle Git tracking in buffer
+
+Enable if disabled, disable if enabled.
+
+Parameters ~
+{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
+
+------------------------------------------------------------------------------
+                                                        *MiniGit.get_buf_data()*
+                        `MiniGit.get_buf_data`({buf_id})
+Get buffer data
+
+Parameters ~
+{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
+
+Return ~
+`(table|nil)` Table with buffer Git data or `nil` if buffer is not enabled.
+  If the file is not part of Git repo, table will be empty.
+  Table has the following fields:
+  - <repo> `(string)` - full path to `.git` directory.
+  - <root> `(string)` - full path to worktree root.
+  - <head> `(string)` - full commit of current HEAD.
+  - <head_name> `(string)` - short name of current HEAD (like "master").
+    For detached HEAD it is "HEAD".
+  - <status> `(string)` - two character file status as returned by `git status`.
+  - <in_progress> `(string)` - name of action(s) currently in progress
+    (bisect, merge, etc.). Can be a combination of those separated by ",".
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: