lualine.nvim/doc/lualine.txt

580 lines
18 KiB
Plaintext
Raw Normal View History

*lualine.txt* A blazing fast and easy to configure statusline
*lualine_nvim* *lualine*
2021-02-09 14:27:42 +00:00
Author: hoob3rt (https://github.com/hoob3rt)
License: MIT License
Repository: https://github.com/hoob3rt/lualine.nvim
===============================================================================
LUALINE.NVIM *lualine_lualine.nvim*
2021-02-09 14:27:42 +00:00
__ __ __ ______ __ __ __ __ ______
/\ \ /\ \/\ \ /\ __ \ /\ \ /\ \ /\ "-.\ \ /\ ___\
\ \ \____ \ \ \_\ \ \ \ __ \ \ \ \____ \ \ \ \ \ \-. \ \ \ __\
\ \_____\ \ \_____\ \ \_\ \_\ \ \_____\ \ \_\ \ \_\\"\_\ \ \_____\
\/_____/ \/_____/ \/_/\/_/ \/_____/ \/_/ \/_/ \/_/ \/_____/
2021-02-09 14:27:42 +00:00
A blazing fast and easy to configure neovim statusline written in pure lua.
`lualine.nvim` requires neovim 0.5
================================================================================
CONTENTS *lualine_contents*
1. lualine.nvim...........................................|lualine_lualine.nvim|
2021-04-07 00:45:50 +00:00
1.1. Performance comparison.................|lualine_performance_comparison|
1.2. Installation.....................................|lualine_installation|
1.2.1. vim-plug.......................................|lualine_vim-plug|
1.2.2.packer.nvim..................................|lualine_packer.nvim|
1.3. Usage and customization...............|lualine_usage_and_customization|
1.3.1. Starting lualine.......................|lualine_starting_lualine|
1.3.2. Setting theme.............................|lualine_setting_theme|
1.3.3. Changing separator...................|lualine_changing_separator|
1.3.4. Changing components.................|lualine_changing_components|
1.3.5. Building Custom components............|lualine_custom_components|
1.3.6. Custom options...........................|lualine_custom_options|
2021-03-06 15:03:00 +00:00
1.3.7. Using tabline as statusline...............|lualine_using_tabline|
1.3.8. Loading plugin extensions.....|lualine_loading_plugin_extensions|
1.3.9 Config examples.........................|lualine_config_examples|
1.3.9.1. Packer.nvim......|lualine_config_example_using_packer.nvim|
1.3.9.2 VIML example.......|lualine_full_config_example_inside_viml|
1.4. Contributing.....................................|lualine_contributing|
1.5. Screenshots.......................................|lualine_screenshots|
2021-02-09 14:27:42 +00:00
================================================================================
2021-04-07 00:45:50 +00:00
PERFORMANCE COMPARISON *lualine_performance_comparison*
2021-02-09 14:27:42 +00:00
Unlike other statusline plugins lualine loads only defined components, nothing else.
Startup time performance measured with an amazing plugin
tweekmonster/startuptime.vim (https://github.com/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*
2021-02-09 14:27:42 +00:00
VIM-PLUG *lualine_vim-plug*
2021-02-09 14:27:42 +00:00
>
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 *lualine_packer.nvim*
2021-02-09 14:27:42 +00:00
>
use {
'hoob3rt/lualine.nvim',
requires = {'kyazdani42/nvim-web-devicons', opt = true}
}
<
--------------------------------------------------------------------------------
USAGE AND CUSTOMIZATION *lualine_usage_and_customization*
2021-02-09 14:27:42 +00:00
Lualine has sections as shown below.
>
+-------------------------------------------------+
| A | B | C X | Y | Z |
2021-02-09 14:27:42 +00:00
+-------------------------------------------------+
<
Each sections holds it's components e.g. current vim's mode.
Colorscheme of sections is mirrored, meaning section `A` will have the same
colorscheme as section `Z` etc.
Configuration is currently limited to lua, please use lua block or a separate
lua file to configure lualine.
STARTING LUALINE *lualine_starting_lualine*
2021-02-09 14:27:42 +00:00
>
require('lualine').setup{}
2021-02-09 14:27:42 +00:00
<
SETTING THEME *lualine_setting_theme*
2021-02-09 14:27:42 +00:00
>
options = {theme = 'gruvbox'}
2021-02-09 14:27:42 +00:00
<
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).
2021-04-12 06:25:21 +00:00
Tweeking themes~
You like a theme but would like to tweek some colors.
You can do that in your config easily.
Example:
>
local custom_gruvbox = require'lualine.themes.gruvbox'
-- Chnage 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 },
...
}
<
You can checkout structure of a lualine theme [here](https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme)
CHANGING SEPARATOR IN SECTION *lualine_changing_separator*
2021-02-09 14:27:42 +00:00
Lualine defines two kinds of seperators. One is for sections and other is
for components. Default section seperators are '', '' and component
separators are '', ''.They require powerline patched fonts. But you can
easily change yours to something else like below.
2021-02-09 14:27:42 +00:00
>
options = {
section_separators = {'', ''},
component_separators = {'', ''}
}
2021-02-09 14:27:42 +00:00
or disable it
>
options = {section_separators = '', component_separators = ''}
2021-02-09 14:27:42 +00:00
<
CHANGING COMPONENTS IN LUALINE SECTIONS *lualine_changing_components*
2021-02-09 14:27:42 +00:00
Lualine defaults~
>
sections = {
2021-02-09 14:27:42 +00:00
lualine_a = { 'mode' },
lualine_b = { 'branch' },
lualine_c = { 'filename' },
lualine_x = { 'encoding', 'fileformat', 'filetype' },
lualine_y = { 'progress' },
lualine_z = { 'location' },
}
inactive_sections = {
2021-02-09 14:27:42 +00:00
lualine_a = { },
lualine_b = { },
lualine_c = { 'filename' },
lualine_x = { 'location' },
lualine_y = { },
lualine_z = { }
}
<
Available components~
general~
* branch (git branch)
* diagnostics (diagnostics count from your prefered source)
* encoding (file encoding)
* fileformat (file format)
2021-02-09 14:27:42 +00:00
* filename
* filetype
2021-04-06 14:03:41 +00:00
* hostname
* location (location in file in line:column format)
* mode (vim mode)
* progress (%progress in file)
* diff (git diff status)
2021-02-09 14:27:42 +00:00
--------------------------------------------------------------------------------
BUILDING YOUR COMPONENTS *lualine_custom_components*
2021-02-09 14:27:42 +00:00
Using custom functions as lualine component~
You can define a custom function as a lualine component
>
local function hello()
return [[hello world]]
end
sections = {lualine_a = {hello}}
2021-02-09 14:27:42 +00:00
<
Using vim functions as lualine component~
You can use vim functions as a lualine component
>
sections = {lualine_a = {'FugitiveHead'}}
<
Using variables as lualine component~
You can use variables from vim. Variables from g:, v:, t:,
w:, b:, o, go:, vo:, to:, wo:, bo: scopes can be used.
Scopes ending with o are options usualy accessed with `&` in
vimscript
>
sections = {lualine_a = {'g:coc_status', 'bo:filetype'}}
<
Using lua expressions as lualine component~
You can use any valid lua expression as a component . This
allows global variables to be used as a component too. Even
require statements can be used to access values returned by
specific scripts. One liner functions can be inlined by
utilizeing this .
For exmaple this will show day of the week. And 2nd one
will display current value of global variabke data.
>
sections = {lualine_c = {"os.data('%a')", 'data'}}
<
--------------------------------------------------------------------------------
CUSTOM OPTIONS FOR COMPONENTS *lualine_custom_options*
Options for components~
======================
2021-04-06 14:03:41 +00:00
Available options:~
Options can change the way a component behave.
There are two kinds of options some that work on every kind of component.
Even the ones you create like custom function component . And some that only
work on specific component.
Detailed list of available options are given below.
Global options~
2021-04-06 14:03:41 +00:00
These options are available for all components.
option (default_value)
------ ---------------
• icons_enabled (true)
Displays icons on components
You should have nerd-fonts supported fonts to see icons properly.
Supported components: branch, fileformat, filetype, location, diagnostics
2021-04-06 14:03:41 +00:00
• icon (depends on component)
displays an icon infront of a component
Supported components: all
• padding (1)
spaces on left and right
Supported components: all
• left_padding (1)
spaces on left
Supported components: all
• right_padding (1)
spaces on right
Supported components: all
2021-04-06 14:03:41 +00:00
• separator (component_separators)
which separator to use at end of component
Supported components: all
• upper (false)
Displayed in upper case
Supported components: all
• lower (false)
Displayed in lower case
Supported components: all
• format (nil)
Takes a function . The funtion gets the result of component
as argument and it's return value is displayed. So this function
can parse and format the output as user wants.
Supported components: all
Example:
`lualine.options.icons_enabled = true`
Component specific options
---------------
As mentioned above, all global options can be applied to specific components.
However there are some options which are component-only (you cannot set them as globals)
option (default_value)
------ ---------------
• icon (differs for each component)
displays an icon infront of a component
2021-04-06 13:31:45 +00:00
• condition (nil)
Takes a function. The component is loaded if the function
returns true otherwise not. It can be used to load some
comoonents on specific cases.
• color (Theme colors)
color option can be used to set custom color to a component
Color format:
`lua color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'}`
the members of color table are optional and default to theme
Color option can also be a string containing highlight group name >
color = "WarningMsg"`
< One neat trick set the color to highlight group name then change
that highlight with :hi command to change color of that component
at runtime.
2021-04-06 14:03:41 +00:00
Using global options~
Global options can be set in two ways. One is as part of options table in setup.
>
require'lualine'.setup{
options = {
icons_enabled = true,
padding = 2,
}
}
<
When set this way these values work as default for all component.
These defaults can be overwritten by setting option as part of component
configuration like following.
>
lualine_a = {
-- Displays only first char of mode name
{'mode', format=function(mode_name) return mode_name:sub(1,1) end},
-- Disables icon for branch component
{'branch', icons_enabled=false},
},
lualine_c = {
-- Displays filename only when window is wider then 80
{'filename', condition=function() return vim.fn.winwidth(0) > 80 end},
}
<
Component specific options~
In addition, some components have unique options.
• diagnostics~
• sources (nil)
displays diagnostic count from defined source.
array containing one or many string from set
{'nvim_lsp', 'coc', 'ale', 'vim_lsp'}
• sections ({'error', 'warn', 'info'})
displays diagnostics of defined severity.
array containing one or many string from set
{'error', 'warn', 'info'}
• color_error (DiffDelete foreground color)
changes diagnostic's error section foreground color.
color in #rrggbb format
• color_warn (DiffText foreground color)
changes diagnostic's warn section foreground color
color in #rrggbb format
• color_info (Normal foreground color)
changes diagnostic's info section foreground color
color in #rrggbb format
• symbols
(icons_enabled: true -> {error = ' ', warn = ' ', info = ' '})
(icons_enabled: false -> {error = 'E:', warn = 'W:', info = 'I:'})
changes diagnostic's symbol characters. You can set one or more symbols
for each level.
>
{
'diagnostics',
symbols = {
-- set the error symbol and use defaults for warn and info.
error = '!!',
},
}
<
• filename~
• file_status (true)
Displays file status (readonly status, modified status)
• full_path (false)
Displays relative path if set to `true`, absolute path if set to `false`
• shorten (true)
if `full_path` is `true` and `shorten` is `false` it shortens
absolute path `aaa/bbb/ccc/file` to `a/b/c/file`
• symbols (`{modified = '[+]', readonly = '[-]'}`)
changes status symbols
• fileformat~
• icons_enabled (true)
Whether to displays icon before component. Colors
are automaticaly extracted from colorscheme . If you
want to change any of those you can use options given below.
• diff~
• colored (true)
displays diff status in color if set to `true`
• color_added (DiffAdd foreground color)
Changes diff's added section foreground color
Color in `#rrggbb` format
• color_modified (DiffChange foreground color)
Changes diff's changed section foreground color
Color in `#rrggbb` format
• color_removed (DiffDelete foreground color)
Changes diff's removed section foreground color
Color in `#rrggbb` format
• symbols (`{added = '+', modified = '~', removed = '-'}`)
changes diff's symbols
Color in `#rrggbb` format
<
2021-04-06 14:03:41 +00:00
Component specific options can only be set with component configs.
Example:~
>
sections = {
lualine_b = {
2021-04-06 14:03:41 +00:00
{'branch', icon = '', upper = true, color = {fg = '#00aa22'}}, {
'filename',
full_name = true,
shorten = true,
format = function(name)
-- Capitalize first charecter of filename to capital.
local path, fname = name:match('(.*/)(.*)')
if not path then
path = '';
fname = name
end
return path .. fname:sub(1, 1):upper() .. fname:sub(2, #fname)
end
}
}
}
2021-03-06 15:03:00 +00:00
-------------------------------------------------------------------------------
USING TABLINE AS STATUSLINE *lualine_using_tabline*
You can use lualine to display components in tabline .
The sections, configurations and highlights are same as statusline.
>
tabline = {
2021-03-06 15:03:00 +00:00
lualine_a = { },
lualine_b = { 'branch' },
lualine_c = { 'filename' },
lualine_x = { },
lualine_y = { },
lualine_z = { },
}
<
2021-03-06 15:03:00 +00:00
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
instead of lualine.sections & lualine.inactive_sections and setting them to empty
>
tabline = {
2021-03-06 15:03:00 +00:00
......
}
sections = {}
inactive_sections = {}
2021-03-06 15:03:00 +00:00
<
2021-02-09 14:27:42 +00:00
--------------------------------------------------------------------------------
LOADING PLUGIN EXTENSIONS *lualine_loading_plugin_extensions*
2021-02-09 14:27:42 +00:00
Lualine extensions change statusline appearance for a window/buffer with
a plugin loaded e.g. junegunn/fzf.vim (https://github.com/junegunn/fzf.vim)
By default no plugin extension are loaded to improve performance. If you are
using a plugin which is supported you can load it this way:
>
extensions = { 'fzf' }
2021-02-09 14:27:42 +00:00
<
Available extensions
* fugitive
* fzf
* nerdtree
* chadtree
* nvim-tree
2021-02-09 14:27:42 +00:00
--------------------------------------------------------------------------------
CONGIG EXAMPLES *lualine_config_examples*
2021-02-09 14:27:42 +00:00
Lua config example
2021-02-09 14:27:42 +00:00
>
use {
'hoob3rt/lualine.nvim',
requires = {'kyazdani42/nvim-web-devicons', opt = true},
config = function()
require('lualine').setup{
2021-04-06 14:03:41 +00:00
options = {
theme = 'gruvbox',
section_separators = {'', ''},
component_separators = {'', ''},
icons_enabled = true,
},
sections = {
lualine_a = { {'mode', upper = true} },
lualine_b = { {'branch', icon = ''} },
lualine_c = { {'filename', file_status = true} },
lualine_x = { 'encoding', 'fileformat', 'filetype' },
lualine_y = { 'progress' },
lualine_z = { 'location' },
},
inactive_sections = {
lualine_a = { },
lualine_b = { },
lualine_c = { 'filename' },
lualine_x = { 'location' },
lualine_y = { },
lualine_z = { }
},
extensions = { 'fzf' }
2021-02-09 14:27:42 +00:00
}
end
}
2021-02-09 14:27:42 +00:00
<
--------------------------------------------------------------------------------
Vimscript config example
2021-02-09 14:27:42 +00:00
>
let g:lualine = {
2021-04-06 14:03:41 +00:00
\'options' : {
\ 'theme' : 'gruvbox',
\ 'section_separators' : ['', ''],
\ 'component_separators' : ['', ''],
\ 'icons_enabled' : v:true,
\},
\'sections' : {
\ 'lualine_a' : [ ['mode', {'upper': v:true,},], ],
\ 'lualine_b' : [ ['branch', {'icon': '',}, ], ],
\ 'lualine_c' : [ ['filename', {'file_status': v:true,},], ],
\ 'lualine_x' : [ 'encoding', 'fileformat', 'filetype' ],
\ 'lualine_y' : [ 'progress' ],
\ 'lualine_z' : [ 'location' ],
\},
\'inactive_sections' : {
\ 'lualine_a' : [ ],
\ 'lualine_b' : [ ],
\ 'lualine_c' : [ 'filename' ],
\ 'lualine_x' : [ 'location' ],
\ 'lualine_y' : [ ],
\ 'lualine_z' : [ ],
\},
\'extensions' : [ 'fzf' ],
\}
lua require("lualine").setup()
2021-02-09 14:27:42 +00:00
<
-------------------------------------------------------------------------------
vim:tw=80:sw=4:ts=8:noet:ft=help:norl:et: