Skip to content

Latest commit

 

History

History
584 lines (378 loc) · 10.5 KB

examples.md

File metadata and controls

584 lines (378 loc) · 10.5 KB

(examples)=

Example Configurations

Short hand / inline style

tmuxp has a short-hand syntax to for those who wish to keep their configs punctual.

::::{sidebar} short hand

.. aafig::
   :textual:

    +-------------------+
    | 'did you know'    |
    | 'you can inline'  |
    +-------------------+
    | 'single commands' |
    |                   |
    +-------------------+
    | 'for panes'       |
    |                   |
    +-------------------+

::::

YAML

:language: yaml

JSON

:language: json

Blank panes

No need to repeat pwd or a dummy command. A null, 'blank', 'pane' are valid.

Note '' counts as an empty carriage return.

YAML

:language: yaml

JSON

:language: json

2 panes

::::{sidebar} 2 pane

.. aafig::

    +-----------------+
    | $ pwd           |
    |                 |
    |                 |
    +-----------------+
    | $ pwd           |
    |                 |
    |                 |
    +-----------------+

::::

YAML

:language: yaml

JSON

:language: json

3 panes

::::{sidebar} 3 panes

.. aafig::

    +-----------------+
    | $ pwd           |
    |                 |
    |                 |
    +--------+--------+
    | $ pwd  | $ pwd  |
    |        |        |
    |        |        |
    +--------+--------+

::::

YAML

:language: yaml

JSON

:language: json

4 panes

::::{sidebar} 4 panes

.. aafig::

    +--------+--------+
    | $ pwd  | $ pwd  |
    |        |        |
    |        |        |
    +--------+--------+
    | $ pwd  | $ pwd  |
    |        |        |
    |        |        |
    +--------+--------+

::::

YAML

:language: yaml

JSON

:language: json

Start Directory

Equivalent to tmux new-window -c <start-directory>.

YAML

:language: yaml

JSON

:language: json

Environment variable replacing

tmuxp will replace environment variables wrapped in curly brackets for values of these settings:

  • start_directory
  • before_script
  • session_name
  • window_name
  • shell_command_before
  • global_options
  • options in session scope and window scope

tmuxp replaces these variables before-hand with variables in the terminal tmuxp invokes in.

In this case of this example, assuming the username "user":

$ MY_ENV_VAR=foo tmuxp load examples/env-variables.yaml

and your session name will be session - user (foo).

Shell variables in shell_command do not support this type of concatenation. shell_command and shell_command_before both support normal shell variables, since they are sent into panes automatically via send-key in tmux(1). See ls $PWD in example.

If you have a special case and would like to see behavior changed, please make a ticket on the issue tracker.

YAML

:language: yaml

JSON

:language: json

Environment variables

tmuxp will set session environment variables.

YAML

:language: yaml

JSON

:language: json

Focusing

tmuxp allows focus: true for assuring windows and panes are attached / selected upon loading.

YAML

:language: yaml

JSON

:language: json

Terminal History

tmuxp allows suppress_history: false to override the default command / suppression when building the workspace. This will add the shell_command to the bash history in the pane.

YAML

:language: yaml

JSON

:language: json

Window Index

You can specify a window's index using the window_index property. Windows without window_index will use the lowest available window index.

YAML

:language: yaml

JSON

:language: json

Shell per pane

Every pane can have its own shell or application started. This allows for usage of the remain-on-exit setting to be used properly, but also to have different shells on different panes.

YAML

:language: yaml

JSON

:language: json

Set tmux options

Works with global (server-wide) options, session options and window options.

Including automatic-rename, default-shell, default-command, etc.

YAML

:language: yaml

JSON

:language: json

Set window options after pane creation

Apply window options after panes have been created. Useful for synchronize-panes option after executing individual commands in each pane during creation.

YAML

:language: yaml

JSON

:language: json

Main pane height

YAML

:language: yaml

JSON

:language: json

Super-advanced dev environment

:::{seealso}

{ref}tmuxp developer config in the {ref}developing section.

:::

YAML

:language: yaml

JSON

:language: json

Multi-line commands

You can use YAML's multiline syntax to easily split multiple commands into the same shell command: https://stackoverflow.com/a/21699210


session_name: my project
shell_command_before: 
- >
  [ -d `.venv/bin/activate` ] &&
  source .venv/bin/activate &&
  reset
- sleep 1
windows:
- window_name: first window
  layout: main-horizontal
  focus: true
  panes:
  - focus: True
  - blank
  - >
    poetry run ./manage.py migrate &&
    npm -C js run start
  - poetry run ./manage.py runserver
  options:
    main-pane-height: 35

Bootstrap project before launch

You can use before_script to run a script before the tmux session starts building. This can be used to start a script to create a virtualenv or download a virtualenv/rbenv/package.json's dependency files before tmuxp even begins building the session.

It works by using the Exit Status code returned by a script. Your script can be any type, including bash, python, ruby, etc.

A successful script will exit with a status of 0.

Important: the script file must be chmod executable +x or 755.

Run a python script (and check for it's return code), the script is relative to the .tmuxp.yaml's root (Windows and panes omitted in this example):


session_name: my session
before_script: ./bootstrap.py
# ... the rest of your config



{
    "session_name": "my session",
    "before_script": "./bootstrap.py"
}

Run a shell script + check for return code on an absolute path. (Windows and panes omitted in this example)


session_name: another example
before_script: /absolute/path/this.sh # abs path to shell script
# ... the rest of your config



{
    "session_name": "my session",
    "before_script": "/absolute/path/this.sh"
}

Per-project tmux config

You can load your software project in tmux by placing a .tmuxp.yaml or .tmuxp.json in the project's config and loading it.

tmuxp supports loading configs via absolute filename with tmuxp load and via $ tmuxp load . if config is in directory.


$ tmuxp load ~/workspaces/myproject.yaml

See examples of tmuxp in the wild. Have a project config to show off? Edit this page.

You can use start_directory: ./ to make the directories relative to the config file / project root.

Bonus: pipenv auto-bootstrapping

:::{versionadded} 1.3.4

before_script CWD's into the root (session)-level start_directory.

:::

If you use pipenv / poetry, you can use a script like this to ensure your packages are installed:


# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
windows:
- window_name: django project
  focus: true
  panes:
  - blank
  - pipenv run ./manage.py runserver

You can also source yourself into the virtual environment using shell_command_before:


# assuming your .tmuxp.yaml is in your project root directory
session_name: my pipenv project
start_directory: ./
before_script: pipenv install --dev --skip-lock # ensure dev deps install
shell_command_before:
- '[ -d `pipenv --venv` ] && source `pipenv --venv`/bin/activate && reset'
windows:
- window_name: django project
  focus: true
  panes:
  - blank
  - ./manage.py runserver

Kung fu

:::{note}

tmuxp sessions can be scripted in python. The first way is to use the ORM in the {ref}API. The second is to pass a {py:obj}dict into {class}~tmuxp.workspacebuilder.WorkspaceBuilder with a correct schema. See: {meth}tmuxp.config.validate_schema.

:::

Add yours? Submit a pull request to the github site!