gruvbox-material.txt

*gruvbox-material.txt*     Gruvbox with Material Palette
*gruvbox-material*
>
           ______                 __
          / ____/______  ___   __/ /_  ____  _  __
         / / __/ ___/ / / / | / / __ \/ __ \| |/_/
        / /_/ / /  / /_/ /| |/ / /_/ / /_/ />  <
        \____/_/   \__,_/ |___/_.___/\____/_/|_|

            __  ___      __            _       __
           /  |/  /___ _/ /____  _____(_)___ _/ /
          / /|_/ / __ `/ __/ _ \/ ___/ / __ `/ /
         / /  / / /_/ / /_/  __/ /  / / /_/ / /
        /_/  /_/\__,_/\__/\___/_/  /_/\__,_/_/
<

==============================================================================
CONTENTS                                     *gruvbox-material-contents*

Introduction                                 |gruvbox-material-introduction|
Installation                                 |gruvbox-material-installation|
Usage                                        |gruvbox-material-usage|
Configuration                                |gruvbox-material-configuration|
FAQ                                          |gruvbox-material-faq|

Note: Type |gO| in neovim to show the outline of contents.

==============================================================================
INTRODUCTION                                     *gruvbox-material-introduction*

Gruvbox Material is a modified version of Gruvbox, the contrast is adjusted to
be softer in order to protect developers' eyes.

There are 3 palettes available in this color scheme:

- `material`: Carefully designed to have a soft contrast.
- `mix`: Color palette obtained by calculating the mean of the other two.
- `original`: The color palette used in the original gruvbox.

This color scheme uses the `material` palette by default, you can use
|g:gruvbox_material_foreground| to switch to another palette.

Features~

- Carefully designed color palette for eye protection.
- Switch back to the original color palette whenever you like.
- Highly customizable.
- Rich support for common file types and plugins.
- Tree-sitter support.
- Semantic highlighting support.
- Italic support 🎉

==============================================================================
INSTALLATION                                     *gruvbox-material-installation*

Note: For better syntax highlighting support, consider installing one of the
following plugins additionally to this colorscheme:

	https://github.com/sheerun/vim-polyglot
	https://github.com/nvim-treesitter/nvim-treesitter.

------------------------------------------------------------------------------
Via a Plugin Manager

VIM-PLUG
>
    Plug 'sainnhe/gruvbox-material'
<
Refer to https://github.com/junegunn/vim-plug for further information.

LAZY.NVIM

In Neovim (Lua configuration):
>
    {
      'sainnhe/gruvbox-material',
      lazy = false,
      priority = 1000,
      config = function()
        -- Optionally configure and load the colorscheme
        -- directly inside the plugin declaration.
        vim.g.gruvbox_material_enable_italic = true
        vim.cmd.colorscheme('gruvbox-material')
      end
    }
<
Refer to https://github.com/folke/lazy.nvim for further information.

------------------------------------------------------------------------------
As a Native Vim Package

Users of Vim 8 and greater may leverage Vim's native |packages| system.

1. Create a new directory: `$ mkdir -p ~/.vim/pack/colors/opt`

2. Clone this repository: `$ git clone --depth 1 https://github.com/sainnhe/gruvbox-material.git ~/.vim/pack/colors/opt/gruvbox-material`

3. Generate help tags: `:helptags ~/.vim/pack/colors/opt/gruvbox-material/doc/`

4. Add `packadd! gruvbox-material` to your vimrc.

Note: If you install this color scheme to `pack/*/start` instead of
`pack/*/opt`, you still need to add `packadd! gruvbox-material` to your vimrc,
as discussed in the following issue:
https://github.com/sainnhe/gruvbox-material/issues/60

------------------------------------------------------------------------------
Manually

Users of Vim 7 and lower may install the colorscheme manually.

1. Clone the repository: `git clone --depth 1 https://github.com/sainnhe/gruvbox-material.git`

2. Copy `gruvbox-material/autoload/gruvbox_material.vim` to `~/.vim/autoload/`.

3. Copy `gruvbox-material/colors/gruvbox-material.vim` to `~/.vim/colors/`.

4. Copy `gruvbox-material/doc/gruvbox-material.txt` to `~/.vim/doc/` and
   execute `:helptags ~/.vim/doc/` to generate help tags.

5. To install the airline theme, copy
   `gruvbox-material/autoload/airline/themes/gruvbox_material.vim`
   to `~/.vim/autoload/airline/themes/`.
   https://github.com/vim-airline/vim-airline

