Ob-tmux is an Emacs library that allows org mode to evaluate code blocks in a tmux session.
Switch branches/tags
Clone or download
ahendriksen Fix bug where trailing semicolon at end of line would be omitted
Tmux assumes a semicolon at the end of a command-line argument means
that a new command is started. See tmux man page around "Multiple
commands may ... a command sequence." This allows, for example, the
following two commands to be executed in one line:

    tmux new-window; split-window -d

Unfortunately, this behaviour meant that trailing semicolons would not
be sent from ob-tmux. For instance,

echo hello;

would yield

> echo hello

In bash, a semi-colon is also interpreted as a command
separator. Hence, zapping the semicolon would usually not cause any
problems. It does, however, cause problems in multi-line strings,
heredocs, etc.

In short, the bug has now been fixed. I have checked that tmux does
not eat any other characters. The code that removes the semicolon is
in the function cmd_list_parse in the file cmd-list.c in the tmux
source code.
Latest commit 73bed0e Aug 31, 2018

README.org

ob-tmux

Ob-tmux is an Emacs library that allows org mode to evaluate code blocks in a tmux session.

Ob-tmux is useful for keeping notes on how to perform tasks in the terminal, especially when some interactivity is required. The functionality can be used to document software installation, build instructions, and administrative tasks. The documentation can be tested and adjusted while it is written.

Installation

This package is available on from MELPA.

If you have added MELPA to your package sources, you can install ob-tmux interactively

M-x package-install [RET] ob-tmux [RET]

Alternatively, you can copy the ob-tmux.el file to a directory in your load-path.

Configuration

In your .emacs or .emacs.d/init.el file, add the following:

(require 'ob-tmux)
(setq org-babel-default-header-args:tmux
  '((:results . "silent")		;
    (:session . "default")	; The default tmux session to send code to
    (:socket  . nil)              ; The default tmux socket to communicate with
    ;; You can use "xterm" and "gnome-terminal".
    ;; On mac, you can use "iterm" as well.
    (:terminal . "gnome-terminal")))

;; The tmux sessions are prefixed with the following string.
;; You can customize this if you like.
(setq org-babel-tmux-session-prefix "ob-")

;; Finally, if your tmux is not in your $PATH for whatever reason, you
;; may set the path to the tmux binary as follows:
(setq org-babel-tmux-location "/usr/bin/tmux")

If you use use-package, you can also write

(use-package ob-tmux
  ;; Install package automatically (optional)
  :ensure t
  :custom
  (org-babel-default-header-args:tmux
   '((:results . "silent")	 ;
     (:session . "default")	 ; The default tmux session to send code to
     (:socket  . nil)            ; The default tmux socket to communicate with
     ;; You can use "xterm" and "gnome-terminal".
     ;; On mac, you can use "iterm" as well.
     (:terminal . "gnome-terminal")))
  ;; The tmux sessions are prefixed with the following string.
  ;; You can customize this if you like.
  (org-babel-tmux-session-prefix "ob-")
  ;; Finally, if your tmux is not in your $PATH for whatever reason, you
  ;; may set the path to the tmux binary as follows:
  (org-babel-tmux-location "/usr/bin/tmux"))

Usage

You can start a new terminal window with a tmux session as follows:

#+BEGIN_SRC tmux :session hello
echo hello
#+END_SRC

If you press C-c C-c with your point in the code block, a terminal window will pop up with a new tmux session named org-babel-session-hello.

You can continue work in this session with another code block.

#+BEGIN_SRC tmux :session hello
echo world
#+END_SRC

If you press C-c C-c now, no new terminal window will open, but the code will be sent to the existing tmux session.

You can also specify to which tmux window the source block should be sent. If the tmux window does not yet exist, ob-tmux will create it. To specify the window, you may use the tmux target syntax. In the following example, the :session argument has been changed to hello:new-world:

#+BEGIN_SRC tmux :session hello:new-window
echo hello world in new-window
#+END_SRC

Executing this code block will add a window, new-window, to your session.

You can exit your tmux session by detaching. The terminal window will close automatically. Ob-tmux will not detect that you have detached. Any commands you send will be sent to the tmux session in the background. You can reattach to your tmux session at any time and check that the commands have indeed been executed.

Tip. Ob-tmux is also very useful for restarting your tmux sessions after a reboot. Take a look at the following snippet.

** Startup tmux
Use ~C-c C-v s~ to execute subtree.
*** Jupyter
#+BEGIN_SRC tmux :session daemons:jupyter
cd ~/projects/notebooks/
jupyter notebook
#+END_SRC
*** htop
#+BEGIN_SRC tmux session daemons:htop
htop
#+END_SRC
*** dmesg
#+BEGIN_SRC tmux :session daemons:dmesg
dmesg
#+END_SRC

If your point is on the Startup tmux header, you can execute all code blocks in the subtree with C-c C-v s to restart your favorite tmux sessions.

Sockets: remoting

If you want your code to execute on a remote machine, you can use ob-tmux too. There are two ways to control a remote machine. The first is to simply SSH into the remote machine and execute code from there:

#+BEGIN_SRC tmux
ssh remote-machine
#+END_SRC
#+BEGIN_SRC tmux
echo do things...
#+END_SRC

This method has one big downside: long-running code might be interrupted when you lose connection. This method does not start a tmux session on the remote computer; it only starts a tmux session on the local computer.

The other method is to start a remote tmux session and share the remote tmux socket with your local machine. It is possible to start a remote tmux session:

ssh remote-machine -t tmux new -d

This creates a socket on the remote machine. You can forward this socket to the local machine as follows:

REMOTE_SOCKET=$(ssh remote-machine  'tmux ls -F "#{socket_path}"' | head -1)
echo $REMOTE_SOCKET
ssh remote-machine -tfN \
    -L ~/.tmux-local-socket-remote-machine:$REMOTE_SOCKET

Now you can execute code on the remote machine:

#+BEGIN_SRC tmux :socket ~/.tmux-local-socket-remote-machine :session hello
echo hello from remote machine
#+END_SRC

There are some advantages to this method, especially with long running jobs. For instance, if your local machine is rebooted the remote tmux session remains running and you can always reconnect. Furthermore, you do not have to prepend ssh remote-machine to every tmux source code block. This saves time and makes sure that you code is reexecutable: you can execute the same code block twice and it will (hopefully) work the same. It will not try to SSH into the remote machine again while it is already logged in remotely.

Known bugs and or possible issues

My tmux indexes start at 1. By default, tmux window indexes start at zero. This might lead to problems. I have not yet checked.

Terminals other than xterm and gnome-terminal have not been tested. If you have positive or negative experiences with any other terminal, let me know.

I will try to respond within a week to any issues raised. I cannot promise I will fix them.

Contributions

Contributions are always welcome. Please be in touch before you make sweeping changes or add large features. This may prevent disappointment and will help me help you.