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 comparism...................|lualine_performance_comparism|
    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 COMPARISM                            *lualine_performance_comparism*

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*
>
    local lualine = require('lualine')
    lualine.status()
<

SETTING THEME                                          *lualine_setting_theme*
>
    lualine.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).

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

or disable it
>
    lualine.section_separators = ''
    lualine.component_separators = ''
<

CHANGING COMPONENTS IN LUALINE SECTIONS            *lualine_changing_components*


Lualine defaults~
>
    lualine.sections = {
      lualine_a = { 'mode' },
      lualine_b = { 'branch' },
      lualine_c = { 'filename' },
      lualine_x = { 'encoding', 'fileformat', 'filetype' },
      lualine_y = { 'progress' },
      lualine_z = { 'location'  },
    }
    lualine.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
        *   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
    lualine.sections.lualine_a = { hello }
<
Using vim functions as lualine component~

You can use vim functions as a lualine component

>
    lualine.sections.lualine_b = { 'FugitiveHead' }
<

Using variables as lualine component~

You can use variables from vim and lua globals as a lualine component
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

>
    lualine.sections.lualine_b = { 'g:coc_status', 'bo:filetype' }
    lualine.sections.lualine_x = { 'vim.bo.fileencoding' }
<

--------------------------------------------------------------------------------
CUSTOM OPTIONS FOR COMPONENTS                        *lualine_custom_options*


Options for components~
======================

Global Default options~
----------------------

Default options act as default for all components

icons_enabled (Default: true)

  Displays icons on components
  You should have nerd-fonts supported fonts to see
  icons properly.
  Suported by branch, fileformat, filetype, location

  Example:
    `lualine.options.icons_enabled = true`

Genaral options~
---------------
These options are available for all components.

option       (default_value)
------       ---------------

  • padding       (1)
    spaces on left and right

  • left_padding  (1)
    spaces on left

  • icon          (depends on component)
    displays an icon infront of a component

  • icons_enabled (true)
    whether to show icon(if available)

  • right_padding (1)
    spaces on right

  • separator ('|')
    which separator to use at end of component

  • upper         (false)
    Displayed in upper case

  • lower         (false)
    Displayed in lower case

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

  • 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


Component specific options~
--------------------------
These options are available for specific components only.
List of options are given below.


  • diagnostics~
    • sources  (nil)
      displays diagnostic count from defined source.
      array containing one or many string from set
      {'nvim_lsp', 'coc', 'ale'}

    • 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)
      Whether to display filemodified status in filename

    • shorten      (true)
      Whether to display full/relative path with filename

    • full_path  (false)
      Whether to display full path when shorten is false

  • 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)
      Whether to show colors

    • color_added (DiffAdd foreground color)
      Foreground color of added section
      Color in #rrggbb format

    • color_modified (DiffChange foreground color)
      Foreground color of modified section
      Color in #rrggbb format

    • color_removed (DiffDelete foreground color)
      Foreground color of removed section
      Color in #rrggbb format

    • symbols ({added = '+', modified = '~', removed = '-'})
      Changes diff's symbol characters. You can set some symbols partly.
      Color in #rrggbb format
      >
          {
            'diff',
            -- set the added symbol and use defaults for modified and removed.
            symbols = {
              added = 'A',
            },
          }
<

Example:~
>
  lualine.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.

>
    lualine.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
>
    lualine.tabline = {
    ......
      }
    lualine.sections = {}
    lualine.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:
>
    lualine.extensions = { 'fzf' }
<

All available extensions are listed in EXTENSIONS.md (./EXTENSIONS.md)

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

FULL CONFIG EXAMPLE USING PACKER.NVIM *lualine_config_example_using_packer.nvim*


packer config
>
      use {
        'hoob3rt/lualine.nvim',
        requires = {'kyazdani42/nvim-web-devicons', opt = true},
        config = function()
        require('lualine').status{
            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' }
          }
        end
      }
<


--------------------------------------------------------------------------------
FULL CONFIG EXAMPLE INSIDE VIML        *lualine_full_config_example_inside_viml*


vimrc config
>
    let g:lualine = {
        \'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").status()
<

--------------------------------------------------------------------------------
CONTRIBUTING                                              *lualine_contributing*

Please read CONTRIBUTING.md (./CONTRIBUTING.md) before contributing.

You can check this (https://github.com/hoob3rt/lualine.nvim/projects/3) out if you want to see what is currently being worked on.

Feel free to create an issue/pr if you want to see anything else implemented.

--------------------------------------------------------------------------------
SCREENSHOTS                                                *lualine_screenshots*

Here is a preview of how lualine can look like.

- normal:
  https://user-images.githubusercontent.com/41551030/103467902-06b44080-4d54-11eb-89db-6d3bebf449fa.png
- insert:
  https://user-images.githubusercontent.com/41551030/103467914-1764b680-4d54-11eb-9e3d-528d3568dce7.png
- visual:
  https://user-images.githubusercontent.com/41551030/103467916-23507880-4d54-11eb-804e-5b1c4d6e3db3.png
- command:
  https://user-images.githubusercontent.com/41551030/103467919-2ba8b380-4d54-11eb-8585-6c667fd5082e.png
- replace:
  https://user-images.githubusercontent.com/41551030/103467925-32372b00-4d54-11eb-88d6-6d39c46854d8.png

Screenshots of all available themes are listed in THEMES.md (./THEMES.md)


-------------------------------------------------------------------------------
vim:tw=80:sw=4:ts=8:noet:ft=help:norl:noet: