path: root/start/indent-blankline-2.20.4/doc/indent_blankline.txt

*indent_blankline.txt*        Show vertical lines for indent on empty lines


Author: Lukas Reineke <lukas.reineke@protonmail.com>
Version: 2.20.4

==============================================================================
CONTENTS                                                    *indent-blankline*

  1. Introduction                          |indent-blankline-introduction|
  2. Highlights                            |indent-blankline-highlights|
  3. Setup                                 |indent-blankline-setup|
  4. Variables                             |indent-blankline-variables|
  5. Commands                              |indent-blankline-commands|
  6. License                               |indent-blankline-license|

==============================================================================
 1. INTRODUCTION                               *indent-blankline-introduction*

This plugin adds indentation guides to all lines (including empty lines).

It uses Neovim's virtual text feature and **no conceal**

This plugin requires Neovim 0.5 or higher. It makes use of Neovim only
features so it will not work in Vim.
There is a legacy version of the plugin that supports Neovim 0.4 under the
branch `version-1`

==============================================================================
 2. HIGHLIGHTS                                   *indent-blankline-highlights*

To change the highlighting of either the indent character, or the whitespace
between indent characters, define or update these highlight groups.

------------------------------------------------------------------------------
IndentBlanklineChar                                   *hl-IndentBlanklineChar*

    Highlight of indent character.

    Default: takes guifg color from 'Whitespace'                             ~

    Example: >

        highlight IndentBlanklineChar guifg=#00FF00 gui=nocombine

------------------------------------------------------------------------------
IndentBlanklineSpaceChar                         *hl-IndentBlanklineSpaceChar*

    Highlight of space character.

    Default: takes guifg color from 'Whitespace'                             ~

    Example: >

        highlight IndentBlanklineSpaceChar guifg=#00FF00 gui=nocombine

------------------------------------------------------------------------------
IndentBlanklineSpaceCharBlankline       *hl-IndentBlanklineSpaceCharBlankline*

    Highlight of space character on blank lines.

    Default: takes guifg color from 'Whitespace'                             ~

    Example: >

        highlight IndentBlanklineSpaceCharBlankline guifg=#00FF00 gui=nocombine

------------------------------------------------------------------------------
IndentBlanklineContextChar                     *hl-IndentBlanklineContextChar*

    Highlight of indent character when base of current context.
    Only used when |g:indent_blankline_show_current_context| is active

    Default: takes guifg color from 'Label'                             ~

    Example: >

        highlight IndentBlanklineContextChar guifg=#00FF00 gui=nocombine

------------------------------------------------------------------------------
IndentBlanklineContextSpaceChar           *hl-IndentBlanklineContextSpaceChar*

    Highlight of space characters one indent level of the current context.
    Only used when |g:indent_blankline_show_current_context| is active

    Default: takes guifg color from 'Label'                             ~

    Example: >

        highlight IndentBlanklineContextSpaceChar guifg=#00FF00 gui=nocombine

------------------------------------------------------------------------------
IndentBlanklineContextStart                     *hl-IndentBlanklineContextStart*

    Highlight of the first line of the current context.
    Only used when |g:indent_blankline_show_current_context_start| is active

    Default: takes guifg color from 'Label' as guisp and adds underline      ~

    Note: You need to have set |gui-colors| for the default to work.

    Example: >

        highlight IndentBlanklineContextStart guisp=#00FF00 gui=underline

------------------------------------------------------------------------------

Note: Define your highlight group after setting colorscheme or your colorscheme will clear your highlight group

When defining the highlight group, it is important to set |nocombine| as a
gui option. This is to make sure the character does not inherit gui options
from the underlying text, like italic or bold.

Highlight groups get reset on |ColorScheme| autocommand, if both fg and bg
are empty.

The set more than one highlight group that changes based on indentation level,
see:
|g:indent_blankline_char_highlight_list|
|g:indent_blankline_space_char_highlight_list|
|g:indent_blankline_space_char_blankline_highlight_list|

==============================================================================
 3. SETUP                                             *indent-blankline-setup*

To configure indent-blankline, either run the setup function, or set variables
manually.
The setup function has a single table as argument, keys of the table match the
|indent-blankline-variables| without the `indent_blankline_` part.

