lualine.nvim/doc/lualine.txt

*lualine.txt*
						        *lualine* *lualine.nvim*

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                                                     *lualline-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. Loading plugin extensions.....|lualine-loading_plugin_extensions|
	1.3.8  Config examples.........................|lualine-config_examples|
	    1.3.8.1. Packer.nvim......|lualine-config_example_using_packer.nvim|
            1.3.8.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 a separator between components in given section, the default
separator is `|`. You can change the separator this way:
>
    lualine.options.separator = '|'
<

or disable it
>
    lualine.options.separator = ''
<

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
        *   encoding
        *   fileformat
        *   filename
        *   filetype
        *   location
        *   mode
        *   progress
    plugin~
        *   signify


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

  • 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

Example:~
>
  lualine.sections.lualine_b = {
    {
      'branch',
      icon = '',
      upper = true,
      color = { fg = '#00aa22' }
    },
    {
      'filename',
      full_name = true,
      relative = true,
      format = function(name)
        -- Capitalize first charecter of filename to capital.
        local path, fname = name:match('(.*/)(.*)')
        rerurn path .. fname[1, 1]:upper() .. fname[2, #fname]
      end
    }
  }
<

--------------------------------------------------------------------------------
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()
          local lualine = require('lualine')
	  lualine.options = {
	    theme = 'gruvbox',
	    separator = '|',
	    icons_enabled = true,
	  }
          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 = {   }
          }
          lualine.extensions = { 'fzf' }
          lualine.status()
        end
      }
<


--------------------------------------------------------------------------------
FULL CONFIG EXAMPLE INSIDE VIML        *lualine-full_config_example_inside_viml*


vimrc config
>
    lua << EOF
    local lualine = require('lualine')
        lualine.options = {
          theme = 'gruvbox',
          separator = '|',
          icons_enabled = true,
        }
        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 = {   }
        }
        lualine.extensions = { 'fzf' }
        lualine.status()
    EOF
<

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