(examples)=

Examples

Short hand / inline style

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

::::{sidebar} short hand

.. aafig::
   :textual:

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

::::


```{literalinclude} ../../examples/shorthands.yaml
:language: yaml

```


```{literalinclude} ../../examples/shorthands.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.


```{literalinclude} ../../examples/blank-panes.yaml
:language: yaml

```


```{literalinclude} ../../examples/blank-panes.json
:language: json

```

2 panes

::::{sidebar} 2 pane

.. aafig::

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

::::


```{literalinclude} ../../examples/2-pane-vertical.yaml
:language: yaml

```


```{literalinclude} ../../examples/2-pane-vertical.json
:language: json

```

3 panes

::::{sidebar} 3 panes

.. aafig::

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

::::


```{literalinclude} ../../examples/3-pane.yaml
:language: yaml

```


```{literalinclude} ../../examples/3-pane.json
:language: json

```

4 panes

::::{sidebar} 4 panes

.. aafig::

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

::::


```{literalinclude} ../../examples/4-pane.yaml
:language: yaml

```


```{literalinclude} ../../examples/4-pane.json
:language: json

```

Start Directory

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


```{literalinclude} ../../examples/start-directory.yaml
:language: yaml

```


```{literalinclude} ../../examples/start-directory.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.


```{literalinclude} ../../examples/env-variables.yaml
:language: yaml

```


```{literalinclude} ../../examples/env-variables.json
:language: json

```

Environment variables

tmuxp will set session, window and pane environment variables.


Setting environment variables for windows and panes requires tmuxp 1.19 or
newer and tmux 3.0 or newer.


```{literalinclude} ../../examples/session-environment.yaml
:language: yaml

```


```{literalinclude} ../../examples/session-environment.json
:language: json

```

`if` conditions

tmuxp enables one to optionally open windows / panes based on conditions. The if conditions can appears in the configuration for window or pane.


```{literalinclude} ../../examples/if-conditions.yaml
:language: yaml

```


```{literalinclude} ../../examples/if-conditions.json
:language: json

```

In the example, running the example

$ tmuxp load examples/if-conditions.yaml

should produce only a window with upper and lower split panes (others should have if conditions that evaluates to false). This example allows for on-demand pane showing, where

$ show_htop=false tmuxp load examples/if-conditions.yaml

will instead suppress the htop command pane and resulting in a different behaviour.

Focusing

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


```{literalinclude} ../../examples/focus-window-and-panes.yaml
:language: yaml

```


```{literalinclude} ../../examples/focus-window-and-panes.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 shell history in the pane. The suppression of the shell_command commands from the shell's history occurs by prefixing the commands with a space when suppress_history: true. Accordingly, this functionality depends on the shell being appropriately configured: bash requires the shell variable HISTCONTROL to be set and include either of the values ignorespace or ignoreboth (to also ignore sequential duplicate commands), and zsh requires setopt HIST_IGNORE_SPACE.


```{literalinclude} ../../examples/suppress-history.yaml
:language: yaml

```


```{literalinclude} ../../examples/suppress-history.json
:language: json

```

(enter)=

Skip command execution

See more at {ref}enter.

:::{note}

Experimental setting: behavior and api is subject to change until stable.

:::

`enter: false` option. Pane-level support.

Omit sending {kbd}enter to key commands. Equivalent to send_keys(enter=False).


```{literalinclude} ../../examples/skip-send.yaml
:language: yaml

```


```{literalinclude} ../../examples/skip-send.json
:language: json

```


```{literalinclude} ../../examples/skip-send-pane-level.yaml
:language: yaml

```


```{literalinclude} ../../examples/skip-send-pane-level.json
:language: json