Example: >

    require("indent_blankline").setup {
        -- for example, context is off by default, use this to turn it on
        show_current_context = true,
        show_current_context_start = true,
    }

==============================================================================
 4. VARIABLES                                     *indent-blankline-variables*

All variables can be set globally |g:var|, per tab |t:var|, or per buffer |b:var|

------------------------------------------------------------------------------
g:indent_blankline_char                              *g:indent_blankline_char*

    Specifies the character to be used as indent line.
    Not used if |g:indent_blankline_char_list| is not empty.

    When set explicitly to empty string (""), no indentation character is
    displayed at all, even when |g:indent_blankline_char_list| is not empty.
    This can be useful in combination with
    |g:indent_blankline_space_char_highlight_list| to only rely on different
    highlighting of different indentation levels without needing to show a
    special character.

    Also set by |g:indentLine_char|

    Default: '│'                                                             ~

    Example: >

        let g:indent_blankline_char = '|'

------------------------------------------------------------------------------
g:indent_blankline_char_blankline          *g:indent_blankline_char_blankline*

    Specifies the character to be used as indent line for blanklines.
    Not used if |g:indent_blankline_char_list_blankline| is not empty.

    Default: ''                                                             ~

    Example: >

        let g:indent_blankline_char_blankline = '┆'

------------------------------------------------------------------------------
g:indent_blankline_char_list                    *g:indent_blankline_char_list*

    Specifies a list of characters to be used as indent line for
    each indentation level.
    Ignored if the value is an empty list.

    Also set by |g:indentLine_char_list|

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_char_list = ['|', '¦', '┆', '┊']

------------------------------------------------------------------------------
g:indent_blankline_char_list_blankline *g:indent_blankline_char_list_blankline*

    Specifies a list of characters to be used as indent line for
    each indentation level on blanklines.
    Ignored if the value is an empty list.

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_char_list_blankline = ['|', '¦', '┆', '┊']

------------------------------------------------------------------------------

g:indent_blankline_char_highlight_list *g:indent_blankline_char_highlight_list*

    Specifies the list of character highlights for each indentation level.
    Ignored if the value is an empty list.

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_char_highlight_list = ['Error', 'Function']

------------------------------------------------------------------------------
g:indent_blankline_space_char_blankline *g:indent_blankline_space_char_blankline*

    Specifies the character to be used as the space value in between indent
    lines when the line is blank.

    Default: An empty space character                                        ~

    Example: >

        let g:indent_blankline_space_char_blankline = ' '

------------------------------------------------------------------------------

g:indent_blankline_space_char_highlight_list *g:indent_blankline_space_char_highlight_list*

    Specifies the list of space character highlights for each indentation
    level.
    Ignored if the value is an empty list.

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_space_char_highlight_list = ['Error', 'Function']

------------------------------------------------------------------------------

g:indent_blankline_space_char_blankline_highlight_list *g:indent_blankline_space_char_blankline_highlight_list*

    Specifies the list of space character highlights for each indentation
    level when the line is empty.
    Ignored if the value is an empty list.

    Also set by |g:indent_blankline_space_char_highlight_list|

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_space_char_blankline_highlight_list = ['Error', 'Function']

------------------------------------------------------------------------------
g:indent_blankline_use_treesitter          *g:indent_blankline_use_treesitter*

    Use treesitter to calculate indentation when possible.
    Requires treesitter

    Default: false                                                           ~

    Example: >

        let g:indent_blankline_use_treesitter = v:true

------------------------------------------------------------------------------
g:indent_blankline_indent_level              *g:indent_blankline_indent_level*

    Specifies the maximum indent level to display.

    Also set by |g:indentLine_indentLevel|

    Default: 10                                                              ~

    Example: >

        let g:indent_blankline_indent_level = 4

------------------------------------------------------------------------------
g:indent_blankline_max_indent_increase  *g:indent_blankline_max_indent_increase*

    The maximum indent level increase from line to line.
    Set this option to 1 to make aligned trailing multiline comments not
    create indentation.

    Default: g:indent_blankline_indent_level                                 ~

    Example: >

        let g:indent_blankline_max_indent_increase = 1

------------------------------------------------------------------------------
g:indent_blankline_show_first_indent_level *g:indent_blankline_show_first_indent_level*

    Displays indentation in the first column.

    Default: v:true                                                         ~

    Example: >

        let g:indent_blankline_show_first_indent_level = v:false

