matemux

matemux is a simple tmux session generator: it generates a session with customized window and pane layouts from a yaml file, called a recipe.

installation

You could install using pip:

$ pip install matemux

usage

$ matemux [RECIPE-FILE-NAME] [--args] [ARGS]...

create the session based on .matemux/RECIPE-FILE-NAME.yml with ARGS following --args flag. $MATEMUX_DIR is ~/.matemux by default. You could change it by setting $MATEMU_DIR in your environment.

examples

$ matemux example --args --command runserver --port 8000 create a session based on ~/.matemux/example.yml and pass command=runserver and port=8000 to example.yml commands.

recipes

each session is generated from a .yml file called a recipe. a sample recipe is shown below:

~/.matemux/example.yml

---
session: example
root: ~/projects/example
defaults:
  command: runserver
  port: 8000
commands:
  - source activate venv/bin/activate
  - C-l
focus: sql
windows:
  - window: main
    focus: 2
    panes:
        - pane: 0
          commands:
            - htop
        - pane: 1
          commands:
            - neofetch
          next-split-vertical: true
        - pane: 2
          root: ~/projects/example/server
          commands:
            - "{{command}} {{port}}"
  - window: home
    root: ~/

At the top level of a .yml file, the following keys could be defined:

• session is the name of the session to be created. It accepts strings and integer values.
• root defines the default directory for all virtual terminals in the session. It must be a valid path. By default, it's set to '~/'.
• defaults is the default arguments to be passed to commands, we'll cover them later on. they should be an object of key-value pairs. It could be omitted.
• commands are a list of commands that are executed in all virtual terminals in the session. it could be omitted.
• focus defines the window to focus on at the initial state of the session. By default, it's the first window. It accepts strings (name of the window) or integers (window number (0, 1, ...))
• windows is a list of window configuration, with the following keys:
  • window is the name of the window. It could be omitted, in that case, it's set by default to its index.
  • root defines the default directory for all panes in the window. It must be a valid path. By default, it's set to the session's root.
  • focus defines the pane to focus on at the initial state of the window. By default, it's the first pane (index 0)
  • panes is a list of pane configuration, with the following keys:
    • pane it's completely optional and has no effect. It could be set to the pane index to make the .yml file more readable, especially in regards to window focus.
    • root defines the default directory for the pane. It must be a valid path. By default, it's set to the parent window's root.
    • commands are a list of commands to be executed in the pane.
    • next-split-vertical is a boolean that defines whether or not the split for the next pane should be vertical. By default, it's set to false. Imagine the current layout is like this:

     ----------------
     |              |
     |      0       |
     |              |
     |              |
     ----------------
    

    if it's false, when if we define another pane, the new layout would be:

    ----------------
    |       |      |
    |   0   |   1  |
    |       |      |
    |       |      |
    ----------------
    

    but if it's true, the new layout would be:

    ----------------
    |      0       |
    |______________|
    |      1       |
    |              |
    ----------------
    

running $ matemux example creates a session with two windows: first window is called main and has the following layout:

---------------
|      |   1  |
|  0   |______|
|      |   2  |
|      |      |
---------------

htop is running in pane 0, neofetch is running in pane 1, and runserver 8000 is running in in pane 2. second window is called home and has a single pane.

Notes about commands and defaults:

• commands are propagated: If you set some commands for a session, some commands for a window, and some commands for a pane, they're all executed in the pane's virtual terminal, in that order.

• You could use custom arguments in commands, in the form {{arg}} and pass the arguments through commandline. For example, if you have a command mysql -u {{user}} you could pass user like this: $ matemux example --args --user myuser if you want a default value for user, you should set it in session's defaults like:

    defaults:
      user: myuser

• It's important to note argument names should only contain characters from the English alphabet and they're case-sensitive.

Author

Kamyab Taghizadeh