1(examples)= 2 3# Example Configurations 4 5## Short hand / inline style 6 7tmuxp has a short-hand syntax to for those who wish to keep their configs 8punctual. 9 10::::{sidebar} short hand 11 12```{eval-rst} 13.. aafig:: 14 :textual: 15 16 +-------------------+ 17 | 'did you know' | 18 | 'you can inline' | 19 +-------------------+ 20 | 'single commands' | 21 | | 22 +-------------------+ 23 | 'for panes' | 24 | | 25 +-------------------+ 26``` 27 28:::: 29 30### YAML 31 32```{literalinclude} ../examples/shorthands.yaml 33:language: yaml 34 35``` 36 37### JSON 38 39```{literalinclude} ../examples/shorthands.json 40:language: json 41 42``` 43 44## Blank panes 45 46No need to repeat `pwd` or a dummy command. A `null`, `'blank'`, 47`'pane'` are valid. 48 49Note `''` counts as an empty carriage return. 50 51### YAML 52 53```{literalinclude} ../examples/blank-panes.yaml 54:language: yaml 55 56``` 57 58### JSON 59 60```{literalinclude} ../examples/blank-panes.json 61:language: json 62 63``` 64 65## 2 panes 66 67::::{sidebar} 2 pane 68 69```{eval-rst} 70.. aafig:: 71 72 +-----------------+ 73 | $ pwd | 74 | | 75 | | 76 +-----------------+ 77 | $ pwd | 78 | | 79 | | 80 +-----------------+ 81``` 82 83:::: 84 85### YAML 86 87```{literalinclude} ../examples/2-pane-vertical.yaml 88:language: yaml 89 90``` 91 92### JSON 93 94```{literalinclude} ../examples/2-pane-vertical.json 95:language: json 96 97``` 98 99## 3 panes 100 101::::{sidebar} 3 panes 102 103```{eval-rst} 104.. aafig:: 105 106 +-----------------+ 107 | $ pwd | 108 | | 109 | | 110 +--------+--------+ 111 | $ pwd | $ pwd | 112 | | | 113 | | | 114 +--------+--------+ 115``` 116 117:::: 118 119### YAML 120 121```{literalinclude} ../examples/3-pane.yaml 122:language: yaml 123 124``` 125 126### JSON 127 128```{literalinclude} ../examples/3-pane.json 129:language: json 130 131``` 132 133## 4 panes 134 135::::{sidebar} 4 panes 136 137```{eval-rst} 138.. aafig:: 139 140 +--------+--------+ 141 | $ pwd | $ pwd | 142 | | | 143 | | | 144 +--------+--------+ 145 | $ pwd | $ pwd | 146 | | | 147 | | | 148 +--------+--------+ 149``` 150 151:::: 152 153### YAML 154 155```{literalinclude} ../examples/4-pane.yaml 156:language: yaml 157 158``` 159 160### JSON 161 162```{literalinclude} ../examples/4-pane.json 163:language: json 164 165``` 166 167## Start Directory 168 169Equivalent to `tmux new-window -c <start-directory>`. 170 171### YAML 172 173```{literalinclude} ../examples/start-directory.yaml 174:language: yaml 175 176``` 177 178### JSON 179 180```{literalinclude} ../examples/start-directory.json 181:language: json 182 183``` 184 185## Environment variable replacing 186 187tmuxp will replace environment variables wrapped in curly brackets 188for values of these settings: 189 190- `start_directory` 191- `before_script` 192- `session_name` 193- `window_name` 194- `shell_command_before` 195- `global_options` 196- `options` in session scope and window scope 197 198tmuxp replaces these variables before-hand with variables in the 199terminal `tmuxp` invokes in. 200 201In this case of this example, assuming the username "user": 202 203``` 204$ MY_ENV_VAR=foo tmuxp load examples/env-variables.yaml 205``` 206 207and your session name will be `session - user (foo)`. 208 209Shell variables in `shell_command` do not support this type of 210concatenation. `shell_command` and `shell_command_before` both 211support normal shell variables, since they are sent into panes 212automatically via `send-key` in `tmux(1)`. See `ls $PWD` in 213example. 214 215If you have a special case and would like to see behavior changed, 216please make a ticket on the [issue tracker][issue tracker]. 217 218[issue tracker]: https://github.com/tmux-python/tmuxp/issues 219 220### YAML 221 222```{literalinclude} ../examples/env-variables.yaml 223:language: yaml 224 225``` 226 227### JSON 228 229```{literalinclude} ../examples/env-variables.json 230:language: json 231 232``` 233 234## Environment variables 235 236tmuxp will set session environment variables. 237 238### YAML 239 240```{literalinclude} ../examples/session-environment.yaml 241:language: yaml 242 243``` 244 245### JSON 246 247```{literalinclude} ../examples/session-environment.json 248:language: json 249 250``` 251 252## Focusing 253 254tmuxp allows `focus: true` for assuring windows and panes are attached / 255selected upon loading. 256 257### YAML 258 259```{literalinclude} ../examples/focus-window-and-panes.yaml 260:language: yaml 261 262``` 263 264### JSON 265 266```{literalinclude} ../examples/focus-window-and-panes.json 267:language: json 268 269``` 270 271## Terminal History 272 273tmuxp allows `suppress_history: false` to override the default command / 274suppression when building the workspace. 275This will add the `shell_command` to the bash history in the pane. 276 277### YAML 278 279```{literalinclude} ../examples/suppress-history.yaml 280:language: yaml 281 282``` 283 284### JSON 285 286```{literalinclude} ../examples/suppress-history.json 287:language: json 288 289``` 290 291## Window Index 292 293You can specify a window's index using the `window_index` property. Windows 294without `window_index` will use the lowest available window index. 295 296### YAML 297 298```{literalinclude} ../examples/window-index.yaml 299:language: yaml 300 301``` 302 303### JSON 304 305```{literalinclude} ../examples/window-index.json 306:language: json 307 308``` 309 310## Set tmux options 311 312Works with global (server-wide) options, session options 313and window options. 314 315Including `automatic-rename`, `default-shell`, 316`default-command`, etc. 317 318### YAML 319 320```{literalinclude} ../examples/options.yaml 321:language: yaml 322 323``` 324 325### JSON 326 327```{literalinclude} ../examples/options.json 328:language: json 329 330``` 331 332## Set window options after pane creation 333 334Apply window options after panes have been created. Useful for 335`synchronize-panes` option after executing individual commands in each 336pane during creation. 337 338### YAML 339 340```{literalinclude} ../examples/2-pane-synchronized.yaml 341:language: yaml 342 343``` 344 345### JSON 346 347```{literalinclude} ../examples/2-pane-synchronized.json 348:language: json 349 350``` 351 352## Main pane height 353 354### YAML 355 356```{literalinclude} ../examples/main-pane-height.yaml 357:language: yaml 358 359``` 360 361### JSON 362 363```{literalinclude} ../examples/main-pane-height.json 364:language: json 365 366``` 367 368## Super-advanced dev environment 369 370:::{seealso} 371 372{ref}`tmuxp developer config` in the {ref}`developing` section. 373 374::: 375 376### YAML 377 378```{literalinclude} ../.tmuxp.yaml 379:language: yaml 380 381``` 382 383### JSON 384 385```{literalinclude} ../.tmuxp.json 386:language: json 387 388``` 389 390 391## Multi-line commands 392 393You can use YAML's multiline syntax to easily split multiple 394commands into the same shell command: https://stackoverflow.com/a/21699210 395 396```{code-block} yaml 397 398session_name: my project 399shell_command_before: 400- > 401 [ -d `.venv/bin/activate` ] && 402 source .venv/bin/activate && 403 reset 404- sleep 1 405windows: 406- window_name: first window 407 layout: main-horizontal 408 focus: true 409 panes: 410 - focus: True 411 - blank 412 - > 413 poetry run ./manage.py migrate && 414 npm -C js run start 415 - poetry run ./manage.py runserver 416 options: 417 main-pane-height: 35 418``` 419 420## Bootstrap project before launch 421 422You can use `before_script` to run a script before the tmux session 423starts building. This can be used to start a script to create a virtualenv 424or download a virtualenv/rbenv/package.json's dependency files before 425tmuxp even begins building the session. 426 427It works by using the [Exit Status][exit status] code returned by a script. Your 428script can be any type, including bash, python, ruby, etc. 429 430A successful script will exit with a status of `0`. 431 432Important: the script file must be chmod executable `+x` or `755`. 433 434Run a python script (and check for it's return code), the script is 435_relative to the `.tmuxp.yaml`'s root_ (Windows and panes omitted in 436this example): 437 438```{code-block} yaml 439 440session_name: my session 441before_script: ./bootstrap.py 442# ... the rest of your config 443 444``` 445 446```{code-block} json 447 448{ 449 "session_name": "my session", 450 "before_script": "./bootstrap.py" 451} 452 453``` 454 455Run a shell script + check for return code on an absolute path. (Windows 456and panes omitted in this example) 457 458```{code-block} yaml 459 460session_name: another example 461before_script: /absolute/path/this.sh # abs path to shell script 462# ... the rest of your config 463 464``` 465 466```{code-block} json 467 468{ 469 "session_name": "my session", 470 "before_script": "/absolute/path/this.sh" 471} 472 473``` 474 475[exit status]: http://tldp.org/LDP/abs/html/exit-status.html 476 477## Per-project tmux config 478 479You can load your software project in tmux by placing a `.tmuxp.yaml` or 480`.tmuxp.json` in the project's config and loading it. 481 482tmuxp supports loading configs via absolute filename with `tmuxp load` 483and via `$ tmuxp load .` if config is in directory. 484 485```{code-block} bash 486 487$ tmuxp load ~/workspaces/myproject.yaml 488 489``` 490 491See examples of `tmuxp` in the wild. Have a project config to show off? 492Edit this page. 493 494- <https://github.com/tony/dockerfiles/blob/master/.tmuxp.yaml> 495- <https://github.com/tony/vcspull/blob/master/.tmuxp.yaml> 496- <https://github.com/tony/sphinxcontrib-github/blob/master/.tmuxp.yaml> 497 498You can use `start_directory: ./` to make the directories relative to 499the config file / project root. 500 501## Bonus: pipenv auto-bootstrapping 502 503:::{versionadded} 1.3.4 504 505`before_script` CWD's into the root (session)-level 506`start_directory`. 507 508::: 509 510If you use [pipenv][pipenv] / [poetry][poetry], you can use a script like this to ensure 511your packages are installed: 512 513```{code-block} yaml 514 515# assuming your .tmuxp.yaml is in your project root directory 516session_name: my pipenv project 517start_directory: ./ 518before_script: pipenv install --dev --skip-lock # ensure dev deps install 519windows: 520- window_name: django project 521 focus: true 522 panes: 523 - blank 524 - pipenv run ./manage.py runserver 525 526``` 527 528You can also source yourself into the virtual environment using 529`shell_command_before`: 530 531```{code-block} yaml 532 533# assuming your .tmuxp.yaml is in your project root directory 534session_name: my pipenv project 535start_directory: ./ 536before_script: pipenv install --dev --skip-lock # ensure dev deps install 537shell_command_before: 538- '[ -d `pipenv --venv` ] && source `pipenv --venv`/bin/activate && reset' 539windows: 540- window_name: django project 541 focus: true 542 panes: 543 - blank 544 - ./manage.py runserver 545 546``` 547 548[pipenv]: https://docs.pipenv.org/ 549[poetry]: https://python-poetry.org/ 550 551## Kung fu 552 553:::{note} 554 555tmuxp sessions can be scripted in python. The first way is to use the 556ORM in the {ref}`API`. The second is to pass a {py:obj}`dict` into 557{class}`~tmuxp.workspacebuilder.WorkspaceBuilder` with a correct schema. 558See: {meth}`tmuxp.config.validate_schema`. 559 560::: 561 562Add yours? Submit a pull request to the [github][github] site! 563 564[github]: https://github.com/tmux-python/tmuxp 565