tsess
=====

The purpose of tsess is to manage tmux [1] sessions using a declarative
configuration.  Its goal was to replace tmuxinator [2] to move away from
its YAML-based configuration which is effectively an ERB [3] template
that brings along a complete Ruby [4] stack.

tsess is written in Hare [5] and while that should not matter, this has
several consequences.  For example tmuxinator is written in Ruby and that
creates a runtime dependency on Ruby.  Until Hare reaches 1.0, tsess code
may fail to build with newer Hare releases.  There are features or design
choices that are completely arbitrary because tsess served as a learning
material for Hare.

Nevertheless, tsess is a usable, simple and self-contained tmux session
manager.

Tutorial
--------

To start using tsess, create a new session:

    $ tsess edit tutorial-session

This will prompt a text editor with the following contents:

    name = tutorial-session

The session will effectively be created once the editor terminates.  Let's
add a couple windows to this empty session:

    # BEGIN readme.tsess
    name = tutorial-session
    root = '~/tutorial'

    [@template@]
    root = "@template@"
    layout = main-horizontal
    pane.editor.send-keys = "vim $(git ls-files)"
    pane.prompt.send-keys = << EOF
    git fetch
    git status
    EOF

    [template:tmux]
    env[CC] = clang

    [template:tsess]
    # END readme.tsess

This creates a tmux session called tutorial-session with two windows called
tmux and tsess.  Both windows share the same template that will create a first
pane called editor where vim is executed to open all the files tracked by a
git repository and another pane called prompt that will run 'git fetch' and
'git status' when the session is created.  The working directories of panes
is ~/tutorial/tmux or ~/tutorial/tsess in their respective windows.  In the
tmux window, CC=clang is exported to the environment for both panes.

In other words, tutorial-session configuration will bring up a development
environment to work on both tmux and tsess.  To enter this newly-configured
workspace, let's ask tsess again:

    $ tsess attach tutorial-session

It will attach to the session after creating it if necessary.  It may fail
to create the session, for example when one of the working directories does
not exist.

To learn more about tsess commands and configuration capabilities, read the
comprehensive manuals:

    $ man tsess
    $ man 5 tsess

For installation instructions, refer to the INSTALL file.

[1] https://github.com/tmux/tmux/wiki
[2] https://github.com/tmuxinator/tmuxinator
[3] https://github.com/ruby/erb
[4] https://www.ruby-lang.org/
[5] https://harelang.org/