diff --git a/doc/lualine.txt b/doc/lualine.txt index 04344ae..ae28420 100644 --- a/doc/lualine.txt +++ b/doc/lualine.txt @@ -1,42 +1,83 @@ -*lualine.txt* blazing fast and easy to configure statusline - *lualine.nvim* *lualine* - __ __ __ ______ __ __ __ __ ______ - /\ \ /\ \/\ \ /\ __ \ /\ \ /\ \ /\ "-.\ \ /\ ___\ - \ \ \____ \ \ \_\ \ \ \ __ \ \ \ \____ \ \ \ \ \ \-. \ \ \ __\ - \ \_____\ \ \_____\ \ \_\ \_\ \ \_____\ \ \_\ \ \_\\"\_\ \ \_____\ - \/_____/ \/_____/ \/_/\/_/ \/_____/ \/_/ \/_/ \/_/ \/_____/ - -Author: hoob3rt (https://github.com/hoob3rt) -License: MIT License -Repository: https://github.com/hoob3rt/lualine.nvim +*lualine.txt* fast and easy to configure statusline plugin for neovim ============================================================================== -CONTENTS *lualine-contents* +Table of Contents *lualine-table-of-contents* -1. lualine.nvim..........................................|lualine-lualine.nvim| - 1.1. Usage and customization..............|lualine-usage_and_customization| - 1.1.1 Starting lualine.........................|lualine-starting_lualine| - 1.1.2 Setting a theme.....................................|lualine-theme| - 1.1.3 Separators.....................................|lualine-separators| - 1.1.4 Changing components............................|lualine-components| - 1.1.5 Custom components.......................|lualine-custom_components| - 1.1.6 Component options.......................|lualine-component_options| - 1.1.7 Tabline...........................................|lualine-tabline| - 1.1.8 Extensions.....................................|lualine-extensions| - 1.1.8 Disabling lualine.................................|lualine-disable| +1. lualine.nvim |lualine-lualine.nvim| + - Contributing |lualine-contributing| + - Performance compared to other plugins|lualine-performance-compared-to-other-plugins| + - Installation |lualine-installation| + - Usage and customization |lualine-usage-and-customization| ============================================================================== -USAGE AND CUSTOMIZATION *lualine-usage_and_customization* +1. lualine.nvim *lualine-lualine.nvim* + +A fast and easy to configure statusline plugin for neovim + +`lualine.nvim` requires neovim 0.5 + +CONTRIBUTING *lualine-contributing* + +Feel free to create an issue/pr if you want to see anything else implemented. +If you have some question or need help with configuration start a discussion +. + +Please read CONTRIBUTING.md <./CONTRIBUTING.md> before opening a pr. You can +also help with documentation in wiki + + +PERFORMANCE COMPARED TO OTHER PLUGINS*lualine-performance-compared-to-other-plugins* + +Unlike other statusline plugins lualine loads only defined components, nothing +else. + +Startup time performance measured with an amazing plugin +tweekmonster/startuptime.vim + +All times are measured with only `startuptime.vim` and given statusline plugin +installed + +│clean vimrc│lualine │lightline│ airline │ +│ 8.943 ms │9.034 ms│11.463 ms│13.425 ms│ + + +INSTALLATION *lualine-installation* + +VIM-PLUG + +> + Plug 'hoob3rt/lualine.nvim' + " If you want to have icons in your statusline choose one of these + Plug 'kyazdani42/nvim-web-devicons' + Plug 'ryanoasis/vim-devicons' +< + + +PACKER.NVIM + +> + use { + 'hoob3rt/lualine.nvim', + requires = {'kyazdani42/nvim-web-devicons', opt = true} + } +< + + +USAGE AND CUSTOMIZATION *lualine-usage-and-customization* Lualine has sections as shown below. + > +-------------------------------------------------+ | A | B | C X | Y | Z | +-------------------------------------------------+ +< -Each sections holds it's components e.g. current vim's mode. -Default config~ +Each sections holds it’s components e.g. current vim’s mode. + +Default config + > require'lualine'.setup { options = { @@ -66,259 +107,323 @@ Default config~ tabline = {}, extensions = {} } - -If you want to get your current lualine config. you can -do so with > - require'lualine'.get_config() - < + + +If you want to get your current lualine config. you can do so with + +> + require'lualine'.get_config() +< + + ------------------------------------------------------------------------------ -STARTING LUALINE *lualine-starting_lualine* *lualine.setup()* + +STARTING LUALINE + > require('lualine').setup() +< + ------------------------------------------------------------------------------ -SETTING A THEME *lualine-theme* + +SETTING A THEME + > options = {theme = 'gruvbox'} +< -Available themes are listed here: -https://github.com/hoob3rt/lualine.nvim/blob/master/THEMES.md -Customizing themes~ +All available themes are listed in THEMES.md <./THEMES.md> + +Please create a pr if you managed to port a popular theme before me, here is +how to do it <./CONTRIBUTING.md>. + +Customizing themes + > local custom_gruvbox = require'lualine.themes.gruvbox' - -- Change the background of lualine_c section for normal mode custom_gruvbox.normal.c.bg = '#112233' -- rgb colors are supported - require'lualine'.setup{ options = { theme = custom_gruvbox }, ... } < -Theme structure is available here: -https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme + + +Theme structure is available here + ------------------------------------------------------------------------------ -SEPARATORS *lualine-separators* -Lualine defines two kinds of seperators: - * |section_separators| - separators between sections - * |components_separators| - separators between components in sections +SEPARATORS + +Lualine defines two kinds of separators: + + +- `section_separators` - separators between sections +- `components_separators` - separators between components in sections + + > options = { section_separators = {'', ''}, component_separators = {'', ''} } +< + + +Disabling separators -Disabling separators~ > options = {section_separators = '', component_separators = ''} +< + ------------------------------------------------------------------------------ -CHANGING COMPONENTS IN LUALINE SECTIONS *lualine-components* - `sections = {lualine_a = {'mode'}}` +CHANGING COMPONENTS IN LUALINE SECTIONS -Available components~ - general~ - * |branch| (git branch) - * |diagnostics| (diagnostics count from your preferred source) - * |encoding| (file encoding) - * |fileformat| (file format) - * |filename| - * |filesize| - * |filetype| - * |hostname| - * |location| (location in file in line:column format) - * |mode| (vim mode) - * |progress| (%progress in file) - * |diff| (git diff status) +> + sections = {lualine_a = {'mode'}} +< ------------------------------------------------------------------------------- -CUSTOM COMPONENTS *lualine-custom_components* -Lua functions as lualine component~ +**Available components** + + +- `branch` (git branch) +- `diagnostics` (diagnostics count from your prefered source) +- `encoding` (file encoding) +- `fileformat` (file format) +- `filename` +- `filesize` +- `filetype` +- `hostname` +- `location` (location in file in line:column format) +- `mode` (vim mode) +- `progress` (%progress in file) +- `diff` (git diff status) + + + *lualine-Custom-components* + +LUA FUNCTIONS AS LUALINE COMPONENT + > local function hello() return [[hello world]] end sections = {lualine_a = {hello}} < -Vim functions as lualine component~ + + +VIM FUNCTIONS AS LUALINE COMPONENT + > sections = {lualine_a = {'FugitiveHead'}} < -Vim's statusline items as lualine component~ + + + *lualine-Vim’s-statusline-items-as-lualine-component* + > sections = {lualine_c = {'%=', '%t%m', '%3p'}} < -Vim variables as lualine component~ -Variables from `g:`, `v:`, `t:`, `w:`, `b:`, `o`, `go:`, `vo:`, `to:`, `wo:`, `bo:` scopes can be used. -See `:h lua-vim-variables` and `:h lua-vim-options` if you are not sure what to use. +VIM VARIABLES AS LUALINE COMPONENT + +Variables from `g:`, `v:`, `t:`, `w:`, `b:`, `o`, `go:`, `vo:`, `to:`, `wo:`, +`bo:` scopes can be used. + +See `:h lua-vim-variables` and `:h lua-vim-options` if you are not sure what to +use. + > sections = {lualine_a = {'g:coc_status', 'bo:filetype'}} < -Lua expressions as lualine component~ -You can use any valid lua expression as a component including - * oneliners - * global variables - * require statements + +LUA EXPRESSIONS AS LUALINE COMPONENT + +You can use any valid lua expression as a component including * oneliners * +global variables * require statements + > - sections = {lualine_c = {"os.date('%a')", 'data', require'lsp-status'.status}} + sections = {lualine_c = {"os.date('%a')", 'data', "require'lsp-status'.status()"}} +< + `data` is a global variable in this example. ------------------------------------------------------------------------------ -COMPONENT OPTIONS *lualine-component_options* -Component options can change the way a component behave. -There are two kinds of options: - * global options affecting all components - * local options affecting specific +COMPONENT OPTIONS + +Component options can change the way a component behave. There are two kinds of +options: * global options affecting all components * local options affecting +specific + +Global options can be used as local options (can be applied to specific +components) but you cannot use local options as global. Global option used +locally overwrites the global, for example: -Global options can be used as local options (can be applied to specific components) -but you cannot use local options as global. -Global option used locally overwrites the global, for example: > - require'lualine'.setup { - options = {lower = true}, - sections = {lualine_a = {{'mode', lower = false}}, lualine_b = {'branch'}} - } - -`mode` will be displayed with `lower = false` and `branch` will be displayed with `lower = true` - -Available options:~ - -Global options~ ---------------- -> - options = { - icons_enabled = 1, -- displays icons in alongside component - padding = 1, -- adds padding to the left and right of components - left_padding = 1, -- adds padding to the left of components - right_padding =1, -- adds padding to the right of components - upper = false, -- displays components in uppercase - lower = false, -- displays components in lowercase - format = nil -- format function, formats component's output - } - -Local options~ ---------------- -> - sections = { - lualine_a = { - { - 'mode', - icon = nil, -- displays icon in front of the component - separator = nil, -- Determines what separator to use for the component. - -- when a string is given it's treated as component_separator. - -- When a table is given it's treated as section_separator. - -- This options can be used to set colored separators - -- arround component. Option need to be set like `separator = {'', ''}`. - -- Where first element is left_separator and 2nd element is right separator. - -- Passing empty string disables that separator - condition = nil, -- condition function, component is loaded when function returns true - -- custom color for component in format - -- color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'} - -- or highlight group - -- color = "WarningMsg" - color = nil, - -- Type option specifies what type a component is. - -- When type is omitted lualine will guess it. - -- Available types [format: type_name(example)] - -- mod(branch/filename), stl(%f/%m), var(g:coc_status/bo:modifiable), - -- luae(lua expressions), vimf(viml function name) - -- luae is short for lua-expression and vimf is short fror vim-function - -- vim_function(viml function name) - type = nil, - } - } - } - -Component specific local options~ ---------------- - -* diagnostics~ - > - sections = { - lualine_a = { - { - 'diagnostics', - -- table of diagnostic sources, available sources: - -- 'nvim_lsp', 'coc', 'ale', 'vim_lsp' - -- Or a function that returns a table like - -- {error=error_cnt, warning=warn_cnt, info=info_cnt, hint=hint_cnt} - sources = {}, - -- displays diagnostics from defined severity - sections = {'error', 'warn', 'info', 'hint'}, - -- all colors are in format #rrggbb - color_error = nil, -- changes diagnostic's error foreground color - color_warn = nil, -- changes diagnostic's warn foreground color - color_info = nil, -- Changes diagnostic's info foreground color - color_hint = nil, -- Changes diagnostic's hint foreground color - symbols = {error = 'E', warn = 'W', info = 'I', hint = 'H'} - update_in_insert = false, -- Update diagnostics in insert mode - } - } - } - -* filename~ -> - sections = { - lualine_a = { - { - 'filename', - file_status = true, -- displays file status (readonly status, modified status) - path = 0 -- 0 = just filename, 1 = relative path, 2 = absolute path - shorting_target = 40 -- Shortens path to leave 40 space in the window - -- for other components. Terrible name any suggestions? - } - } - } - -* filetype~ -> - sections = { - lualine_a = { - { - 'filetype', - colored = true, -- displays filetype icon in color if set to `true` - disable_text = false -- Display only icon for filetype - } - } - } + require'lualine'.setup { + options = {lower = true}, + sections = {lualine_a = {{'mode', lower = false}}, lualine_b = {'branch'}} + } < -* diff~ + +`mode` will be displayed with `lower = false` and `branch` will be displayed +with `lower = true` + + *lualine-Available-options* + +**Global options** + > - sections = { - lualine_a = { - { - 'diff', - colored = true, -- displays diff status in color if set to true - -- all colors are in format #rrggbb - color_added = nil, -- changes diff's added foreground color - color_modified = nil, -- changes diff's modified foreground color - color_removed = nil, -- changes diff's removed foreground color - symbols = {added = '+', modified = '~', removed = '-'} -- changes diff symbols - source = nil, -- A function that works as a data source for diff. - -- it must return a table like - -- {added = add_count, modified = modified_count, removed = removed_count } - -- Or nil on failure. Count <= 0 won't be displayed. + options = { + icons_enabled = true, -- displays icons in alongside component + padding = 1, -- adds padding to the left and right of components + left_padding = 1, -- adds padding to the left of components + right_padding =1, -- adds padding to the right of components + upper = false, -- displays components in uppercase + lower = false, -- displays components in lowercase + format = nil -- format function, formats component's output + } +< + + +**Local options** + +> + sections = { + lualine_a = { + { + 'mode', + icon = nil, -- displays icon in front of the component + separator = nil, -- Determines what separator to use for the component. + -- when a string is given it's treated as component_separator. + -- When a table is given it's treated as section_separator. + -- This options can be used to set colored separators + -- arround component. Option need to be set like `separator = {'', ''}`. + -- Where first element is left_separator and 2nd element is right separator. + -- Passing empty string disables that separator + condition = nil, -- condition function, component is loaded when function returns true + -- custom color for component in format + -- color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'} + -- or highlight group + -- color = "WarningMsg" + color = nil, + -- Type option specifies what type a component is. + -- When type is omitted lualine will guess it. + -- Available types [format: type_name(example)] + -- mod(branch/filename), stl(%f/%m), var(g:coc_status/bo:modifiable), + -- luae(lua expressions), vimf(viml function name) + -- luae is short for lua-expression and vimf is short fror vim-function + type = nil, + } } } - } +< + + +**Component specific local options** + + *lualine-diagnostics-component-options* + +> + sections = { + lualine_a = { + { + 'diagnostics', + -- table of diagnostic sources, available sources: + -- 'nvim_lsp', 'coc', 'ale', 'vim_lsp' + -- Or a function that returns a table like + -- {error=error_cnt, warning=warn_cnt, info=info_cnt, hint=hint_cnt} + sources = {}, + -- displays diagnostics from defined severity + sections = {'error', 'warn', 'info', 'hint'}, + -- all colors are in format #rrggbb + color_error = nil, -- changes diagnostic's error foreground color + color_warn = nil, -- changes diagnostic's warn foreground color + color_info = nil, -- Changes diagnostic's info foreground color + color_hint = nil, -- Changes diagnostic's hint foreground color + symbols = {error = 'E', warn = 'W', info = 'I', hint = 'H'} + update_in_insert = false, -- Update diagnostics in insert mode + } + } + } +< + + + *lualine-filename-component-options* + +> + sections = { + lualine_a = { + { + 'filename', + file_status = true, -- displays file status (readonly status, modified status) + path = 0, -- 0 = just filename, 1 = relative path, 2 = absolute path + shorting_target = 40 -- Shortens path to leave 40 space in the window + -- for other components. Terrible name any suggestions? + } + } + } +< + + + *lualine-filetype-component-options* + +> + sections = { + lualine_a = { + { + 'filetype', + colored = true, -- displays filetype icon in color if set to `true + disable_text = false -- Display only icon for filetype + } + } + } +< + + + *lualine-diff-component-options* + +> + sections = { + lualine_a = { + { + 'diff', + colored = true, -- displays diff status in color if set to true + -- all colors are in format #rrggbb + color_added = nil, -- changes diff's added foreground color + color_modified = nil, -- changes diff's modified foreground color + color_removed = nil, -- changes diff's removed foreground color + symbols = {added = '+', modified = '~', removed = '-'} -- changes diff symbols + source = nil, -- A function that works as a data source for diff. + -- it must return a table like + -- {added = add_count, modified = modified_count, removed = removed_count } + -- Or nil on failure. Count <= 0 won't be displayed. + } + } + } +< + ------------------------------------------------------------------------------ -TABLINE *lualine-tabline* -You can use lualine to display components in tabline. -The configuration for tabline sections is exactly the same as for statusline. +TABLINE + +You can use lualine to display components in tabline. The configuration for +tabline sections is exactly the same as for statusline. + > tabline = { lualine_a = {}, @@ -326,62 +431,85 @@ The configuration for tabline sections is exactly the same as for statusline. lualine_c = {'filename'}, lualine_x = {}, lualine_y = {}, - lualine_z = {}, + lualine_z = {} } < -This will show branch and filename component on top of neovim inside tabline. -You can also completely move your statuline to tabline by configuring -|lualine.tabline| and disabling |lualine.sections| and |lualine.inactive_sections|. + +This will show branch and filename component in top of neovim inside tabline. + +You can also completely move your statuline to tabline by configuring +`lualine.tabline` and disabling `lualine.sections` and +`lualine.inactive_sections`. + > tabline = { ...... - } - sections = {} - inactive_sections = {} + }, + sections = {}, + inactive_sections = {}, +< -If you're looking for bufferline or want to show tabs in tabline . There are + +If you’re looking for bufferline or want to show tabs in tabline. There are manny awesome plugins that can do that. For example: - * [nvim-bufferline](https://github.com/akinsho/nvim-bufferline.lua) - * [tabline.nvim](https://github.com/kdheepak/tabline.nvim) -tabline.nvim even uses lualines theme by default 🙌 -You can find a bigger list [here](https://github.com/rockerBOO/awesome-neovim#tabline) +- nvim-bufferline +- tabline.nvim + + +tabline.nvim even uses lualines theme by default 🙌 You can find a bigger +list here ------------------------------------------------------------------------------ -EXTENSIONS *lualine-extensions* + +EXTENSIONS Lualine extensions change statusline appearance for a window/buffer with specified filetypes. -By default no extension are loaded to improve performance. -You can load extensions with: +By default no extension are loaded to improve performance. You can load +extensions with: + > extensions = {'quickfix'} < -Available extensions~ - * |chadtree| - * |fugitive| - * |fzf| - * |nerdtree| - * |nvim-tree| - * |quickfix| - * -Custom extensions~ -You can define your own extensions. -If you think an extension might be useful for others then please submit a pr. +**Available extensions** + + +- chadtree +- fugitive +- fzf +- nerdtree +- nvim-tree +- quickfix + + +**Custom extensions** + +You can define your own extensions. If you think an extension might be useful +for others then please submit a pr. + > local my_extension = {sections = {lualine_a = 'mode'}, filetypes = {'lua'}} require'lualine'.setup {extensions = {my_extension}} +< + ------------------------------------------------------------------------------ -DISABLING LUALINE *lualine-disable* + +DISABLING LUALINE You can disable lualine for specific filetypes -`options = {disabled_filetypes = {'lua'}}` ------------------------------------------------------------------------------- -vim:tw=80:sw=4:ts=8:et:ft=help:norl:et: +> + options = {disabled_filetypes = {'lua'}} +< + + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: