Code

Organize Your Work With tmux Sessions

October 27, 2021

At any given time I have several projects on the go, and each one gets its own tmux session. This makes it easy to keep my work organized and I can quickly switch to another project without having to close any programs. When I’m ready to resume work on a project I attach to its tmux session and vim and any other terminals or programs I’ve opened are exactly as I left them.

Session names

You can launch a new tmux session with the new-session command:

$ tmux new -s blog

Tmux displays the session name in the bottom left corner of the screen. To get back to the raw terminal, detach with <prefix>d (on Linux the default the prefix combination is Ctrl-b. To type <prefix>d press control and b together, release and then press d).

The tmux ls command displays a list of current sessions. I always name my sessions so I know what each one is for:

$ tmux ls
blog: 2 windows (created Tue Oct 26 19:32:56 2021) (attached)
codereview: 1 windows (created Wed Oct 20 13:22:50 2021)
wizard: 2 windows (created Tue Oct 19 19:33:03 2021)
entity: 4 windows (created Tue Oct 19 09:13:11 2021)

To re-attach to a specific session, I use its name:

$ tmux a -t blog

Auto-naming sessions

I sometimes forget to name new tmux sessions. This isn’t calamitous: the key binding <prefix>$ lets you rename the current session. But I’ve largely solved that problem by adding a hook to my .tmux.conf:

set-hook -g session-created 'send-keys tmux Space rename-session Space $(basename Space $(pwd)) Space Enter tput Space clear Enter'

Here’s what that mouthful is doing: it adds a hook that executes whenever a new tmux session is created. The hook renames the session to the basename of the current working directory, and then clears the screen. I use send-keys here because the rename-session command only accepts a string. And because send-keys ignores spaces, every space is passed by key name.

Switching between sessions

I’ve already mentioned how you can list and attach to a given tmux session, but I usually don’t do it that way. As my terminal is always in one tmux session or another, I can jump to the next session with <prefix>). To jump to the previous session, use <prefix>(.

If I have a lot of sessions, or trouble finding a particular session, I use the choose-tree interactive menu to pick the session (<prefix>s). An awesome feature is tmux displays a preview of all the windows in the session to help me find the one I’m looking for:

Organizing panes in a session

I often work with two vertical panes side by side (the binding <prefix>% creates a new vertical pane). Occasionally the work I’m doing in each pane diverge and I’d rather move one to a new window. This is one of my favorite features! I jump to the pane I want to move with <prefix>o, and then type <prefix>! to break it out into its own window.

When I have two panes in separate windows that I want to compare side-by-side, I place them in the same window with the join-pane command. For example to join the active pane on window 2 to window 0: <prefix>:joinp -s :2 -t :0 (note the colons). This adds the pane horizontally, so I cycle the pane layout with <prefix>space until they are side-by-side.

Changing the default directory

Usually all the work I do in a session happens under same root directory. Tmux defaults the session working directory to the current directory when the session is created. Any new pane created in the session begins in the session working directory. Sometimes I want to change this; either I launched the session in the wrong directory, or I’ve moved the project files elsewhere. I fix this within the session using the attach-session command (alias a) giving it a new directory. E.g. <prefix>:a -c /home/dfarrell/blog changes the session working directory to be /home/dfarrell/blog.

Getting more info

Tmux has a comprehensive manual which is a great reference for understanding a command and its options. It can be a little overwhelming though. I recommend adding one or two new commands to your repertoire at a time to see if they help your workflow or not. Within tmux you can also view key bindings with <prefix>?.

Tags: tmux command-line