tmux-Integration-Best-Practices.md

+This document describes how best to use the tmux integration feature for common use cases. There are a number of settings in far-flung places that are worth customizing.
+
+## What tmux command should I use?
+
+Most users have one tmux session per machine that they wish to either create (if needed) or attach to (if possible). Use this command:
+
+```
+tmux -CC new -A -s main
+```
+
+## What ssh command should I use?
+
+If you wish to run tmux on a remote host over ssh, use this command:
+
+```
+ssh -t example.com 'tmux -CC new -A -s main'
+```
+
+The `-t` argument says to use a TTY, which tmux needs to be happy.
+
+## I keep having to reattach because my ssh connection dies when my IP address changes
+
+Use [Eternal Terminal](https://eternalterminal.dev/). It tunnels ssh connections over a more reliable transport and just works. Then the command is:
+
+```
+et -c="tmux -CC new -A -s main" example.com
+```
+
+## I want to use mosh
+
+Don't use mosh for tmux integration. It's not meant to tunnel traffic, and will cause you horrible agony.
+
+## How do I use shell integration?
+
+Shell integration works with tmux integration, but does not work well with plain-old-tmux (henceforth, POT). For that reason, it is disabled by default. You can enable shell integration in tmux by adding this to your login script (.bash_profile, .profile, .zshrc, .config/fish/config.fish, or .login) prior to where shell integration is loaded:
+
+```
+export ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=YES
+```
+
+tcsh and fish users should modify the above as needed for their shells.
+
+## How do I configure my profile?
+
+I recommend using version 3.3.0 of iTerm2 (in beta at the time of this writing). Create a new profile for each machine you run tmux on. Set the profile's command, like this:
+
+![image](uploads/5f0ca5365f2a4cd55b282e324a1e8eb0/image.png)
+
+If you use ssh instead of Eternal Terminal, configure the session to restart automatically:
+
+![image](uploads/baf5ca2d8ec9fae5f19171745ada17fe/image.png)
+
+## What other settings are relevant?
+
+Check **Prefs > General > tmux**. Here's how I like to configure it:
+
+![image](uploads/e2e5ec850f0258905f97286d4b439566/image.png)
+
+Buried sessions are removed from the window and go in the menu under **Session > Buried Sessions**. You probably don't need to interact with the tmux gateway session (the one where `tmux -CC` was run) very often, so it's nice to hide it away.
+
+## I have a lot of windows. How can I get them all to open?
+
+If you have more than ten tabs or windows, the dashboard will open. If you have a thousand windows, this is probably convenient. If you have eleven, it might just be annoying. The threshold is adjustable in the dashboard itself:
+
+![image](uploads/ff170f69ff75978e475d7c162a8d1866/image.png)
+
+## I want to do something dangerous
+
+Turn on **Prefs > Advanced > Allow variable window sizes in tmux integration**. Ensure you have the most recent version of tmux installed. This is kinda half-baked at the moment, but it works well enough to be useful for some people. I expect to finish polishing it up some time this year (2019).
\ No newline at end of file