```

(sleep)=

Pausing commands

:::{note}

Experimental setting: behavior and api is subject to change until stable.

:::

`sleep_before` and `sleep_after` options added. Pane and command-level support.

**Blocking.** This will delay loading as it runs synchronously for each pane as [`asyncio`](asyncio)) is not implemented yet.

Omit sending {kbd}enter to key commands. Equivalent to having a time.sleep before and after send_keys.

This is especially useful for expensive commands where the terminal needs some breathing room (virtualenv, poetry, pipenv, sourcing a configuration, launching a tui app, etc).


```{literalinclude} ../../examples/sleep-virtualenv.yaml
:language: yaml

```


```{literalinclude} ../../examples/sleep.yaml
:language: yaml

```


```{literalinclude} ../../examples/sleep.json
:language: json

```


```{literalinclude} ../../examples/sleep-pane-level.yaml
:language: yaml

```


```{literalinclude} ../../examples/sleep-pane-level.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.


```{literalinclude} ../../examples/window-index.yaml
:language: yaml

```


```{literalinclude} ../../examples/window-index.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.


```{literalinclude} ../../examples/pane-shell.yaml
:language: yaml

```


```{literalinclude} ../../examples/pane-shell.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.


```{literalinclude} ../../examples/options.yaml
:language: yaml

```

```{literalinclude} ../../examples/options.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.

```{literalinclude} ../../examples/2-pane-synchronized.yaml
:language: yaml

```

```{literalinclude} ../../examples/2-pane-synchronized.json
:language: json

```

Main pane height

Percentage

:::{versionadded} 1.46.0

Before this, tmuxp layouts would not detect the terminal's size.

:::

```{literalinclude} ../../examples/main-pane-height-percentage.yaml
:language: yaml

```

```{literalinclude} ../../examples/main-pane-height-percentage.json
:language: json

```

Rows

```{literalinclude} ../../examples/main-pane-height.yaml
:language: yaml

```

```{literalinclude} ../../examples/main-pane-height.json
:language: json

```

Super-advanced dev environment

:::{seealso}

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

:::

```{literalinclude} ../../.tmuxp.yaml
:language: yaml

```

```{literalinclude} ../../.tmuxp.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

```yaml
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):

```yaml
session_name: my session
before_script: ./bootstrap.py
# ... the rest of your workspace

```

```json
{
    "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)


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

```


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

```

Per-project tmuxp workspaces

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

tmuxp supports loading workspace via absolute filename with tmuxp load and via $ tmuxp load . if workspace is in the directory.

$ tmuxp load ~/workspaces/myproject.yaml

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

https://github.com/tony/dockerfiles/blob/master/.tmuxp.yaml
https://github.com/vcs-python/vcspull/blob/master/.tmuxp.yaml
https://github.com/tony/sphinxcontrib-github/blob/master/.tmuxp.yaml

You can use start_directory: ./ to make the directories relative to the workspace 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:


```yaml
# 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:


```yaml
# 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.workspace.builder.WorkspaceBuilder with a correct schema. See: {meth}tmuxp.validation.validate_schema.

:::

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

examples.md

examples.md

Examples

Short hand / inline style

Blank panes

2 panes

3 panes

4 panes

Start Directory

Environment variable replacing

Environment variables

`if` conditions

Focusing

Terminal History

Skip command execution

Pausing commands

Window Index

Shell per pane

Set tmux options

Set window options after pane creation

Main pane height

Percentage

Rows

Super-advanced dev environment

Multi-line commands

Bootstrap project before launch

Per-project tmuxp workspaces

Bonus: pipenv auto-bootstrapping

Kung fu

Files

examples.md

Latest commit

History

examples.md

File metadata and controls

Examples

Short hand / inline style

Blank panes

2 panes

3 panes

4 panes

Start Directory

Environment variable replacing

Environment variables

if conditions

Focusing

Terminal History

Skip command execution

Pausing commands

Window Index

Shell per pane

Set tmux options

Set window options after pane creation

Main pane height

Percentage

Rows

Super-advanced dev environment

Multi-line commands

Bootstrap project before launch

Per-project tmuxp workspaces

Bonus: pipenv auto-bootstrapping

Kung fu

`if` conditions