whatyouhide.vim-gotham/04_TERMINAL_COMPATIBILITY.md

Terminal Compatibility Guide

Version Overview

Version	Best For	Terminal Dependency
gotham	GUI Vim, true color terminals	Requires terminal colorscheme
gotham256	256-color terminals	Fixed palette, terminal-independent

gotham256 Requirements

The gotham256 version includes a guard that exits early if requirements aren't met:

if !(has('termguicolors') && &termguicolors) && !has('gui_running') && &t_Co != 256
  finish
endif

This means it requires one of:

• termguicolors enabled (true color)
• GUI running (gVim, MacVim)
• 256 color support (t_Co == 256)

Setting Up Terminal Colorschemes

For gotham (non-256) to look correct, your terminal emulator must use the Gotham color scheme.

gotham-contrib

Supported platforms are documented in the gotham-contrib repository:

• iTerm2 (macOS)
• Terminal.app (macOS)
• Guake (Linux)
• Terminator (Linux)
• Xresources (Linux)
• PuTTY (Windows)
• and more...

Neovim :terminal Integration

Gotham sets Neovim's terminal palette colors via g:terminal_color_* variables:

let g:terminal_color_0  = '#0c1014'  " base0
let g:terminal_color_1  = '#c23127'  " red
let g:terminal_color_2  = '#2aa889'  " green
let g:terminal_color_3  = '#edb443'  " yellow
let g:terminal_color_4  = '#195466'  " blue
let g:terminal_color_5  = '#4e5166'  " violet
let g:terminal_color_6  = '#33859E'  " cyan
let g:terminal_color_7  = '#99d1ce'  " base6
let g:terminal_color_8  = '#0c1014'  " base0 (bright)
let g:terminal_color_9  = '#c23127'  " red (bright)
let g:terminal_color_10 = '#2aa889'  " green (bright)
let g:terminal_color_11 = '#edb443'  " yellow (bright)
let g:terminal_color_12 = '#195466'  " blue (bright)
let g:terminal_color_13 = '#4e5166'  " violet (bright)
let g:terminal_color_14 = '#33859E'  " cyan (bright)
let g:terminal_color_15 = '#d3ebe9'  " base7

True Color Support

Modern terminals supporting 24-bit color (true color):

Terminal	Support
iTerm2 (macOS)	Yes
Konsole (Linux)	Yes
GNOME Terminal	Yes (with tweaks)
Windows Terminal	Yes
Alacritty	Yes
Kitty	Yes
tmux	Requires set -g default-terminal "screen-256color"

Enable true color in Neovim:

set termguicolors

Vim vs Neovim Differences

Feature	Vim	Neovim
GUI colors	Full hex	Full hex
256 colors	cterm	cterm
True color	Via GUI	Via termguicolors
Terminal palette	N/A	g:terminal_color_*

tmux Configuration

For proper colors in tmux sessions:

# In ~/.tmux.conf
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

SSH Session Colors

When using Vim over SSH, ensure:

1. Terminal supports 256 colors (echo $TERM)
2. SSH config has ForwardX11Trusted yes for true color
3. Server-side TERM matches capabilities

Troubleshooting

Colors Look Washed Out

• Enable true color: set termguicolors
• Ensure terminal supports 24-bit color

Only 16 Colors Showing

• Use gotham256 variant instead of gotham
• Verify $TERM is set to a 256-color terminal

SSH Session Has Wrong Colors

1. Ensure terminal supports 256 colors: echo $TERM
2. Use ForwardX11Trusted yes in SSH config for true color
3. Consider using -Y flag instead of -X for trusted forwarding

tmux Colors Broken

Ensure tmux.conf has:

set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

If colors are still wrong in tmux, add:

set -ga terminal-overrides ",xterm-256color:Tc:smcup@:rmcup@"

Then restart tmux completely:

tmux kill-server && tmux

Neovim in tmux

When using Neovim inside tmux, you may need additional configuration:

1. Ensure termguicolors is set in Neovim:

set termguicolors

2. If colors still appear wrong, add to tmux.conf:

set -ga terminal-overrides ",xterm-256color:Tc:smcup@:rmcup@"

3. Restart tmux completely: tmux kill-server && tmux