Gruvbox theme for Tmux

Theme with 'retro groove' flavor for Tmux, based on Pavel Pertsev's gruvbox colorscheme and inspired by work of Gordon Chiam. Subthemes switching inspired by tmux-color-solarized.

Screenshot made with dark & light themes (16-bit) from macOS alacritty terminal with xterm-256color and Hack Nerd Font Regular. Backgrounds by Aleksandar Pasaric and Vishnu Murali.

Installation

Install via TPM (recommended)

Add plugin at the top list of TPM plugins list in .tmux.conf and select desired theme.

# ~/.tmux.conf

set -g @plugin 'tmux-plugins/tpm' # mandatory
set -g @plugin 'tmux-plugins/tmux-sensible' # optional recommended

set -g @plugin 'egel/tmux-gruvbox'
# set desired theme options...
set -g @tmux-gruvbox 'dark' # or 'dark256', 'light', 'light256'

# other plugins
...

Hit prefix + I to fetch the plugin and source it. Your Tmux should be updated with the theme at this point.

Note

If you used v1 before and interested to adapt to v2 use this Migration Guide from v1 to v2.

Install manually

Tip

If you do not have github account download it and unzip.

1. Clone the project to desired location

   cd ~/projects/
   git clone ...

2. Add theme at to top of your ~/.tmux.conf config.

   # ~/.tmux.conf
   
   run ~/projects/tmux-gruvbox/tmux-gruvbox.tmux
   # set desired options...
   set -g @tmux-gruvbox 'dark' # or 'dark256', 'light', 'light256'

Configuration options

Theme

• default value: dark256

Theme name	Color palette	Preview link
dark	16-bit colors	preview
light	16-bit colors	preview
dark256	256 colors	preview
light256	256 colors	preview

set -g @tmux-gruvbox 'dark' # dark256, light, light256

Tip

Each terminal emulator can behave bit differently regarding displaying colors. If you have some problems see True Color (24-bit) and italics with alacritty + tmux + vim (neovim) where there is great wisdom how to adjust terminal, especially when used alacritty and tmux.

Transparent status-bar

• default value: 'false'
• tmux >= 3.2 (experimental)

set -g @tmux-gruvbox-statusbar-alpha 'true'

Left Status (Section A)

• default value: '#S' (session name)

set -g @tmux-gruvbox-left-status-a '#S' # tmux's session name

Right Status (Section X)

• default value: '%Y-%m-%d'

This section is customizable for user, and by default contains current date.

# set date in US notation
set -g @tmux-gruvbox-right-status-x '%m/%d/%Y' # e.g.: 01/31/2024

# or set date in EU notation
set -g @tmux-gruvbox-right-status-x '%d.%m.%Y' # e.g.: 30.01.2024

Tip

Some user may have problem with displaying dates in desired format, if this case for you try using double percent %%

Right Status (Section Y)

• default value: '%H:%M'

This section is customizable for user, and by default contains current time.

# set US time format
set -g @tmux-gruvbox-right-status-y '%I:%M %p' # 09:54 PM

Right Status (Section Z)

• default value: '#h' (hostname)

This section is customizable for user, and by default contains hostname.

# display hostname and enhance section with other plugin
set -g @tmux-gruvbox-right-status-z '#h #{tmux_mode_indicator}'

Tip

Make sure the themes' settings are defined before all other plugins, otherwise content from external plugins may not be displayed correctly by the theme.

Development

To run project locally:

1. clone the repository to desired place

   cd $HOME/projects/
   git clone ...

2. create a symlink to the cloned repository (best in the standard TPM plugin directory):

   # cd to tmux plugin directory
   cd ~/.tmux/plugins/
   
   # create symlink to cloned repo
   ln -sf $HOME/projects/tmux-gruvbox/ tmux-gruvbox

3. and in ~/.tmux.conf set

   # ~/.tmux.conf
   set -g @plugin 'egel/tmux-gruvbox'
   # set desired options...
   set -g @tmux-gruvbox 'dark'

Linters & formatters

To keep the files clean we use few program to help us achieve it:

1. Editorconfig (make sure your editor have it)
2. Markdown (prettier/prettierd)
3. Shell (shellcheck, shfmt)

License

GPLv3 - Maciej Sypień