Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 127 lines (74 sloc) 5.602 kb
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
11 echo "export PATH=$HOME/bin:$PATH" >> ~/.bashrc
12 . ~/.bashrc
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
24 If you want to call your session something else, just give `etmux` a different name:
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
32 To see all the options try:
33
34 etmux --help
35
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
36 ## Predefined Sessions
37
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
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.
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
39
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
40 If you name your script `mySession` and it exists and is executable at `~/.etmux-sessions/mySession` then you can run it with:
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
49 cd /path/to/session/root
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
50
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
51 # start the session, even if we're already in a session
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
52 env TMUX= tmux new-session -d -t mySession
53
54 # set up panes and windows
55 tmux split-window -h -t mySession
56
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
57 # join the newly created session
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
58 if [ -z $TMUX ]; then
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
59 # if we aren't in a session, then attach to the new one
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
60 tmux attach-session -t mySession
61 else
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
62 # if we are in a session, then switch this client over to the new one
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
63 tmux switch-client -t mySession
64 fi
65
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
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.
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
67
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
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:
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
69
70 # change the default working directory for tmux
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
71 cd /path/to/session/root
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
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
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
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:
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
100
d3c360b7 » Benjamin Thomas
2011-10-09 Add options (help, version, verbose, etc)
101 export ETMUX_PATH=/path/to/sessions/one:/path/to/sessions/two
9c5d456a » Benjamin Thomas
2011-10-07 Initial commit
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.