------------------------------------------------------------------------------
g:indent_blankline_show_trailing_blankline_indent *g:indent_blankline_show_trailing_blankline_indent*

    Displays a trailing indentation guide on blank lines, to match the
    indentation of surrounding code.
    Turn this off if you want to use background highlighting instead of chars.

    Default: v:true                                                         ~

    Example: >

        let g:indent_blankline_show_trailing_blankline_indent = v:false

------------------------------------------------------------------------------
g:indent_blankline_show_end_of_line      *g:indent_blankline_show_end_of_line*

    Displays the end of line character set by |listchars| instead of the
    indent guide on line returns.

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_show_end_of_line = v:true

------------------------------------------------------------------------------
g:indent_blankline_show_foldtext            *g:indent_blankline_show_foldtext*

    Displays the full fold text instead of the indent guide on folded lines.

    Note: there is no autocommand to subscribe to changes in folding. This
          might lead to unexpected results. A possible solution for this is to
          remap folding bindings to also call |IndentBlanklineRefresh|

    Default: v:true                                                         ~

    Example: >

        let g:indent_blankline_show_foldtext = v:false

------------------------------------------------------------------------------
g:indent_blankline_enabled                        *g:indent_blankline_enabled*

    Turns this plugin on or off.

    Also set by |g:indentLine_enabled|

    Note: the buffer version of this variable overwrites all other
          enabled/disabled checks.

    Default: v:true                                                          ~

    Example: >

        let g:indent_blankline_enabled = v:false

------------------------------------------------------------------------------
g:indent_blankline_disable_with_nolist *g:indent_blankline_disable_with_nolist*

    When true, automatically turns this plugin off when |nolist| is set.
    When false, setting |nolist| will keep displaying indentation guides but
    removes whitespace characters set by |listchars|.

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_disable_with_nolist = v:true

------------------------------------------------------------------------------
g:indent_blankline_filetype                      *g:indent_blankline_filetype*

    Specifies a list of |filetype| values for which this plugin is enabled.
    All |filetypes| are enabled if the value is an empty list.

    Also set by |g:indentLine_fileType|

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_filetype = ['vim']

------------------------------------------------------------------------------
g:indent_blankline_filetype_exclude      *g:indent_blankline_filetype_exclude*

    Specifies a list of |filetype| values for which this plugin is not enabled.
    Ignored if the value is an empty list.

    Also set by |g:indentLine_fileTypeExclude|

    Default: [                                                               ~
        "lspinfo",                                                           ~
        "packer",                                                            ~
        "checkhealth",                                                       ~
        "help",                                                              ~
        "man",                                                               ~
        "",                                                                  ~
    ]                                                                        ~

    Example: >

        let g:indent_blankline_filetype_exclude = ['help']

------------------------------------------------------------------------------
g:indent_blankline_buftype_exclude        *g:indent_blankline_buftype_exclude*

    Specifies a list of |buftype| values for which this plugin is not enabled.
    Ignored if the value is an empty list.

    Also set by |g:indentLine_bufTypeExclude|

    Default: [                                                               ~
        "terminal",                                                          ~
        "nofile",                                                            ~
        "quickfix",                                                          ~
        "prompt",                                                            ~
    ]                                                                        ~

    Example: >

        let g:indent_blankline_buftype_exclude = ['terminal']

------------------------------------------------------------------------------
g:indent_blankline_bufname_exclude        *g:indent_blankline_bufname_exclude*

    Specifies a list of buffer names (file name with full path) for which
    this plugin is not enabled.
    A name can be regular expression as well.

    Also set by |g:indentLine_bufNameExclude|

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_bufname_exclude = ['README.md', '.*\.py']

------------------------------------------------------------------------------
g:indent_blankline_strict_tabs                *g:indent_blankline_strict_tabs*

    When on, if there is a single tab in a line, only tabs are used to
    calculate the indentation level.
    When off, both spaces and tabs are used to calculate the indentation
    level.
    Only makes a difference if a line has a mix of tabs and spaces for
    indentation.

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_strict_tabs = v:true

------------------------------------------------------------------------------
g:indent_blankline_show_current_context *g:indent_blankline_show_current_context*

    When on, use treesitter to determine the current context. Then show the
    indent character in a different highlight.

    Note: Requires https://github.com/nvim-treesitter/nvim-treesitter to be
          installed

    Note: With this option enabled, the plugin refreshes on |CursorMoved|,
          which might be slower

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_show_current_context = v:true

------------------------------------------------------------------------------
g:indent_blankline_show_current_context_start *g:indent_blankline_show_current_context_start*

    Applies the |hl-IndentBlanklineContextStart| highlight group to the first
    line of the current context.
    By default this will underline.

    Note: Requires https://github.com/nvim-treesitter/nvim-treesitter to be
          installed

    Note: You need to have set |gui-colors| and it depends on your terminal
          emulator if this works as expected.
          If you are using kitty and tmux, take a look at this article to
          make it work
          http://evantravers.com/articles/2021/02/05/curly-underlines-in-kitty-tmux-neovim/

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_show_current_context_start = v:true

------------------------------------------------------------------------------
g:indent_blankline_show_current_context_start_on_current_line *g:indent_blankline_show_current_context_start_on_current_line*

    Shows |g:indent_blankline_show_current_context_start| even when the cursor
    is on the same line

    Default: v:true                                                         ~

    Example: >

        let g:indent_blankline_show_current_context_start_on_current_line = v:false

------------------------------------------------------------------------------
g:indent_blankline_context_char              *g:indent_blankline_context_char*

    Specifies the character to be used for the current context indent line.
    Not used if |g:indent_blankline_context_char_list| is not empty.

    Useful to have a greater distinction between the current context indent
    line and others.

    Also useful in combination with |g:indent_blankline_char| set to empty string
    (""), as this allows only the current context indent line to be shown.

    Default: g:indent_blankline_char                                         ~

    Example: >

        let g:indent_blankline_context_char = '┃'

------------------------------------------------------------------------------
g:indent_blankline_context_char_blankline *g:indent_blankline_context_char_blankline*

    Equivalent of |g:indent_blankline_char_blankline| for
    |g:indent_blankline_context_char|.

    Default: ''                                                             ~

    Example: >

        let g:indent_blankline_context_char_blankline = '┆'

------------------------------------------------------------------------------
g:indent_blankline_context_char_list    *g:indent_blankline_context_char_list*

    Equivalent of |g:indent_blankline_char_list| for
    |g:indent_blankline_context_char|.

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_context_char_list = ['┃', '║', '╬', '█']

------------------------------------------------------------------------------
g:indent_blankline_context_char_list_blankline *g:indent_blankline_context_char_list_blankline*

    Equivalent of |g:indent_blankline_char_list_blankline| for
    |g:indent_blankline_context_char_blankline|.

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_context_char_list_blankline = ['┃', '║', '╬', '█']

------------------------------------------------------------------------------
g:indent_blankline_context_highlight_list *g:indent_blankline_context_highlight_list*

    Specifies the list of character highlights for the current context at
    each indentation level.
    Ignored if the value is an empty list.

    Only used when |g:indent_blankline_show_current_context| is active

    Default: []                                                              ~

    Example: >

        let g:indent_blankline_context_highlight_list = ['Error', 'Warning']

------------------------------------------------------------------------------
g:indent_blankline_char_priority            *g:indent_blankline_char_priority*

    Specifies the |extmarks| priority for chars.

    Default: 1                                                               ~

    Example: >

        let g:indent_blankline_char_priority = 50

------------------------------------------------------------------------------
g:indent_blankline_context_start_priority *g:indent_blankline_context_start_priority*

    Specifies the |extmarks| priority for the context start.

    Default: 10000                                                           ~

    Example: >

        let g:indent_blankline_context_start_priority = 50

------------------------------------------------------------------------------
g:indent_blankline_context_patterns      *g:indent_blankline_context_patterns*

    Specifies a list of lua patterns that are used to match against the
    treesitter |tsnode:type()| at the cursor position to find the current
    context.

    To learn more about how lua pattern work, see here:
    https://www.lua.org/manual/5.1/manual.html#5.4.1

    Only used when |g:indent_blankline_show_current_context| is active

    Default: [                                                               ~
        "class",                                                             ~
        "^func",                                                             ~
        "method",                                                            ~
        "^if",                                                               ~
        "while",                                                             ~
        "for",                                                               ~
        "with",                                                              ~
        "try",                                                               ~
        "except",                                                            ~
        "arguments",                                                         ~
        "argument_list",                                                     ~
        "object",                                                            ~
        "dictionary",                                                        ~
        "element",                                                           ~
        "table",                                                             ~
        "tuple",                                                             ~
        "do_block",                                                          ~
    ]                                                                        ~

    Example: >

        let g:indent_blankline_context_patterns = ['^if']

------------------------------------------------------------------------------
g:indent_blankline_use_treesitter_scope *g:indent_blankline_use_treesitter_scope*

    Instead of using |g:indent_blankline_context_patterns|, use the current
    scope defined by nvim-treesitter as the context.

    Default: false                                                           ~

    Example: >

        let g:indent_blankline_use_treesitter_scope = true

------------------------------------------------------------------------------
g:indent_blankline_context_pattern_highlight *g:indent_blankline_context_pattern_highlight*

    Specifies a map of patterns set in
    |g:indent_blankline_context_patterns| to highlight groups.
    When the current matching context pattern is in the map, the context
    will be highlighted with the corresponding highlight group.

    Only used when |g:indent_blankline_show_current_context| is active

    Default: {}                                                              ~

    Example: >

        let g:indent_blankline_context_pattern_highlight = {'function': 'Function'}

------------------------------------------------------------------------------
g:indent_blankline_viewport_buffer        *g:indent_blankline_viewport_buffer*

    Sets the buffer of extra lines before and after the current viewport that
    are considered when generating indentation and the context.

    Default: 10                                                              ~

    Example: >

        let g:indent_blankline_viewport_buffer = 20

------------------------------------------------------------------------------
g:indent_blankline_disable_warning_message *g:indent_blankline_disable_warning_message*

    Turns deprecation warning messages off.

    Default: v:false                                                         ~

    Example: >

        let g:indent_blankline_disable_warning_message = v:true

==============================================================================
 5. COMMANDS                                       *indent-blankline-commands*

------------------------------------------------------------------------------
:IndentBlanklineRefresh[!]                            *IndentBlanklineRefresh*

    Refreshes the indent guides for the current buffer.
    Run this with |autocmd| when the file changes. For example after a plugin
    formats the file.

    With bang (IndentBlanklineRefresh!) refreshes the indent guides globally.

    By default it is run for:
      1. |FileChangedShellPost| *
      2. |TextChanged| *
      3. |TextChangedI| *
      4. |CompleteChanged| *
      5. |BufWinEnter| *
      6. |Filetype| *
      7. |OptionSet| list,listchars,shiftwidth,tabstop,expandtab

    Example: >

        autocmd User ALEFixPost IndentBlanklineRefresh

------------------------------------------------------------------------------
:IndentBlanklineRefreshScroll[!]                *IndentBlanklineRefreshScroll*

    Refreshes the indent guides for the current buffer. But tries to reuse as
    indent guides that already exist. Only used if we are sure the buffer
    content did not change.

    With bang (IndentBlanklineRefresh!) refreshes the indent guides globally.

    By default it is run for:
      1. |WinScrolled| *

    Example: >

        autocmd WinScrolled * IndentBlanklineRefreshScroll

------------------------------------------------------------------------------
:IndentBlanklineEnable[!]                               *IndentBlanklineEnable*

    Enables this plugin for the current buffer.
    This overwrites any include/exclude rules.

    With bang (IndentBlanklineEnable!) enables this plugin globally

------------------------------------------------------------------------------
:IndentBlanklineDisable[!]                            *IndentBlanklineDisable*

    Disables this plugin for the current buffer.
    This overwrites any include/exclude rules.

    With bang (IndentBlanklineDisable!) disables this plugin globally

------------------------------------------------------------------------------
:IndentBlanklineToggle[!]                              *IndentBlanklineToggle*

    Toggles between |IndentBlanklineEnable| and |IndentBlanklineDisable|.

    With bang (IndentBlanklineToggle!) toggles globally

==============================================================================
 6. LICENSE                                         *indent-blankline-license*

The MIT Licence
http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2023 Lukas Reineke

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

==============================================================================
vim:tw=78:ts=8:ft=help:norl