lualine.nvim/doc/lualine.txt

*lualine.txt*                A 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.NVIM                                              *lualine_lualine.nvim*


   __         __  __     ______     __         __     __   __     ______
  /\ \       /\ \/\ \   /\  __ \   /\ \       /\ \   /\ "-.\ \   /\  ___\
  \ \ \____  \ \ \_\ \  \ \  __ \  \ \ \____  \ \ \  \ \ \-.  \  \ \  __\
   \ \_____\  \ \_____\  \ \_\ \_\  \ \_____\  \ \_\  \ \_\\"\_\  \ \_____\
    \/_____/   \/_____/   \/_/\/_/   \/_____/   \/_/   \/_/ \/_/   \/_____/




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|
    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|
        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|

================================================================================
PERFORMANCE COMPARISON                          *lualine_performance_comparison*

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*

VIM-PLUG                                                      *lualine_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                                                *lualine_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.
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*
>
    require('lualine').setup{}
<

SETTING THEME                                          *lualine_setting_theme*
>
    options = {theme = 'gruvbox'}
<

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).

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*

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.
>
    options = {
      section_separators = {'', ''},
      component_separators = {'', ''}
    }

or disable it
>
    options = {section_separators = '', component_separators = ''}
<

CHANGING COMPONENTS IN LUALINE SECTIONS            *lualine_changing_components*


Lualine defaults~
>
    sections = {
      lualine_a = { 'mode' },
      lualine_b = { 'branch' },
      lualine_c = { 'filename' },
      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 = {  }
    }
<




Available components~

    general~
        *   branch (git branch)
        *   diagnostics (diagnostics count from your prefered source)
        *   encoding (file encoding)
        *   fileformat (file format)
        *   filename
        *   filetype
        *   hostname
        *   location (location in file in line:column format)
        *   mode (vim mode)
        *   progress (%progress in file)
        *   diff (git diff status)


--------------------------------------------------------------------------------
BUILDING YOUR COMPONENTS                           *lualine_custom_components*


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}}
<
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~
======================

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~

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

  • 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

  • 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

  • disabled_filetypes   ({})
    Disables lualine for specific filetypes. It works on entire
    statusline instead of on a single component.

  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

  • 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.

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)

    • path (0)
      filename `path` option: 0 = just filename, 1 = relative path, 2 = absolute path

    • symbols (`{modified = '[+]', readonly = '[-]'}`)
      changes status symbols

  • filetype~
    • colored  (true)
      Displays filetype icon in color if set to `true`

  • 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
<
Component specific options can only be set with component configs.

Example:~
>
    sections = {
      lualine_b = {
        {'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
        }
      }
    }
-------------------------------------------------------------------------------
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 = {
      lualine_a = { },
      lualine_b = { 'branch' },
      lualine_c = { 'filename' },
      lualine_x = { },
      lualine_y = { },
      lualine_z = { },
    }
<
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 = {
    ......
      }
    sections = {}
    inactive_sections = {}
<


--------------------------------------------------------------------------------
LOADING PLUGIN EXTENSIONS                    *lualine_loading_plugin_extensions*

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' }
<

Available extensions
    * chadtree
    * fugitive
    * fzf
    * nerdtree
    * nvim-tree
    * quickfix

--------------------------------------------------------------------------------
CONGIG EXAMPLES                                        *lualine_config_examples*

Lua config example
>
    use {
    'hoob3rt/lualine.nvim',
    requires = {'kyazdani42/nvim-web-devicons', opt = true},
    config = function()
      require('lualine').setup{
        options = {
          theme = 'gruvbox',
          section_separators = {'', ''},
          component_separators = {'', ''},
          disabled_filetypes = {},
          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' }
      }
    end
    }
<
--------------------------------------------------------------------------------
Vimscript config example
>
    let g:lualine = {
        \'options' : {
        \  'theme' : 'gruvbox',
        \  'section_separators' : ['', ''],
        \  'component_separators' : ['', ''],
        \  'disabled_filetypes' : [],
        \  '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()
<
-------------------------------------------------------------------------------
vim:tw=80:sw=4:ts=8:noet:ft=help:norl:et: