Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 129 lines (74 sloc) 5.602 kb
9c5d456 Initial commit
Benjamin Thomas authored
1 # etmux
2
3 Simple utility for easily starting and joining [tmux] sessions.
4
5 `etmux` is short for "Easy tmux". It was chosen because it had limited competition for tab completion. In a default install of Ubuntu all you have to type is `et<TAB>`.
6
7 ## Install
8
9 Put the `etmux` shell script in a folder in your path. If that's not enough instruction, paste these lines into your terminal:
10
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
11 echo "export PATH=$HOME/bin:$PATH" >> ~/.bashrc
12 . ~/.bashrc
9c5d456 Initial commit
Benjamin Thomas authored
13 mkdir ~/bin/
14 mv etmux ~/bin/
15
16 ## Usage
17
18 Simply call `etmux` to start a new session.
19
20 etmux
21
22 Just like `tmux`, the default session is named `0`. Unlike `tmux` if a session with a name `0` already exists, it will join that instead of creating a new session. Thus preventing you from unknownlingly starting a bunch of sessions (like this author does).
23
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
24 If you want to call your session something else, just give `etmux` a different name:
9c5d456 Initial commit
Benjamin Thomas authored
25
26 etmux mySession
27
28 Again, if a session with the same name already exists, `etmux` will attach to that session.
29
30 If you are already in a `tmux` session when you call `etmux`, instead of nesting the sessions, `etmux` will switch you over to the new session.
31
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
32 To see all the options try:
33
34 etmux --help
35
9c5d456 Initial commit
Benjamin Thomas authored
36 ## Predefined Sessions
37
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
38 Sometimes it is handy to have predefined sessions, with windows, panes and commands chosen ahead of time (like is addressed by [Tmuxinator] or [Teamocil]). Easy! Just put a shell script in `~/.etmux-sessions` that uses the `tmux` command line API to set up your session.
9c5d456 Initial commit
Benjamin Thomas authored
39
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
40 If you name your script `mySession` and it exists and is executable at `~/.etmux-sessions/mySession` then you can run it with:
9c5d456 Initial commit
Benjamin Thomas authored
41
42 etmux mySession
43
44 And as would be expected, if the session is already started, `etmux` will just join that session instead of rerunning the script and starting it again.
45
46 The smallest feature complete script I can think of:
47
48 # change the default working directory for this session
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
49 cd /path/to/session/root
9c5d456 Initial commit
Benjamin Thomas authored
50
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
51 # start the session, even if we're already in a session
9c5d456 Initial commit
Benjamin Thomas authored
52 env TMUX= tmux new-session -d -t mySession
53
54 # set up panes and windows
55 tmux split-window -h -t mySession
56
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
57 # join the newly created session
9c5d456 Initial commit
Benjamin Thomas authored
58 if [ -z $TMUX ]; then
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
59 # if we aren't in a session, then attach to the new one
9c5d456 Initial commit
Benjamin Thomas authored
60 tmux attach-session -t mySession
61 else
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
62 # if we are in a session, then switch this client over to the new one
9c5d456 Initial commit
Benjamin Thomas authored
63 tmux switch-client -t mySession
64 fi
65
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
66 The nice thing about writing your scripts like this is that they are regular old shell scripts and you could run them directly if you don't want to use `etmux` and they would work fine.
9c5d456 Initial commit
Benjamin Thomas authored
67
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
68 However, `etmux` can make writing these scripts easier. Because the starting and joining session code is done in every script, `etmux` will pass in the variables `$start` and `$join` which will do that for you. Also having to rewrite the session name so many times makes it a pain to change, so `etmux` will pass in the session name for you as `$session`. Using those variables, our script looks like:
9c5d456 Initial commit
Benjamin Thomas authored
69
70 # change the default working directory for tmux
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
71 cd /path/to/session/root
9c5d456 Initial commit
Benjamin Thomas authored
72
73 $start
74
75 # set up panes and windows
76 tmux split-window -h -t $session
77
78 $join
79
80 Which is pretty simple.
81
82 Sometimes all you want to do is just set the default working directory. I have a lot of scripts that just look like this:
83
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
84 cd /path/to/session/root && $start && $join
85
86 `etmux` can play nicely with starting the `tmux` server using a different socket (try `etmux --help` for more details) but to allow switching sessions work properly with the your scripts, your scripts should use a different `tmux` command. `etmux` also passes in a `$tmux` variable as a replacement for the command. This `$tmux` variable makes sure `tmux` is using the right socket. The updated script would look like:
87
88 cd /path/to/session/root
89
90 $start
91
92 # note use of "$tmux" instead of just "tmux"
93 $tmux split-window -h -t $session
94
95 $join
9c5d456 Initial commit
Benjamin Thomas authored
96
97 You may be thinking that this looks complicated, and that the configuration files of Tmuxinator or Teamocil might be easier. And I mean nothing against either of those projects (they were the inspiration for this project after all), but if you're going to learn how to write configuration files for either of those, why don't you just instead learn the `tmux` API which, while it looks scary at first, is actually pretty straight-forward? Either way you're still learning something new and this way you can use your new found skillz in `tmux` and if you decide you don't like this project you haven't wasted your time!
98
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
99 If you don't want to store your scripts in `~/.etmux-sessions` you can set the `$ETMUX_PATH` environment variable to some other location:
9c5d456 Initial commit
Benjamin Thomas authored
100
d3c360b Add options (help, version, verbose, etc)
Benjamin Thomas authored
101 export ETMUX_PATH=/path/to/sessions/one:/path/to/sessions/two
9c5d456 Initial commit
Benjamin Thomas authored
102
103 ## ZSH Command Line Completion
104
105 `emtux` comes with command line completion for ZSH. To enable this you need to do three things
106
107 First, in your `.zshrc` file, specify a directory for custom completion scripts:
108
109 fpath=(~/.zsh/completion $fpath)
110
111 Second, in your `.zshrc` file, after the previous line, enable completion:
112
113 autoload -U compinit
114 compinit
115
116 Third, put the `_etmux` completion script in the directory specified in the first step:
117
118 mkdir -p ~/.zsh/completion
119 mv zsh_completion/_etmux ~/zsh/completion
120
121 Now you can enjoy tab completion on all active sessions and specified `etmux` scripts.
122
123 Sessions that are currently active are suffixed with a `+`.
124
125 [tmux]: http://tmux.sourceforge.net/
126 [Tmuxinator]: https://github.com/aziz/tmuxinator
127 [Teamocil]: https://github.com/remiprev/teamocil
128
Something went wrong with that request. Please try again.