# tmux Configuration with chezmoi This guide shows you how to manage your tmux configuration with **chezmoi**, making your tmux setup portable across all your machines. **Series navigation:** 1. [[1. tmux Basics]] - Core concepts 2. **tmux Configuration with chezmoi** (this article) 3. [[3. TPM - Tmux Plugin Manager]] - Plugins 4. [[4. Ghostty + tmux Startup Automation]] - Startup workflows 5. [[5. tmux Session Presets]] - Project layouts ## What Problem Does This Solve? **Without chezmoi:** - Copy `.tmux.conf` manually between machines - Forget which machine has the latest config - No version control for your tmux settings - TPM plugins may be out of sync **With chezmoi:** - One source of truth for all configs - Changes sync across machines instantly - Full Git history of your configuration - Automated setup on new machines ## Pre-Setup Checklist ✅ chezmoi installed (`brew install chezmoi`) ✅ chezmoi initialized (`chezmoi init`) ✅ tmux installed (`brew install tmux`) See [[1. chezmoi]] for complete chezmoi setup. ## Basic Workflow: Adding Your tmux Config ### Step 1: Add Your Config to chezmoi If you already have a `.tmux.conf`: ```bash # Add your existing config to chezmoi chezmoi add ~/.tmux.conf # Edit it through chezmoi (optional) chezmoi edit ~/.tmux.conf # Apply changes chezmoi apply ``` If you don't have a config yet, create one through chezmoi: ```bash # Create new tmux config chezmoi edit ~/.tmux.conf # (Opens your editor with a new file) # Apply it chezmoi apply ``` ### Step 2: Verify It's Managed ```bash # Check that chezmoi is managing the file chezmoi managed | grep tmux.conf # See the difference between source and target chezmoi diff ``` ### Step 3: Commit to Git ```bash # Navigate to chezmoi source directory cd ~/.local/share/chezmoi # Commit your changes git add . git commit -m "Add tmux configuration" git push ``` ## Managing TPM with Homebrew + Brewfile **Recommended approach:** Install TPM via Homebrew and track it in your Brewfile. ### Step 1: Install TPM via Homebrew ```bash brew install tmux tpm ``` ### Step 2: Add to Your Brewfile ```bash # Regenerate Brewfile to include tmux and tpm brew bundle dump --file=~/Brewfile --force # Add Brewfile to chezmoi chezmoi add ~/Brewfile ``` ### Step 3: Tell chezmoi to Ignore Plugin Directory ```bash # Add to ~/.local/share/chezmoi/.chezmoiignore echo ".tmux/plugins/*" >> ~/.local/share/chezmoi/.chezmoiignore ``` This prevents chezmoi from trying to manage the actual plugin files (installed by TPM). ### Step 4: Update tmux.conf for Homebrew TPM When TPM is installed via Homebrew, the path is different. Update your `.tmux.conf`: ```bash # Change from: run '~/.tmux/plugins/tpm/tpm' # To (for Homebrew): run '/opt/homebrew/opt/tpm/share/tpm/tpm' ``` **Alternative:** Create a symlink for compatibility: ```bash mkdir -p ~/.tmux/plugins ln -s /opt/homebrew/opt/tpm/share/tpm ~/.tmux/plugins/tpm ``` Then you can keep using the standard path in `.tmux.conf`. ### On New Machines ```bash # 1. Install Homebrew packages (including tmux and tpm) brew bundle install --file=~/Brewfile # 2. Apply chezmoi configs chezmoi init chezmoi apply # 3. Inside tmux, install plugins tmux Ctrl+B I # Install plugins ``` **Why this approach is better:** - ✅ TPM updates via `brew upgrade` like other tools - ✅ Version controlled in Brewfile - ✅ No need for custom install scripts - ✅ Works seamlessly with your package management workflow See [[2. Managing Homebrew with Brewfile]] for full Brewfile workflow. ### Step 3: Document Plugin Installation In your `.tmux.conf` (managed by chezmoi), add this comment at the top: ```bash # ============================================ # Plugins (Managed by TPM) # ============================================ # After applying this config: # 1. Start tmux # 2. Press Ctrl+B I to install plugins # ============================================ set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'tmux-plugins/tmux-resurrect' # Initialize TPM (keep at bottom) run '~/.tmux/plugins/tpm/tpm' ``` ## Workflow: Updating Config Across Machines ### On Machine A (where you make changes): ```bash # Edit config chezmoi edit ~/.tmux.conf # Apply changes locally chezmoi apply # Test in tmux tmux source ~/.tmux.conf # If good, commit cd ~/.local/share/chezmoi git add . git commit -m "Update tmux: added vim-style navigation" git push ``` ### On Machine B (pull changes): ```bash # Pull latest changes chezmoi update # Reload tmux config tmux source ~/.tmux.conf ``` That's it! Your config is synced. ## Advanced: Template Variables You can make your tmux config adapt to different machines using chezmoi templates. **Example:** Different status bar colors per machine. ### Step 1: Add Variables to chezmoi Config Edit `~/.config/chezmoi/chezmoi.toml`: ```toml [data] hostname = "{{ .chezmoi.hostname }}" [data.tmux] status_bg = "colour234" # Default ``` Create machine-specific overrides: ```bash # On your desktop chezmoi edit ~/.config/chezmoi/chezmoi.toml --apply ``` Add: ```toml [data.tmux] status_bg = "colour22" # Green for desktop ``` On your laptop: ```toml [data.tmux] status_bg = "colour17" # Blue for laptop ``` ### Step 2: Use Templates in .tmux.conf Rename your config to use templating: ```bash # Tell chezmoi this file is a template mv ~/.local/share/chezmoi/dot_tmux.conf ~/.local/share/chezmoi/dot_tmux.conf.tmpl ``` Edit it: ```bash chezmoi edit ~/.tmux.conf ``` Use the variable: ```bash # Status bar (color varies by machine) set -g status-bg {{ .tmux.status_bg }} ``` Apply: ```bash chezmoi apply ``` Now each machine gets a different status bar color automatically! ## Recommended Starter Config Here's a solid starter `.tmux.conf` to manage with chezmoi: ```bash # ============================================ # Basic Settings # ============================================ # Change prefix to Ctrl+A (more ergonomic) unbind C-b set -g prefix C-a bind C-a send-prefix # Enable mouse support set -g mouse on # Start windows and panes at 1, not 0 set -g base-index 1 setw -g pane-base-index 1 # Renumber windows when one is closed set -g renumber-windows on # Enable 256 colors set -g default-terminal "screen-256color" # Increase scrollback buffer set -g history-limit 50000 # ============================================ # Better Keybindings # ============================================ # Split panes using | and - bind | split-window -h bind - split-window -v unbind '"' unbind % # Reload config bind r source-file ~/.tmux.conf \; display "Config reloaded!" # Vim-like pane navigation bind h select-pane -L bind j select-pane -D bind k select-pane -U bind l select-pane -R # Vim-like copy mode setw -g mode-keys vi bind -T copy-mode-vi v send -X begin-selection bind -T copy-mode-vi y send -X copy-selection-and-cancel # ============================================ # Status Bar # ============================================ set -g status-position bottom set -g status-bg colour234 set -g status-fg colour137 set -g status-left '#[fg=colour233,bg=colour245,bold] #S ' set -g status-right '#[fg=colour233,bg=colour245,bold] %Y-%m-%d %H:%M ' # ============================================ # Plugins (Managed by TPM) # After applying: Press Ctrl+B I to install # ============================================ set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'tmux-plugins/tmux-sensible' set -g @plugin 'tmux-plugins/tmux-resurrect' set -g @plugin 'tmux-plugins/tmux-continuum' # Auto-restore sessions set -g @continuum-restore 'on' # Initialize TPM (keep at bottom) run '~/.tmux/plugins/tpm/tpm' ``` Save this as your `~/.tmux.conf` and add it to chezmoi! ## Troubleshooting ### Config not syncing ```bash # Check if file is managed chezmoi managed | grep tmux.conf # Force apply chezmoi apply --force ``` ### TPM not installing plugins ```bash # Manually clone TPM git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm # Inside tmux, install plugins Ctrl+B I ``` ### Changes not taking effect ```bash # Reload tmux config tmux source ~/.tmux.conf # Or restart tmux server tmux kill-server tmux ``` ## Next Steps - [[3. TPM - Tmux Plugin Manager]] - Deep dive into the plugin ecosystem - [[4. Ghostty + tmux Startup Automation]] - Auto-start tmux in your terminal - [[1. chezmoi]] - Full chezmoi documentation **Related:** - [[Dev Environment Stack]] - Understanding configuration layers