• Stars
    star
    139
  • Rank 262,954 (Top 6 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 7 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tmux scripting made easy

Hey tmux!

GitHub Actions Status Coverage Status Gem

Tmux scripting made easy.

Installation

Heytmux requires Ruby 2.0+ and tmux 2.3+.

As Ruby gem

gem install heytmux
  • Installs heytmux executable

As Vim plugin

Using vim-plug:

Plug 'junegunn/heytmux'
  • Registers :Heytmux command
  • No need to install Gem if you only use Heytmux inside Vim
    • But if you want it to be globally available, Plug 'junegunn/heytmux', { 'do': 'gem install heytmux' }

Usage

Create a YAML file that describes a desired tmux workspace.

# workspace.yml
- first window:
    layout: tiled
    panes:
      - first pane: sleep 1
      - second pane: sleep 2
      - third pane: |
          sleep 3
          sleep 4

- second window:
    layout: even-vertical
    pane-border-status: top
    synchronize-panes: true
    panes:
      - pane 2-1: sleep 5
      - pane 2-2: sleep 6

Then run heytmux workspace.yml.

Instead of creating a new session from scratch, Heytmux looks at the current session and only creates windows and panes that are not found. So you can repeatedly run the same input file only to issue commands on the existing panes.

Heytmux identifies windows and panes by their names and titles, so renaming them can confuse Heytmux. Duplicate names are okay as long as you don't reorder windows or panes of the same names.

More examples can be found here.

Heytmux can read STDIN, so cat workspace.yml | heytmux is also valid. It may seem pointless, but it allows you to do :w !heytmux with a visual selection in Vim.

Step-by-step tutorial

List of window names

In the simplest case, input file only has to contain the names of windows as the top-level list. Create workspace.yml and add the following lines.

- window 1
- window 2
- window 3

heytmux workspace.yml will create 3 windows with the given names. If you re-run the same command, you'll notice Heytmux doesn't create more windows as they already exist.

Windows and panes

Well, that was not particularly interesting. Let's split the windows and run some commands.

First run heytmux --kill workspace.yml to kill the windows we just created, and update your input file as follows:

- window 1:
  - echo 1-1
  - echo 1-2
  - echo 1-3
- window 2:
  - echo 2-1
  - echo 2-2
- window 3:
  - sleep 3

Run Heytmux with it and you'll see that panes are created under the windows to run those commands. If you rerun the same command, Heytmux will send them again to the same panes. No new panes are created.

Pane titles

However, if you change a command on the input file (e.g. echo 1-1 to sleep 1) and run Heytmux, a new pane for the command will be created. That's because Heytmux identifies windows and panes by their names and titles, and in the above case, the title of a pane is implicitly set to the given command. So changing the command changes the identifier of the pane, and Heytmux no longer can find the previous pane.

To reuse the existing panes, you have to explictly name the panes. Update the input file, close the windows (heytmux --kill workspace.yml), and rerun the command.

- window 1:
  - pane 1: sleep 1
  - pane 2: sleep 2
  - pane 3: sleep 3
- window 2:
  - pane 2-1: sleep 1
  - pane 2-2: |
      sleep 2
      sleep 3

Now, you can freely change the commands without worrying about getting extra panes. You can also create and use input files for any subset of the panes.

# In another file
- window 2:
  - pane 2: echo 'I slept 5 seconds!'

Window layout and options

What if we want to change the layout of the windows, or if we want to set some window options of tmux? To do that, move the list of panes to panes under each window entry, so you can specify additional settings.

- window 1:
    layout: even-horizontal
    synchronize-panes: true
    pane-border-status: bottom
    panes:
      - pane 1: sleep 1
      - pane 2: sleep 2
      - pane 3: sleep 3
- window 2:
    layout: even-horizontal
    synchronize-panes: true
    pane-border-status: top
    panes:
      - pane 2-1: sleep 1
      - pane 2-2: |
          sleep 1
          sleep 2

Root layout and options

That's nice, but looks like we're repeating ourselves with the same options. We can reorganize the input file as follows to define the root layout and options that are applied to all windows.

layout: even-horizontal
synchronize-panes: true
pane-border-status: bottom

windows:
  - window 1:
      panes:
        - pane 1: sleep 1
        - pane 2: sleep 2
        - pane 3: sleep 3
  - window 2:
      # Override root option
      pane-border-status: top
      panes:
        - pane 2-1: sleep 1
        - pane 2-2: |
            sleep 1
            sleep 2

Expanding panes with {{ item }}

The panes under window 1 in the previous example are similar in their names and commands, and this is a very common case. To avoid repetition, set items list for a window, then panes with {{ item }} in their titles will be expanded according to the list.

# Equivalent to the previous example
- window 1:
    items: [1, 2, 3]
    panes:
      - pane {{item}}: sleep {{item}}

Note that you have to quote a pane title if it starts with {{.

This is often useful when you have to work with a series of log files or with a set of servers.

- servers:
    layout: tiled
    items:
      - west-host1
      - west-host2
      - east-host1
      - east-host2
    panes:
      - ssh user@{{item}} tail -f /var/log/server-{{item}}.log

Also note that {{ item.index }} expands to zero-based index of the item.

Referring to environment variables

You can refer to environment variables using {{ $ENV_VAR }} syntax. For default values, use {{ $ENV_VAR | the-default-value }} syntax. Heytmux will not start if an environment variable is not defined and there's no default value.

Expecting pattern

Sometimes it's not enough to just send lines of text at once. For example, the following example will not work as expected.

- servers:
  - server 1: |
      ssh server1
      {{ $MY_SSH_PASSWORD }}
      uptime

With expect construct, you can make Heytmux wait until a certain regular expression pattern appears on the pane (a la Expect).

- servers:
  - server 1:
    - ssh server1
    - expect: '[Pp]assword:'
    - {{ $MY_SSH_PASSWORD }}
    - uptime

Special commands

In addition to expect, Heytmux also supports sleep and keys commands. sleep suspends the execution for a given time period. It's useful when the shell on the target pane is non-interactive so you can't send sleep command to it. keys command is for sending special keys, such as c-c (CTRL-C) using tmux send-keys command. To send multiple keys, specify the keys as a YAML list (e.g. [c-c, c-l]).

- servers:
  - server 1:
    - vmstat 2 | tee log
    - sleep: 3
    - keys: c-c

Vim plugin

You don't really need a Vim plugin for Heytmux (because :w !heytmux will just do), but here's one anyway, to save you some typing.

  • :Heytmux [OPTIONS]
    • Run with the current file
  • :Heytmux [OPTIONS] FILES...
    • Run with the files
  • :'<,'>Heytmux [OPTIONS] (in visual mode)
    • Run with the given range

Use bang version of the command (:Heytmux!) not to move focus. It is equivalent to passing -d flag to heytmux executable.

Related projects

Many of the ideas were borrowed from Tmuxinator and Ansible, but Heytmux solves a different problem.

There are also other projects that are similar to tmuxinator.

How is this different from tmuxinator?

With Tmuxinator, you can manage session configurations each of which defines the initial layout of a tmux session.

On the other hand, Heytmux does not care about sessions, instead it simply creates windows and panes on the current session, and it only creates the ones that don't exist. So it can be used not only to bootstrap the initial workspace, but also to send commands to any subset of the existing panes, which means you can use it for scripting your tasks that span multiple tmux windows and panes. Heytmux somehow feels like a hybrid of Tmuxinator and Ansible.

I primarily use Heytmux to write Markdown documents with fenced code blocks of YAML snippets that I can easily select and run with Heytmux in my editor.

License

MIT

More Repositories

1

fzf

🌸 A command-line fuzzy finder
Go
55,523
star
2

vim-plug

🌺 Minimalist Vim Plugin Manager
Vim Script
33,335
star
3

fzf.vim

fzf ❤️ vim
Vim Script
9,178
star
4

goyo.vim

🌷 Distraction-free writing in Vim
Vim Script
4,404
star
5

vim-easy-align

🌻 A Vim alignment plugin
Vim Script
3,981
star
6

limelight.vim

🔦 All the world's indeed a stage and we are merely players
Vim Script
2,290
star
7

redis-stat

(UNMAINTAINED) A real-time Redis monitoring tool
Ruby
2,014
star
8

seoul256.vim

🌳 Low-contrast Vim color scheme based on Seoul Colors
Vim Script
1,604
star
9

gv.vim

A git commit browser in Vim
Vim Script
1,286
star
10

vim-peekaboo

👀 " / @ / CTRL-R
Vim Script
1,102
star
11

vim-emoji

😃 Emoji in Vim
Vim Script
606
star
12

vader.vim

A simple Vimscript test framework
Vim Script
571
star
13

vim-github-dashboard

:octocat: Browse GitHub events in Vim
Vim Script
481
star
14

vim-slash

Enhancing in-buffer search experience
Vim Script
322
star
15

fzf-git.sh

bash and zsh key bindings for Git objects, powered by fzf
Shell
280
star
16

vim-journal

📝
Vim Script
259
star
17

myvim

🍱 Script to create a portable bundle of Vim environment
Shell
252
star
18

vim-xmark

Live markdown preview for Vim on macOS (UNMAINTAINED; see https://github.com/iamcco/markdown-preview.nvim)
CSS
135
star
19

fzf-bin

117
star
20

vim-after-object

👉 Target text *after* the designated characters
Vim Script
112
star
21

vim-oblique

DEPRECATED Improved /-search (experimental)
Vim Script
83
star
22

vim-startuptime-benchmark

Outdated information
Vim Script
69
star
23

tmux-fzf-url

🚀 Quickly open urls on screen from your browser!
Shell
45
star
24

perlin_noise

Perlin noise generator in Ruby
Ruby
43
star
25

gimchi

Gimchi reads Korean.
Ruby
40
star
26

hbase-jruby

A JRuby binding for HBase
Ruby
38
star
27

tmux-fzf-maccy

Tmux plugin for Maccy and fzf integration
Shell
34
star
28

blsd

List directories in breadth-first order
Go
33
star
29

mvmv

Simple batch renaming script (ruby)
Ruby
27
star
30

vim-fnr

🎭 Find-N-Replace helper free of regular expressions
Vim Script
25
star
31

jdbc-helper

Deprecated. Use Sequel.
Ruby
19
star
32

jruby-daemon-template

Turn a JRuby script into an init-d style daemon
Shell
18
star
33

tabularize

Formatting tabular data with paddings
Ruby
18
star
34

mini-file-server

A simple, insecure file server
Clojure
17
star
35

ansi256

A Rubygem for colorizing text with 256-color ANSI codes
Ruby
16
star
36

vim-pseudocl

Pseudo-command-line (experimental)
Vim Script
16
star
37

insensitive_hash

DEPRECATED: Use hashie
Ruby
15
star
38

pipe-logger

Log rotation of stdout & stderr
Ruby
14
star
39

grouper

A simple batch processing facility
Clojure
12
star
40

vim-redis

Experimental Redis plugin for Vim
Vim Script
12
star
41

lq

A simple HTTP server for queuing lines of text
Clojure
11
star
42

clj-inspector

Inspector helps debugging Clojure programs
Clojure
11
star
43

parallelize

Simple multi-threading for Ruby
Ruby
10
star
44

tre-ruby

Approximate regular expression matching using TRE
Ruby
10
star
45

treely

Library for generating tree diagram of nested data structure
Clojure
9
star
46

junegunn

8
star
47

coffee-processing

Helps writing Processing.js sketches in CoffeeScript
Ruby
8
star
48

ssh-copy-id.rb

Unmaintained
Ruby
7
star
49

agl

List files and directories using ag
Ruby
7
star
50

si

Human-readable numbers with SI prefix (metric prefix)
Ruby
6
star
51

evented-servers

experiments with libev
C
6
star
52

vim-ruby-x

if_ruby helper
Vim Script
6
star
53

microbe

A simple micro benchmark helper for Clojure
Clojure
5
star
54

vim-cfr

Decompile Java class files using CFR
Vim Script
5
star
55

each_line_reverse

Read lines of a file in reverse order
Ruby
4
star
56

shorten

Number shortener
Ruby
4
star
57

proco

experimental: a lightweight asynchronous task executor designed for efficient batch processing
Ruby
4
star
58

lps

lps: rate-controlled loop execution
Ruby
3
star
59

SuperCSV

A fork of SuperCSV project with a few fixes
Java
2
star
60

colored-not

Toggles methods from colored gem
Ruby
2
star
61

img2xterm-clj

img2xterm rewritten in clojure (for no good reason)
Clojure
2
star
62

jrubysql

SQL client for any JDBC-compliant database.
Ruby
2
star
63

linux-scripts

Ruby
2
star
64

zipfian

Zipfian distribution in Ruby
Ruby
2
star
65

rcron

A simple cron-like scheduler for Ruby
Ruby
2
star
66

option_initializer

Object construction with method chaining
Ruby
2
star
67

quote_unquote

Wraps (and unwraps) strings with quotes
Ruby
1
star
68

maven_dependency

A Ruby gem to resolve maven dependencies
Ruby
1
star
69

coffee-processing-live

coffee-processing demo app
JavaScript
1
star
70

tweet-backup-ruby

Ruby script for backing up tweets
Ruby
1
star
71

i

1
star
72

hbase-client-dep

Makefile
1
star
73

each_sql

Enumerate each SQL statement in SQL scripts
Ruby
1
star
74

srsly

SRSLY? NO!
Ruby
1
star
75

omniauth-nate

OmniAuth strategy for Nate.com (Nate/Cyworld)
Ruby
1
star
76

oxm

A tiny Object-XML-Mapper for Ruby
Ruby
1
star