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

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ń