6. To install the lightline theme,
   copy `gruvbox-material/autoload/lightline/colorscheme/gruvbox_material.vim`
   to `~/.vim/autoload/lightline/colorscheme/`.
   https://github.com/itchyny/lightline.vim

7. To install the lualine theme,
   copy `gruvbox-material/lua/lualine/themes/gruvbox-material.lua`
   to `~/.config/nvim/lua/lualine/themes/`.
   https://github.com/nvim-lualine/lualine.nvim

------------------------------------------------------------------------------
AUR

There are some packages available for Arch Linux users in AUR:

	https://aur.archlinux.org/pkgbase/vim-gruvbox-material-git (Vim)
	https://aur.archlinux.org/pkgbase/neovim-gruvbox-material-git (Neovim)

==============================================================================
USAGE                                                   *gruvbox-material-usage*

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

Vim~

    Put something like this in your vimrc:
>
        " Important!!
        if has('termguicolors')
          set termguicolors
        endif

        " For dark version.
        set background=dark

        " For light version.
        set background=light

        " Set contrast.
        " This configuration option should be placed before `colorscheme gruvbox-material`.
        " Available values: 'hard', 'medium'(default), 'soft'
        let g:gruvbox_material_background = 'soft'

        " For better performance
        let g:gruvbox_material_better_performance = 1

        colorscheme gruvbox-material
<
    See |gruvbox-material-configuration| for more configuration options.

    If you want to apply this color scheme temporarily, run this command in
    vim(this may cause broken colors):
>
        :colorscheme gruvbox-material
<
------------------------------------------------------------------------------

