Something went wrong. Try again.
Library of 45+ independent Lua modules improving Neovim experience with minimal effort nvim-mini.org/mini.nvim
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361*mini.statusline* Statusline
MIT License Copyright (c) 2021 Evgeni Chasnovski
------------------------------------------------------------------------------ *MiniStatusline*Features:- Define own custom statusline structure for active and inactive windows. This is done with a function which should return string appropriate for |'statusline'|. Its code should be similar to default one with structure: - Compute string data for every section you want to be displayed. - Combine them in groups with |MiniStatusline.combine_groups()|.
- Built-in active mode indicator with colors.
- Sections can hide information when window is too narrow (specific window width is configurable per section).
# Dependencies ~
Suggested dependencies (provide extra functionality, will work without them):
- Nerd font (to support extra icons).
- Enabled |mini.icons| module for |MiniStatusline.section_fileinfo()|. Falls back to using `nvim-tree/nvim-web-devicons` plugin or shows nothing.
- Enabled |mini.git| module for |MiniStatusline.section_git()|. Falls back to using `lewis6991/gitsigns.nvim` plugin or shows nothing.
- Enabled |mini.diff| module for |MiniStatusline.section_diff()|. Falls back to using `lewis6991/gitsigns.nvim` plugin or shows nothing.
# Setup ~
This module needs a setup with `require('mini.statusline').setup({})`(replace `{}` with your `config` table). It will create global Lua table`MiniStatusline` which you can use for scripting or manually (with`:lua MiniStatusline.*`).
See |MiniStatusline.config| for `config` structure and default values. Forsome content examples, see |MiniStatusline-example-content|.
You can override runtime config settings locally to buffer inside`vim.b.ministatusline_config` which should have same structure as`MiniStatusline.config`. See |mini.nvim-buffer-local-config| for more details.
# Highlight groups ~*MiniStatusline-hl-groups*
Highlight depending on mode (second |MiniStatusline.section_mode()| output):- `MiniStatuslineModeNormal` - Normal mode.- `MiniStatuslineModeInsert` - Insert mode.- `MiniStatuslineModeVisual` - Visual mode.- `MiniStatuslineModeReplace` - Replace mode.- `MiniStatuslineModeCommand` - Command mode.- `MiniStatuslineModeOther` - other modes (like Terminal, etc.).
Highlight used in default statusline:- `MiniStatuslineDevinfo` - for "dev info" group (|MiniStatusline.section_git()| and |MiniStatusline.section_diagnostics()|).- `MiniStatuslineFilename` - for |MiniStatusline.section_filename()| section.- `MiniStatuslineFileinfo` - for |MiniStatusline.section_fileinfo()| section.
Other groups:- `MiniStatuslineInactive` - highlighting in not focused window.
To change any highlight group, set it directly with |nvim_set_hl()|.
# Disabling ~
To disable (show empty statusline), set `vim.g.ministatusline_disable`(globally) or `vim.b.ministatusline_disable` (for a buffer) to `true`.Considering high number of different scenarios and customizationintentions, writing exact rules for disabling module's functionality isleft to user. See |mini.nvim-disabling-recipes| for common recipes.
------------------------------------------------------------------------------ *MiniStatusline-example-content*Example content
# Default content ~
This function is used as default value for active content: >lua
function() local mode, mode_hl = MiniStatusline.section_mode({ trunc_width = 120 }) local git = MiniStatusline.section_git({ trunc_width = 40 }) local diff = MiniStatusline.section_diff({ trunc_width = 75 }) local diagnostics = MiniStatusline.section_diagnostics({ trunc_width = 75 }) local lsp = MiniStatusline.section_lsp({ trunc_width = 75 }) local filename = MiniStatusline.section_filename({ trunc_width = 140 }) local fileinfo = MiniStatusline.section_fileinfo({ trunc_width = 120 }) local location = MiniStatusline.section_location({ trunc_width = 75 }) local search = MiniStatusline.section_searchcount({ trunc_width = 75 })
return MiniStatusline.combine_groups({ { hl = mode_hl, strings = { mode } }, { hl = 'MiniStatuslineDevinfo', strings = { git, diff, diagnostics, lsp } }, '%<', -- Mark general truncate point { hl = 'MiniStatuslineFilename', strings = { filename } }, '%=', -- End left alignment { hl = 'MiniStatuslineFileinfo', strings = { fileinfo } }, { hl = mode_hl, strings = { search, location } }, }) end<# Show boolean options ~
To compute section string for boolean option use variation of this codesnippet inside content function (you can modify option itself, truncationwidth, short and long displayed names): >lua
local spell = vim.wo.spell and (MiniStatusline.is_truncated(120) and 'S' or 'SPELL') or ''<Here `x and y or z` is a common Lua way of doing ternary operator: if `x`is `true`-ish then return `y`, if not - return `z`.
------------------------------------------------------------------------------ *MiniStatusline.setup()* `MiniStatusline.setup`({config})Module setup
Parameters ~{config} `(table|nil)` Module config table. See |MiniStatusline.config|.
Usage ~>lua require('mini.statusline').setup() -- use default config -- OR require('mini.statusline').setup({}) -- replace {} with your config table<------------------------------------------------------------------------------ *MiniStatusline.config* `MiniStatusline.config`Defaults ~>lua MiniStatusline.config = { -- Content of statusline as functions which return statusline string. See -- `:h statusline` and code of default contents (used instead of `nil`). content = { -- Content for active window active = nil, -- Content for inactive window(s) inactive = nil, },
-- Whether to use icons by default use_icons = true, }<------------------------------------------------------------------------------ *MiniStatusline.active()* `MiniStatusline.active`()Compute content for active window
------------------------------------------------------------------------------ *MiniStatusline.inactive()* `MiniStatusline.inactive`()Compute content for inactive window
------------------------------------------------------------------------------ *MiniStatusline.combine_groups()* `MiniStatusline.combine_groups`({groups})Combine groups of sections
Each group can be either a string or a table with fields `hl` (group'shighlight group) and `strings` (strings representing sections).
General idea of this function is as follows;- String group is used as is (useful for special strings like `%<` or `%=`).- Each table group has own highlighting in `hl` field (if missing, the previous one is used) and string parts in `strings` field. Non-empty strings from `strings` are separated by one space. Non-empty groups are separated by two spaces (one for each highlighting).
Parameters ~{groups} `(table)` Array of groups.
Return ~`(string)` String suitable for |'statusline'|.
------------------------------------------------------------------------------ *MiniStatusline.is_truncated()* `MiniStatusline.is_truncated`({trunc_width})Decide whether to truncate
This basically computes window width and compares it to `trunc_width`: ifwindow is smaller then truncate; otherwise don't. Don't truncate bydefault.
Use this to manually decide if section needs truncation or not.
Parameters ~{trunc_width} `(number|nil)` Truncation width. If `nil`, output is `false`.
Return ~`(boolean)` Whether to truncate.
------------------------------------------------------------------------------ *MiniStatusline.section_mode()* `MiniStatusline.section_mode`({args})Section for Vim |mode()|
Short output is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments.
Return ~`(...)` Section string and mode's highlight group.
------------------------------------------------------------------------------ *MiniStatusline.section_git()* `MiniStatusline.section_git`({args})Section for Git information
Shows Git summary from |mini.git| (should be set up; recommended). To tweakformatting of what data is shown, modify buffer-local summary string directlyas described in |MiniGit-examples|.
If |mini.git| is not set up, section falls back on `lewis6991/gitsigns.nvim` dataor showing empty string.
Empty string is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_diff()* `MiniStatusline.section_diff`({args})Section for diff information
Shows diff summary from |mini.diff| (should be set up; recommended). To tweakformatting of what data is shown, modify buffer-local summary string directlyas described in |MiniDiff-diff-summary|.
If |mini.diff| is not set up, section falls back on `lewis6991/gitsigns.nvim` dataor showing empty string.
Empty string is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_diagnostics()* `MiniStatusline.section_diagnostics`({args})Section for Neovim's builtin diagnostics
Shows nothing if diagnostics is disabled, no diagnostic is set, or for shortoutput. Otherwise uses |vim.diagnostic.get()| to compute and show number oferrors (`E`), warnings (`W`), information (`I`), and hints (`H`).
Short output is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments. Use `args.icon` to supply your own icon. Use `args.signs` to use custom signs per severity level name. For example: >lua
{ ERROR = '!', WARN = '?', INFO = '@', HINT = '*' }<Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_lsp()* `MiniStatusline.section_lsp`({args})Section for attached LSP servers
Shows number of LSP servers (each as separate "+" character) attached tocurrent buffer or nothing if none is attached.Nothing is shown if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_filename()* `MiniStatusline.section_filename`({args})Section for file name
Show full file name or relative in short output.
Short output is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_fileinfo()* `MiniStatusline.section_fileinfo`({args})Section for file information
Shows |'filetype'|, |'fileencoding'| / |'encoding'|, |'fileformat'|, and buffer size.Short output has only non-empty |'filetype'| and is returned if window width islower than `args.trunc_width` or buffer is not normal (as per |'buftype'|).
Buffer size is computed based on current text, not file's saved version.
If `config.use_icons` is true and icon provider is present (see"Dependencies" section in |mini.statusline|), shows icon near the filetype.
Parameters ~{args} `(table)` Section arguments.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_location()* `MiniStatusline.section_location`({args})Section for location inside buffer
Show location inside buffer in the form:- Normal: `'<cursor line>|<total lines>│<cursor column>|<total columns>'`- Short: `'<cursor line>│<cursor column>'`
Short output is returned if window width is lower than `args.trunc_width`.
Parameters ~{args} `(table)` Section arguments.
Return ~`(string)` Section string.
------------------------------------------------------------------------------ *MiniStatusline.section_searchcount()* `MiniStatusline.section_searchcount`({args})Section for current search count
Show the current status of |searchcount()|. Empty output is returned ifwindow width is lower than `args.trunc_width`, search highlighting is noton (see |v:hlsearch|), or if number of search result is 0.
`args.options` is forwarded to |searchcount()|. By default it recomputesdata on every call which can be computationally expensive (although stillusually on 0.1 ms order of magnitude). To prevent this, supply`args.options = { recompute = false }`.
Parameters ~{args} `(table)` Section arguments.
Return ~`(string)` Section string.
vim:tw=78:ts=8:noet:ft=help:norl: