This content originally appeared on DEV Community and was authored by Igor Irianto
Configuring Your Tmux to Be Even More Awesome
This article is part 2 of my tmux series. In the previous article, you learned how to use tmux: what tmux is, how to manage multiple terminals, and how to use tmux's powerful features. However, in that article, I didn't cover much how to customize tmux. This is what this article is for. Here you'll learn some configurations that I use.
My hope is that by exposing a list of my personal tmux configurations and my reasoning behind them, you will see a general pattern and understand it enough to make tmux your own.
Here you will learn useful tmux shortcuts you might not even know exist. Whenever you thinking "Can Tmux can do that?" when reading this article, the answer is, 90% of the time, "Yes, tmux can do that!". No, tmux can't do your chores or make your wildest dreams come true, but tmux probably can make your wildest terminal multiplexing dreams come true :D.
It is highly recommended that you either read my previous article or are already familiar with how tmux works.
The Tmux Config File
When you start using tmux, you may think that some of tmux's keys are not intuitive or straight-up uncomfortable to reach. For example, I never understood why tmux uses Ctrl + b as a prefix. The letter b is positioned at a weird distance from the ctrl button. I also found commands like the split commands Prefix + " and Prefix + % are not intuitive. There is nothing about " and % that are associable to horizontal / vertical splits.
It would be nice to be able to change some of the default configs into something that are more intuitive to me, the user. To do this, we need to configure the tmux config file.
When you start a tmux session, tmux looks for a file named .tmux.conf in the HOME path ~/.tmux.conf (technically tmux looks for /etc/tmux.conf first, then ~/.tmux.conf, but the former is best left untouched).
How to Modify the Config File
A .tmux.conf file to tmux is like .zshrc to Z-Shell and .vimrc to Vim. It is a path to a file where you enter your own configurations so next time you launch tmux, it executes everything inside that config file.
So what can you put inside the tmux config file? Anything. The possibilities are endless.
Endless possibility is not always a good thing. I remember the times I was staring at a blank MS Word when having to write a report or a blank Strathmore Paper when having to draw a scene - it can be intimidating having to fill up your config file from a blank slate. When I started using tmux a few years ago, I copied + pasted much of my tmux config from random sites I found from the internet. Now that I'm older and wiser (am I? :D), I have deleted the configs that I don't need. I also make sure that I understood the ones that I keep. I hope that you will be able to start your tmux journey at a better place than I did: understanding what you put into your config file instead of copy-pasting anything that remotely look interesting without knowing what it really does.
Tmux has a set of commands that you can run from the terminal inside a tmux session. For example, to display a message, you can use tmux's display-message command. Type this from the terminal inside a tmux session:
tmux display-message "Hello my tmux friends"
You should see "Hello my tmux friends" displayed on the bottom of the screen.
If you find display-message is too long to type, display works the same way, plus it is shorter.
tmux display "Hello my tmux friends"
If you want to display the message on the terminal instead on the status bar, pass it the -p flag. Try:
tmux display -p "Hello tmux"
To run tmux command from the terminal, you need to precede it with the tmux command, as you'll see later.
Another way to run a tmux command is to use the command-line mode. To enter the command-line mode, press Prefix + : (Vim users might notice striking similarities with Vim's EX mode). In this mode, you can enter any tmux commands without prepending it with tmux.
If you haven't already, run:
Prefix + :
Your cursor should now be at the bottom of the tmux window. Type:
display "Hello my tmux friends"
Again, with this approach you don't have to type tmux display anymore. display is enough. If you look at the status bar (bottom of the screen), you'll see the "Hello my tmux friends" text.
One advantage of the command-line mode is that you can run any tmux command while having another program running. For example, if you need to run display "hello" and you currently have Vim open, instead of exiting Vim then typing tmux display "hello", with the command-line mode, you can just press Prefix + : and type display-message "hello" - without exiting Vim!
Quick Source
When you edit your tmux config file, you will need to reload it for the change to take place. To reload tmux, run tmux source-file ~/.tmux.conf from the terminal or run source-file ~/.tmux.conf from tmux's command-line mode. Tmux will re-execute all the codes inside the ~/.tmux.conf file.
If you're a tinkerer, a shortcut to quickly source your config file can be useful. Add the following inside ~/.tmux.conf:
bind r source-file ~/.tmux.conf \; display "Reloaded!"
The bind command (short for bind-key) binds the letter r to perform the following (note, this actually binds Prefix + r, not just the letter r by itself)
- Config file source (
source-file ~/.tmux.conf) - Display message (
display "Reloaded!")
The semi-colon (;) lets you to sequentially combine multiple tmux commands. It's a great way to bind a single key with multiple commands.
So each time you make changes to the config file, save the tmux config and run Prefix + r.
Some configs won't take place even after you reload the config file. Usually these are the UI-related commands. If you don't see your changes after reloading the tmux config, you need to restart the tmux server:
- Detach from the session (
Prefix + d) - Kill the server (
tmux kill-server) - Start a new session (
tmux new -s MY_SESSION)
Alternatively, you can also run Prefix + I (note the I is uppercased) to reload tmux environment.
In short, if running Prefix + r doesn't do anything, try running Prefix + I or restart your server.
Commenting
Tmux uses # to comment out any subsequent texts. Commented lines won't be executed by tmux config. I like to use comments to explain an obscure code. For example:
# Add binding to reload tmux.conf for fast, iterative development
bind r source-file ~/.tmux.conf \; display "Reloaded!"
You can also put a comment at the end of the same line:
bind r source-file ~/.tmux.conf \; display "Reloaded!" # quick reload
Useful Configurations
Here are some configurations that I find useful.
Changing the Default Prefix
As said before, I am not a big fan of tmux's default Ctrl + b default prefix. Let's change it with something more intuitive. If you look around on the internet, some popular tmux prefix alternatives are:
Ctrl + a-
Ctrl + Space -
Ctrl + s -
Ctrl + u - Backticks
- Tab + key variation instead of
Ctrl + KEY - Other?
I personally use Ctrl + Space mainly because my Vim leader key is the Space key. To change my prefix to Ctrl + Space, I add this in the tmux config file:
unbind C-Space
set -g prefix C-Space
bind C-Space send-prefix
What each does:
-
unbindunbinds whatever functionalityC-spacehad (if any). -
set -g prefixline informs tmux that the prefix will now beC-Space. -
bind ... send-prefixallowsCtrl + Spaceto perform thesend-prefixcommand. The send-prefix command sends the prefix keystroke to a window. This is useful with nested tmux sessions.
Feel free to use whatever key combination you feel most comfortable with.
Mouse Usage in Tmux
Although I am not a big fan of using mouse extensively, there were times when I needed to use it. Tmux's default configs are not mouse friendly. Let's change that. To enable scrolling, clicking, and resizing, add the following inside the tmux config file:
set -g mouse on
If you want to see more, check out the MOUSE SUPPORT section inside man tmux.
Increase History
By default, tmux keeps the previous 2000 lines of window history (you can scroll up 2000 lines above your current terminal line). Sometimes 2000 isn't enough. To increase it to 5000 lines, add this inside the config file:
set-option -g history-limit 5000
I never needed more than 5000, so I never went higher. Of course, you can make it higher if you need to.
Jump to a Marked Pane
If you're a Vim user, you may be aware that you can create a mark with m + identifier. You can then return to that mark at any time. You can do the same with tmux.
To mark the pane you are currently on, press:
Prefix + m
In Vim, to return to a marked location, you use a single-quote or a backtick. Since we already have the single-quote shortcut taken (recall that Prefix + ' is used to jump to a window number by index), let's use backtick. To jump to a mark using a backtick, add this config:
bind \` switch-client -t'{marked}'
Try this: mark a pane, then go to a different window - observe that you can quickly return to the previous pane with Prefix + backtick. I find it useful to mark the pane I always find myself returning into, usually the pane where the main codebase is.
To remove a mark, press Prefix + m again while you're on that marked pane or just press Prefix + M anywhere.
One final re*mark* (pun intended), in Vim you can have up to 26 marks. In tmux, you can only have one, so choose wisely which pane to mark.
Numbering Windows and Panes
Recall that tmux windows and panes are 0-based. I find them not really intuitive. I prefer to have my first windows and panes to start with 1.
set -g base-index 1
setw -g pane-base-index 1
Suppose that I have 4 windows in a session - call them window A, B, C, and D. If I close the third window (window C), now I end up with window A in position 1, B in position 2, and D in position 4. I have a gap in position 3. This behavior causes a friction in my workflow because I have to keep in the back of my mind that position 3 window is vacant. Wouldn't it be better to automatically move window D to the third position after deleting window C? Heck yea! To get this behavior, add:
set -g renumber-windows on
Now when I delete window C in position 3, window D automatically moves to position 3. The next window I create will become window 4. Little things like these free up your mental real estate. The fewer things I have to remember in my head, the more I can use my head to think about the important things! (Like, what's for lunch? :D)
More Intuitive Split Commands
I think tmux's default split pane shortcuts, Prefix + % and Prefix + " are not intuitive. | and - are better symbols to represent vertical and horizontal splits. Why not use them instead?
bind | split-window -hc "#{pane_current_path}"
bind - split-window -vc "#{pane_current_path}"
Now when I press Prefix + |, tmux does a vertical split and when I press Prefix + -, tmux does a horizontal split.
Btw, I find that having to press the Shift key to do Prefix + | is mildly inconvenient. So I have these mappings:
bind-key "|" split-window -h -c "#{pane_current_path}"
bind-key "\\" split-window -fh -c "#{pane_current_path}"
bind-key "-" split-window -v -c "#{pane_current_path}"
bind-key "_" split-window -fv -c "#{pane_current_path}"
This allows me to press either the uppercased version of that key to get the vertical / horizontal splits.
Swapping Windows
Sometimes I need to swap windows around. Maybe I want to have the docker-compose to window 1 from window 2. I think > and < make good, intuitive keys to swap the current window to the right and left, respectively.
bind -r "<" swap-window -d -t -1
bind -r ">" swap-window -d -t +1
Now if I want to move the current window to the right, I can do Prefix + >. To move the current window to the left, do Prefix + <.
Keeping Current Path
When you create a new window (Prefix + c), tmux resets the path. Wait, what are you talking about? Suppose when I start a new tmux session, I was on the HOME path (~/). After coding and doing stuff, I end up in ~/some/directory/. Now I need to create a new window. When I run Prefix + c, the new window will be back on the HOME directory, not whatever path I was on. Tmux automatically resets the path in the new window you just created to the path you were on when you started the current session. 80% of the time, when I create a new window, I want to stay in whatever path I am on. To preserve the path in the new window, add:
bind c new-window -c "#{pane_current_path}"
Now when I create a new window, the new window will also be on ~/some/directory/.
Toggling Windows and Sessions
I find myself needing to toggle between the current and previous window a lot. To quickly toggle between windows:
bind Space last-window
Now I can type Prefix + Space to toggle between the current and previous windows.
Recall that Prefix + Space was originally the toggle layout tmux shortcut. If you use this, you'll lose that layout toggle shortcut. I personally never use the layout toggle functionality at all. I also choose Space because my Prefix is Ctrl + Space, making it intuitive. If you use a different prefix, you may consider a different shortcut key.
Moreover, sometimes I also need to toggle between the current and the previous session. Add this:
bind-key C-Space switch-client -l
Again, I chose Ctrl + Space because Ctrl + Space is also my Prefix. So it's like pressing Prefix twice. If you use a different prefix, consider using that prefix key(s) instead.
Resizing
Recall that we can run tmux resize-pane -D/U/L/R commands to resize the panes. Unfortunately, tmux doesn't come with the shortcuts to quickly resize panes. No worries, let's just add our own! The shortcuts that I use are Prefix + Ctrl-h/j/k/l:
bind -r C-j resize-pane -D 15
bind -r C-k resize-pane -U 15
bind -r C-h resize-pane -L 15
bind -r C-l resize-pane -R 15
The 15 above is tmux cell unit. I find 15 unit increments to be perfect. Not too little, not too much. I also find Ctrl-h/j/k/l to be good keys to do this because it resembles Vim navigation.
Other resizing alternatives are the arrow keys, Ctrl + arrow keys, or </>/-/+.
Breaking and Joining Panes
Maybe you are on a window with multiple panes and you want to break the current pane out into its own window. To do this, tmux has a built-in break-pane command:
Prefix + !
Conversely, what if you want to join a pane from another window into a different window? There is no native keybinding, but tmux has a join-pane command. Add the following:
bind j choose-window 'join-pane -h -s "%%"'
bind J choose-window 'join-pane -s "%%"'
Press Prefix + j to choose which window you want to join.
Btw notice that I have two shortcuts: j and J. The former joins a window horizontally and the latter vertically.
Quick Pane Creation
I don't know when inspiration strikes. But when it strikes, I want to have a quick access to my notes.
bind-key h split-window -h "vim ~/scratch/notes.md"
Now whenever I thought of a billion-dollar startup idea, I can just press Prefix + h to open a new horizontal split window and launch ~/scratch/notes.md in Vim. Who says that learning tmux doesn't pay? :D
General Key-Binding
All the tmux shortcuts you've seen so far have used the Prefix key. What if you need to create a shortcut that does not use Prefix? What if, instead of Prefix + j, you want to use Ctrl + j to join windows?
You can do this bypassing the -n option to the bind command in your config file. Instead of bind j YOUR_COMMAND, you use bind -n C-j YOUR_COMMAND:
bind -n C-j choose-window 'join-pane -h -s "%%"'
Now it will use Ctrl + j Instead of Prefix + j.
Changing the Config File Path
By default your config path is in the HOME directory (in my case, it is ~/.tmux.conf). But you can always put it somewhere else. If you run tmux with tmux -f /path/to/your/new/tmux.conf, it will use whatever path you point instead of the default HOME path.
Personally, I keep my config path in HOME (~/.tmux.conf) but it is symlinked to my dotfiles repo (~/Projects/dotfiles/tmux.conf). With this, can I can edit either ~/Projects/dotfiles/tmux.conf or ~/.tmux.conf and these two files will remain in sync. I like to keep my config files portable.
TPM
At some point, you'll need to use a more complicated setup instead of one-liner configurations. TPM is a good tool for that. It stands for Tmux Plugin Manager. It allows you to create and install tmux plugins easily.
In the following section, I will briefly go over TPM. If you want to learn more, feel free to check the repository!
Installing TPM
To install TPM, you need to:
- Git clone TPM to a HOME directory (
~/.tmux/plugins/tpm) - Add any plugins with
set -g @plugin 'YOUR/PLUGIN'in your tmux config file. Don't forget to precede it withset -g @plugin 'tmux-plugins/tpm'. - Point the
runcommand to the TPM repository location (by default it points to~/.tmux/tpm/tpm).
For more, check out the TPM installation page.
Adding a TPM package
Let's go over how to install a package. I really like the dracula theme plugin. To install it, I have the following in my tmux config:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'dracula/tmux'
run '~/.tmux/plugins/tpm/tpm'
Recall that the first plugin in the list, tmux-plugins/tpm, is required as part of TPM. The next one on the list, dracula/tmux, is the plugin that you're trying to install. Finally, the run '~/.tmux/plugins/tpm/tpm, is also a required code to make TPM work.
You can add as many plugins as you want. Once you added the list of plugins, save and source tmux, then run Prefix + I (reload environment). The dracula plugin should activate. Cool!
For a curated list of plugins, checkout awesome-tmux plugin.
Tmux and Vim
I use tmux and Vim a lot. They are like rice and eggs, or croissant and chocolate, or peanut butter and nutella sandwich - you get the point: they work great together.
There are some configurations that you can add to make them work together even better. It's like adding butter to your rice and eggs, or sesame seeds to your croissant and chocolate, or cheese to your peanut butter and nutella sandwich.
Easy Vim-Tmux Navigation
One of the biggest improvement you can do to vim and tmux is to synchronize their navigations. In my regular workflow, I normally have multiple Vim windows and tmux panes on my screen.
In vim, you move around different windows with Ctrl + w + h/j/k/l. In tmux, you move around different panes with Prefix + left/down/up/right. Wouldn't it be great if you can move your cursor between vim windows and tmux panes using the same key sets?
Heck yea, that sure would make live a LOT simpler! If this is possible, you don't have to pause to think if you're in vim or tmux - should I press Ctrl + w or Prefix? Using only one set of keys eliminates navigation context-switching. The less context-switching you need to do, the more flow you have. The more flow you have, the more brain power you can allocate to actually accomplish the important tasks - like making a tasty rice and egg dish for lunch - I mean, to code!
To accomplish this, you need to install the vim-tmux-navigator plugin for vim and tmux. Technically this is just one plugin, but it needs to be installed in both vim and tmux.
By the way, this article assumes that you have a sufficient understanding of vim plugins. This article is about tmux, not vim. If you want to learn more, check out my other guide, learn-vim. It's the best guide you'll ever read on vim (no bias there :D)
Install the vim-tmux-navigator plugin in vim. I personally use the vim-plug plugin manager, so I only need to add the following:
Plug 'christoomey/vim-tmux-navigator'
Save and source the vimrc, run :PlugInstall.
Next, install the vim-tmux-navigator plugin in tmux. Add this in the tmux config file:
set -g @plugin 'christoomey/vim-tmux-navigator'
Save and source the tmux config file. Don't forget to reload tmux (Prefix + I).
Let's try it! Inside a tmux session, split your window into multiple panes. Inside one pane, open up Vim and split it into multiple windows. Behold! You can navigate to next vim window / tmux pane with Ctrl + h/j/k/l. What!! Isn't that cool? Mind-blown. My life has never been the same ever since I discovered this.
Tmuxinator
Once you use tmux for a while, you will realize that most of the time, you perform the same sequence of commands.
For example, for work, I almost always:
- Create a new session called
work - Rename this window
servers - Launch the rails server
- Launch the sidekiq server on a split pane
- Launch redis on a split pane
- Create a new window named
codes - Launch Vim
- Horizontal split adjusted at about 30% for random terminal needs
- Create a new window named
consolesfor rails / mysql console - Create a new window named
notesto take notes / scratchpads
I do this almost every single day. Let's automate it. One way to do it is to use tmux templating library like tmuxinator.
Tmuxinator lets you to set up your tmux sessions/windows/panes to run specific commands. Set them up once. Reuse any time.
To get started, install tmuxinator. If you have mac, you can just run:
brew install tmuxinator
For more info, check out tmuxinator's installation page.
There are a number of available tmuxinator commands, but the following three are the most important ones, in my opinion (they are also the only ones I remember :D). You can create, edit, and launch a tmuxinator template with:
tmuxinator new PROJECT
tmuxinator edit PROJECT
tmunxinator PROJECT
By the way, I find that the name tmunxinator too long to type. I prefer shorter name, like mux. In my zshrc (or bashrc if you use bash), add:
alias mux=tmuxinator
Now I can just run mux new PROJECT instead of tmuxinator new PROJECT. Let's call our project "work". Run:
mux new work
Tmuxinator will create a new file work.yml somewhere inside the config directory. Inside you can configure your settings for your tmux work project. Mine looks something like this (it comes by default):
# /Users/iggy/.config/tmuxinator/work.yml
name: work
root: ~/
# lots of stuff...
windows:
- editor:
layout: main-vertical
panes:
- vim
- guard
- server: bundle exec rails s
- logs: tail -f log/development.log
The name: attribute is the project name and root is the root directory. windows represents tmux windows for this project - in this case we have three windows:
-
editorwindow using themain-verticallayout. It is split into two with two panes, one runningvimand another runningguard. -
serverthat runsbundle exec rails s, -
logsto display development log.
Let's edit this template to fit my workflow. First, I'm going to update my root to be my work project. Change them to your work directory:
root: ~/Work/is/awesome/
Now each time I run mux work, it will automatically use ~/Work/is/awesome/ as the root path in my session.
Next, modify our windows:
# /Users/iggy/.config/tmuxinator/work.yml
name: work
root: ~/Work/is/awesome/
windows:
- server_stuff:
layout: tiled
panes:
- bundle exec rails s
- bundle exec sidekiq
- redis-server
- code_stuff: vim
- misc_stuff:
- notes:
- cd ~/Dropbox
- vim
I have four windows defined:
- The first,
server_stuff, has the layout set to betiled. It consists of three panes. The first pane runs the rails server, the second sidekiq server, and the third runs redis server. - The second,
code_stuff, runs vim. - The third window is just an empty window for whatever comes up (rails console, mysql console, ssh, git workflow, etc)
- The fourth window is my scratchpad. I have it pointed to my Dropbox directory where I store my notes. I take my notes with vim.
Once you're done, save the yml file. If I ever want to edit it, I just need to run mux edit work. To launch this tmuxinator project, run:
mux work
That's it! It's convenient and easy to set up. This can save you 5-10 minutes everyday.
If you need to close it, since all this is just a tmux session, all you need to do is detach from the work session (Prefix + d), then kill it with tmux kill-session -t work.
By the way, earlier I said that for my codebase window, I like having a window with horizontal split at about 70/30, with the top part running Vim while the bottom one for random terminal work. One way is to use tmux's main-horizontal layout, but it would be nice if I could fine-tune the length of the top and bottom panes.
There is no clean way to do it, but you can use this trick:
- First, create a tmux window and split them horizontally.
- Second, you adjust the height to about 70/30 (using
resize-pane) - Third, when you're happy with the proportions, run
tmux list-windows - It will print something like this:
test* (2 panes) [278x70] [layout edac,278x70,0,0[278x50,0,0,1,278x19,0,51,15]] @1 (active). Your numbers will probably be different from mine. - The ambiguous-looking number is the tmux's window proportions. Copy that. Inside tmuxinator, paste that number in the
layoutsection.
My tmuxinator work.yml file now looks like this:
# /Users/iggy/.config/tmuxinator/work.yml
name: work
root: ~/Work/is/awesome/
windows:
- server_stuff:
layout: tiled
panes:
- bundle exec rails s
- bundle exec sidekiq
- redis-server
- code_stuff:
layout: edac,278x70,0,0[278x50,0,0,1,278x19,0,51,15]
panes:
- vim
- echo "empty"
- misc_stuff:
- notes:
- cd ~/Dropbox
- vim
When I run the mux work command, the second window will be split horizontally with the same proportion as what we had before. Cool!
By the way, tmuxinator is not the only tmux manager in town. There are two more alternatives that I know of (there could be more):
Your turn now - think of your work / personal project workflows, then create your own tmuxinator / tmuxp / teamocil / etc template!
Conclusion
In this chapter you learned the different examples how you can modify your tmux config. They are by no means exhaustive. I've probably only gone through the basic configs. There are many more combinations you can implement to make your tmux more powerful.
I hope that through reading this article, you'll learn enough to understand how to modify tmux on your own. Tmux is a simple, powerful tool. Used correctly, it allows you to organize your workflows and reduce context-switching, allowing you to focus more on the current task at hand.
This is by no means the last tmux articles I'll write. I'm currently working on not just one, but two more articles, so stay tuned! Meanwhile, continue to practice and configure tmux to make it truly your own. Until next time!
This content originally appeared on DEV Community and was authored by Igor Irianto
Igor Irianto | Sciencx (2021-11-18T13:30:50+00:00) Useful Tmux Configuration Examples. Retrieved from https://www.scien.cx/2021/11/18/useful-tmux-configuration-examples/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.