Airline~

    To enable [airline](https://github.com/vim-airline/vim-airline) color
    scheme, put this in your vimrc:
>
        let g:airline_theme = 'gruvbox_material'
<
    To apply it without reloading:
>
        :AirlineTheme gruvbox_material
<
------------------------------------------------------------------------------

Lightline~

    To enable [lightline](https://github.com/itchyny/lightline.vim) color
    scheme, put this in your vimrc:
>
        let g:lightline = {}
        let g:lightline.colorscheme = 'gruvbox_material'

        " Or this line:
        let g:lightline = {'colorscheme' : 'gruvbox_material'}
<
    To apply it without reloading:
>
        :let g:lightline.colorscheme = 'gruvbox_material'
        :call lightline#init()
        :call lightline#colorscheme()
<
------------------------------------------------------------------------------

Lualine~

    To enable [lualine](https://github.com/nvim-lualine/lualine.nvim) color
    scheme, put this in your init.lua:
>
        require'lualine'.setup {
          options = {
            theme = 'gruvbox-material'
          }
        }
<
    To apply it without reloading:
>
        :lua require'lualine'.setup {options = {theme = 'gruvbox-material'}}
<
==============================================================================
CONFIGURATION                                   *gruvbox-material-configuration*

Note: the configuration options should be placed before `colorscheme gruvbox-material`

E.g.
>
    if has('termguicolors')
      set termguicolors
    endif
    set background=light

    let g:gruvbox_material_background = 'soft'
    let g:gruvbox_material_better_performance = 1

    colorscheme gruvbox-material
    let g:lightline = {'colorscheme' : 'gruvbox_material'}
<
------------------------------------------------------------------------------
                                                 *g:gruvbox_material_background*
g:gruvbox_material_background~

The background contrast used in this color scheme.

    Type:               |String|
    Available values:   `'hard'`, `'medium'`, `'soft'`
    Default value:      `'medium'`

------------------------------------------------------------------------------
                                                 *g:gruvbox_material_foreground*
g:gruvbox_material_foreground~

The foreground color palette used in this color scheme.

- `material`: Carefully designed to have a soft contrast.
- `mix`: Color palette obtained by calculating the mean of the other two.
- `original`: The color palette used in the original gruvbox.

    Type:               |String|
    Available values:   `'material'`, `'mix'`, `'original'`
    Default value:      `'material'`

------------------------------------------------------------------------------
                                     *g:gruvbox_material_disable_italic_comment*
g:gruvbox_material_disable_italic_comment~

By default, italic is enabled in `Comment`. To disable italic in `Comment`, set
this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                                *g:gruvbox_material_enable_bold*
g:gruvbox_material_enable_bold~

To enable bold in function name just like the original gruvbox, set this
option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                              *g:gruvbox_material_enable_italic*
g:gruvbox_material_enable_italic~

To enable italic in this color scheme, set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Note: This option is designed to use with fonts that support cursive italics.
See |gruvbox-material-faq| for more information.

------------------------------------------------------------------------------
                                                     *g:gruvbox_material_cursor*
g:gruvbox_material_cursor~

Customize the cursor color, only works in GUI clients.

    Type:               |String|
    Available values:   `'auto'`, `'red'`, `'orange'`, `'yellow'`, `'green'`,
    `'aqua'`, `'blue'`, `'purple'`
    Default value:      `'auto'`

------------------------------------------------------------------------------
                                     *g:gruvbox_material_transparent_background*
g:gruvbox_material_transparent_background~

To use transparent background, set this option to `1`.

If you want more ui components to be transparent (for example, status line
background), set this option to `2`.

    Type:               |Number|
    Available values:   `0`, `1`, `2`
    Default value:      `0`

------------------------------------------------------------------------------
                                       *g:gruvbox_material_dim_inactive_windows*
g:gruvbox_material_dim_inactive_windows~

Dim inactive windows. Only works in Neovim currently.

When this option is used in conjunction with |g:gruvbox_material_show_eob| set
to 0, the end of the buffer will only be hidden inside the active window.
Inside inactive windows, the end of buffer filler characters will be visible
in dimmed symbols. This is due to the way Vim and Neovim handle
|hl-EndOfBuffer|.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                                     *g:gruvbox_material_visual*
g:gruvbox_material_visual~

Control the |hl-Visual| and the |hl-VisualNOS| highlight group.

    Type:               |String|
    Available values:   `'grey background'`, `'green background'`,
    `'blue background'`, `'red background'`, `'reverse'`
    Default value:      `'grey background'`

------------------------------------------------------------------------------
                                  *g:gruvbox_material_menu_selection_background*
g:gruvbox_material_menu_selection_background~

Customize the background color of |hl-PmenuSel| and |hl-WildMenu|.

    Type:               |String|
    Available values:   `'grey'`, `'red'`, `'orange'`, `'yellow'`, `'green'`,
    `'aqua'`, `'blue'`, `'purple'`
    Default value:      `'grey'`

------------------------------------------------------------------------------
                                     *g:gruvbox_material_sign_column_background*
g:gruvbox_material_sign_column_background~

By default, the color of sign column background is the same as normal text
background, but you can use a grey background by setting this option to `'grey'`.

    Type:               |String|
    Available values:   `'none'`, `'grey'`
    Default value:      `'none'`

------------------------------------------------------------------------------
                                           *g:gruvbox_material_spell_foreground*
g:gruvbox_material_spell_foreground~

By default, this color scheme won't color the foreground of |spell|, instead
colored under curls will be used. If you also want to color the foreground,
set this option to `'colored'`.

    Type:               |String|
    Available values:   `'none'`, `'colored'`
    Default value:      `'none'`

------------------------------------------------------------------------------
                                                *g:gruvbox_material_ui_contrast*
g:gruvbox_material_ui_contrast~

The contrast of line numbers, indent lines, etc.

    Type:               |String|
    Available values:   `'low'`, `'high'`
    Default value:      `'low'`

------------------------------------------------------------------------------
                                                   *g:gruvbox_material_show_eob*
g:gruvbox_material_show_eob~

Whether to show |hl-EndOfBuffer|.

    Type:               |Number|
    Available values:   `1`, `0`
    Default value:      `1`

------------------------------------------------------------------------------
                                                *g:gruvbox_material_float_style*
g:gruvbox_material_float_style~

Style used to make floating windows stand out from other windows. `'bright'`
makes the background of these windows lighter than |hl-Normal|, whereas
`'dim'` makes it darker.

Floating windows include for instance diagnostic pop-ups, scrollable
documentation windows from completion engines, overlay windows from
installers, etc.

    Type:               |String|
    Available values:   `'bright'`, `'dim'`
    Default value:      `'bright'`

------------------------------------------------------------------------------
                                  *g:gruvbox_material_diagnostic_text_highlight*
g:gruvbox_material_diagnostic_text_highlight~

Some plugins support highlighting error/warning/info/hint texts, by default
these texts are only underlined, but you can use this option to also highlight
the background of them.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Currently, the following plugins are supported:

- neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/ycm-core/YouCompleteMe
- https://github.com/dense-analysis/ale
- https://github.com/neomake/neomake
- https://github.com/vim-syntastic/syntastic

------------------------------------------------------------------------------
                                  *g:gruvbox_material_diagnostic_line_highlight*
g:gruvbox_material_diagnostic_line_highlight~

Some plugins support highlighting error/warning/info/hint lines, but this
feature is disabled by default in this color scheme. To enable this feature,
set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Currently, the following plugins are supported:

- https://github.com/neoclide/coc.nvim
- https://github.com/ycm-core/YouCompleteMe
- https://github.com/dense-analysis/ale
- https://github.com/vim-syntastic/syntastic

------------------------------------------------------------------------------
                                    *g:gruvbox_material_diagnostic_virtual_text*
g:gruvbox_material_diagnostic_virtual_text~

Some plugins can use the virtual text feature of Neovim to display
error/warning/info/hint information. You can use this option to adjust the
way these virtual texts are highlighted.

    Type:               |String|
    Available values:   `'grey'`, `'colored'`, `'highlighted'`
    Default value:      `'grey'`

Currently, the following plugins are supported:

- Neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/dense-analysis/ale
- https://github.com/neomake/neomake
- https://github.com/ycm-core/YouCompleteMe

------------------------------------------------------------------------------
                                               *g:gruvbox_material_current_word*
g:gruvbox_material_current_word~

Some plugins can highlight the word under current cursor, you can use this
option to control their behavior.

    Type:               |String|
    Available values:   `'grey background'`, `'bold'`, `'underline'`, `'italic'`
    Default value:      `'grey background'` when not in transparent mode, `'bold'`
    when in transparent mode.

Currently, the following plugins are supported:

- https://github.com/neoclide/coc-highlight
- https://github.com/dominikduda/vim_current_word
- https://github.com/RRethy/vim-illuminate
- https://github.com/itchyny/vim-cursorword
- https://github.com/prabirshrestha/vim-lsp

------------------------------------------------------------------------------
                                     *g:gruvbox_material_inlay_hints_background*
g:gruvbox_material_inlay_hints_background~

Inlay hints are special markers that are displayed inline with the code to
provide you with additional information. You can use this option to customize
the background color of inlay hints.

    Type:               |String|
    Available values:   `'none'`, `'dimmed'`
    Default value:      `'none'`

Currently, the following LSP clients are supported:

- neovim's built-in language server client
- https://github.com/neoclide/coc.nvim
- https://github.com/prabirshrestha/vim-lsp
- https://github.com/ycm-core/YouCompleteMe

------------------------------------------------------------------------------
                                    *g:gruvbox_material_disable_terminal_colors*
g:gruvbox_material_disable_terminal_colors~

Setting this option to `1` will disable terminal colors provided by this color
scheme so you can remain terminal colors the same when using |:terminal| in
vim and outside of vim.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

------------------------------------------------------------------------------
                                           *g:gruvbox_material_statusline_style*
g:gruvbox_material_statusline_style~

Determine the style of statusline/airline/lightline/lualine.

There are 3 designs for statusline:

- `default`: See the screenshots.
- `mix`: Combines `default` and `original`.
- `original`: The design used in the original gruvbox.

    Type:               |String|
    Available values:   `'default'`, `'mix'`, `'original'`
    Default value:      `'default'`

------------------------------------------------------------------------------
                                     *g:gruvbox_material_lightline_disable_bold*
g:gruvbox_material_lightline_disable_bold~

By default, bold is enabled in lightline color scheme. To disable bold in
lightline color scheme, set this option to `1`.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Note: this configuration option doesn't need to be placed before `colorscheme gruvbox-material`

------------------------------------------------------------------------------
                                         *g:gruvbox_material_better_performance*
g:gruvbox_material_better_performance~

The loading time of this color scheme is very long because too many file types
and plugins are optimized. This feature allows you to load part of the code on
demand by placing them in the `after/syntax` directory.

Enabling this option will reduce loading time by approximately 50%.

    Type:               |Number|
    Available values:   `0`, `1`
    Default value:      `0`

Note: the initial generation of syntax files, which occurs on the first Vim
restart after enabling this option, requires up to 5 seconds to complete.

------------------------------------------------------------------------------
                                            *g:gruvbox_material_colors_override*
g:gruvbox_material_colors_override~

Override color palette. The available keys can be found in
`/path/to/gruvbox-material/autoload/gruvbox_material.vim`.

E.g.
>
    let g:gruvbox_material_colors_override = {'bg0': ['#1d2021', '234'], 'bg2': ['#282828', '235']}
    colorscheme gruvbox-material
<
    Type:               |Dictionary|
    Default value:      `{}`

==============================================================================
FAQ                                                       *gruvbox-material-faq*

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

The colors don't match those in the screenshots.~

1. This color scheme is mainly designed for true colors, `set termguicolors`
is required. Check output of `vim --version`, maybe your vim doesn't support
`termguicolors`.

2. Maybe your terminal emulator doesn't support true colors, you can test it
using [this script](https://unix.stackexchange.com/questions/404414/print-true-color-24-bit-test-pattern).

3. If you are running vim in tmux, you need to override default true colors of
tmux, as tmux cannot display true colors properly:
[#1246 How to use true colors in vim under tmux?](https://github.com/tmux/tmux/issues/1246)

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

The configuration options don't work.~

You should place them before `colorscheme gruvbox-material` .

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

A lot of errors are detected if I install with pack feature.~

You'll need to add `packadd! gruvbox-material` before applying this color
scheme. Check [sainnhe/gruvbox-material#60](https://github.com/sainnhe/gruvbox-material/issues/60)

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

I can't apply airline/lightline color scheme.~

The name is `gruvbox_material` instead of `gruvbox-material`. I have to use
underline for some grammatical reasons.

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

How to enable cursive italic keywords?~

1. Install a font that supports cursive italics, for example https://aka.sainnhe.dev/fonts

2. Enable italic keywords in this color scheme: `let g:gruvbox_material_enable_italic = 1`

3. (Optional) Disable italic comment: `let g:gruvbox_material_disable_italic_comment = 1`

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

The comment color looks weird.~

Some terminal emulators don't support italics, which may cause the comment
color looks weird. See https://github.com/sainnhe/gruvbox-material/issues/5#issuecomment-729586348

A temporary solution is to disable italic comments via
|g:gruvbox_material_disable_italic_comment|.

If you are using tmux, you may also need to override default true colors of
tmux: https://github.com/tmux/tmux/issues/1246

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

How to use custom colors?~
>
    function! s:gruvbox_material_custom() abort
      " Link a highlight group to a predefined highlight group.
      " See `colors/gruvbox-material.vim` for all predefined highlight groups.
      highlight! link groupA groupB
      highlight! link groupC groupD

      " Initialize the color palette.
      " The first parameter is a valid value for `g:gruvbox_material_background`,
      " the second parameter is a valid value for `g:gruvbox_material_foreground`,
      " and the third parameter is a valid value for `g:gruvbox_material_colors_override`.
      let l:palette = gruvbox_material#get_palette('hard', 'mix', {})
      " Define a highlight group.
      " The first parameter is the name of a highlight group,
      " the second parameter is the foreground color,
      " the third parameter is the background color,
      " the fourth parameter is for UI highlighting which is optional,
      " and the last parameter is for `guisp` which is also optional.
      " See `autoload/gruvbox_material.vim` for the format of `l:palette`.
      call gruvbox_material#highlight('groupE', l:palette.red, l:palette.none, 'undercurl', l:palette.red)
    endfunction

    augroup GruvboxMaterialCustom
      autocmd!
      autocmd ColorScheme gruvbox-material call s:gruvbox_material_custom()
    augroup END

    colorscheme gruvbox-material
<
Or in Neovim (Lua configuration):
>
    vim.api.nvim_create_autocmd('ColorScheme', {
      group = vim.api.nvim_create_augroup('custom_highlights_gruvboxmaterial', {}),
      pattern = 'gruvbox-material',
      callback = function()
        local config = vim.fn['gruvbox_material#get_configuration']()
        local palette = vim.fn['gruvbox_material#get_palette'](config.background, config.foreground, config.colors_override)
        local set_hl = vim.fn['gruvbox_material#highlight']

        set_hl('Search', palette.none, palette.bg_visual_yellow)
        set_hl('IncSearch', palette.none, palette.bg_visual_red)
      end
    })
<
Note: Make sure to define the `augroup` before declare the `colorscheme`.

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

What's your status line configuration?~

See this post: https://aka.sainnhe.dev/statusline

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

What's the font used here?~

See this post: https://aka.sainnhe.dev/fonts

==============================================================================
vim:tw=78:nosta:noet:ts=8:sts=0:ft=help:et:sw=4:fen:fdm=marker:fmr={{{,}}}: