docs(feat[parity]): Recut tmuxinator and teamocil parity docs · tmux-python/tmuxp@dfaac96 · GitHub
Skip to content

Commit dfaac96

Browse files
tonytony
committed
docs(feat[parity]): Recut tmuxinator and teamocil parity docs
why: Document the public parity surface and release notes in one reviewable docs commit. what: - Add comparison, CLI, configuration, and example docs for parity features - Add API pages for new CLI modules and tested examples - Add changelog coverage for the parity release
1 parent 87a945c commit dfaac96

25 files changed

Lines changed: 890 additions & 0 deletions

‎.gitignore‎

Lines changed: 4 additions & 0 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,7 @@ Pass structured data on every log call where useful for filtering, searching, or
201201
| `tmux_pane` | `str` | pane identifier |
202202
| `tmux_config_path` | `str` | workspace config file path |
203203
| `tmux_layout` | `str` | window layout string |
204+
| `tmux_hook_cmd` | `str` | lifecycle hook shell command line |
204205

205206
**Heavy/optional keys** (DEBUG only, potentially large):
206207

‎CHANGES‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,83 @@ $ tmuxp@next load yoursession
4444
_Notes on the upcoming release will go here._
4545
<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
4646

47+
tmuxp 1.71.0 brings tmuxp to feature parity with tmuxinator and
48+
teamocil. Sessions can be managed end to end from the CLI (`stop`,
49+
`new`, `copy`, `delete`), workspace configs gain lifecycle hooks,
50+
`{{ variable }}` templating, and pane titles, and `tmuxp load` learns
51+
`--here` and friends. Imports from tmuxinator and teamocil now convert
52+
much more of an existing config. See {doc}`comparison` for a
53+
side-by-side of all three tools.
54+
55+
### What's new
56+
57+
#### `tmuxp stop` — kill a session with cleanup (#1025)
58+
59+
Stop a running session by name. The `on_project_stop` lifecycle hook
60+
runs before the session is killed, giving your project a chance to
61+
clean up. See {ref}`cli-stop`.
62+
63+
```console
64+
$ tmuxp stop mysession
65+
```
66+
67+
#### `tmuxp new`, `tmuxp copy`, `tmuxp delete` — manage workspace configs (#1025)
68+
69+
Create a workspace config from a starter template and open it in
70+
`$EDITOR`, duplicate an existing config under a new name, or delete
71+
configs (with a confirmation prompt unless `-y` is passed).
72+
73+
```console
74+
$ tmuxp new myproject
75+
```
76+
77+
#### Lifecycle hooks (#1025)
78+
79+
Workspace configs support four hooks, modeled on tmuxinator's:
80+
81+
- `on_project_start` — before a new session is built
82+
- `on_project_restart` — after you confirm reattaching to an existing session
83+
- `on_project_exit` — when the last client detaches
84+
- `on_project_stop` — before `tmuxp stop` kills the session
85+
86+
See {ref}`top-level` for examples.
87+
88+
#### Config templating with `--set` (#1025)
89+
90+
Workspace configs may contain `{{ variable }}` placeholders, filled at
91+
load time:
92+
93+
```console
94+
$ tmuxp load --set project=myapp mytemplate.yaml
95+
```
96+
97+
#### Pane titles (#1025)
98+
99+
Session-level `enable_pane_titles`, `pane_title_position`, and
100+
`pane_title_format` keys turn on tmux pane border titles; a pane-level
101+
`title` key names individual panes.
102+
103+
#### New window keys: `synchronize`, `shell_command_after`, `clear` (#1025)
104+
105+
`synchronize: before/after/true` mirrors keystrokes across a window's
106+
panes; `shell_command_after` runs commands in every pane after the
107+
window is built; `clear: true` clears each pane once its commands
108+
complete.
109+
110+
#### New `tmuxp load` flags (#1025)
111+
112+
- `--here` — build the workspace in your current tmux window instead of a new session
113+
- `--no-shell-command-before` — skip all `shell_command_before` entries
114+
- `--debug` — show each tmux command as it executes
115+
- `--set KEY=VALUE` — fill config template variables
116+
117+
#### Broader tmuxinator and teamocil imports (#1025)
118+
119+
`tmuxp import` now converts lifecycle hooks, named panes, startup
120+
window/pane focus, synchronized windows, and tmux CLI arguments from
121+
tmuxinator configs, and recognizes teamocil's v1.x format. See
122+
{ref}`cli-import` for the full key mappings.
123+
47124
## tmuxp 1.70.0 (2026-05-23)
48125

49126
tmuxp 1.70.0 bumps libtmux to 0.58.0, fixing session and window listing on systems whose locale is not UTF-8.

‎docs/cli/copy.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
(cli-copy)=
2+
3+
(cli-copy-reference)=
4+
5+
# tmuxp copy
6+
7+
Copy an existing workspace config to a new name. Source is resolved using the same logic as `tmuxp load` (supports names, paths, and extensions).
8+
9+
## Command
10+
11+
```{eval-rst}
12+
.. argparse::
13+
:module: tmuxp.cli
14+
:func: create_parser
15+
:prog: tmuxp
16+
:path: copy
17+
```
18+
19+
## Basic usage
20+
21+
Copy a workspace:
22+
23+
```console
24+
$ tmuxp copy myproject myproject-backup
25+
```

‎docs/cli/delete.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
(cli-delete)=
2+
3+
(cli-delete-reference)=
4+
5+
# tmuxp delete
6+
7+
Delete one or more workspace config files. Prompts for confirmation unless `-y` is passed.
8+
9+
## Command
10+
11+
```{eval-rst}
12+
.. argparse::
13+
:module: tmuxp.cli
14+
:func: create_parser
15+
:prog: tmuxp
16+
:path: delete
17+
```
18+
19+
## Basic usage
20+
21+
Delete a workspace:
22+
23+
```console
24+
$ tmuxp delete old-project
25+
```
26+
27+
Delete without confirmation:
28+
29+
```console
30+
$ tmuxp delete -y old-project
31+
```
32+
33+
Delete multiple workspaces:
34+
35+
```console
36+
$ tmuxp delete proj1 proj2
37+
```
38+
39+
```{note}
40+
Only workspace files are deletable: the resolved path must end in `.yaml`, `.yml`, or `.json`. Any other file is refused and the command exits with code 1.
41+
```

‎docs/cli/import.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,14 @@ $ tmuxp import teamocil /path/to/file.json
3838
3939
````
4040

41+
### Supported teamocil features
42+
43+
The teamocil importer handles:
44+
45+
- **v1.x format** — `windows` at top level with `commands` key in panes
46+
- **Focus** — `focus: true` on windows and panes is preserved
47+
- **Window options** — `options` on windows are passed through
48+
4149
(import-tmuxinator)=
4250

4351
## From tmuxinator
@@ -71,3 +79,13 @@ $ tmuxp import tmuxinator /path/to/file.json
7179
```
7280
7381
````
82+
83+
### Supported tmuxinator features
84+
85+
The tmuxinator importer maps:
86+
87+
- **Hook mapping** — `pre` maps to `on_project_start`, `pre_window` maps to `shell_command_before`
88+
- **CLI args** — `cli_args` values (`-f`, `-S`, `-L`) are parsed into tmuxp config equivalents
89+
- **Synchronize** — `synchronize` window key is converted
90+
- **Startup focus** — `startup_window` / `startup_pane` convert to `focus: true`
91+
- **Named panes** — hash-key pane syntax converts to `title` on the pane

‎docs/cli/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ load
5353
shell
5454
ls
5555
search
56+
stop
5657
```
5758

5859
```{toctree}
@@ -63,6 +64,9 @@ edit
6364
import
6465
convert
6566
freeze
67+
new
68+
copy
69+
delete
6670
```
6771

6872
```{toctree}

‎docs/cli/load.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,3 +253,67 @@ When progress is disabled, logging flows normally to the terminal and no spinner
253253
### Before-script behavior
254254

255255
During `before_script` execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.
256+
257+
## Here mode
258+
259+
The `--here` flag reuses the current tmux window instead of creating a new session. This is similar to teamocil's `--here` flag.
260+
261+
```console
262+
$ tmuxp load --here .
263+
```
264+
265+
When used, tmuxp builds the workspace panes inside the current window rather than spawning a new session.
266+
267+
`--here` only supports a single workspace file per invocation.
268+
269+
```{note}
270+
When `--here` needs to provision a directory, environment, or shell, tmuxp uses tmux primitives instead of typing `cd` / `export` into the pane. The pane tmuxp itself runs in is never respawned (that would kill the build mid-flight): there the directory is provisioned with a quoted `cd`, environment variables land in the tmux session environment (inherited by the panes the build creates, not the already-running shell), and `window_shell` is skipped with a warning. Any other reused pane is provisioned with `respawn-pane`, which replaces the pane's process before the workspace commands run — long-running child processes in that pane will be terminated.
271+
```
272+
273+
## Skipping shell_command_before
274+
275+
The `--no-shell-command-before` flag skips all `shell_command_before` entries at every level (session, window, pane). This is useful for quick reloads when the setup commands (virtualenv activation, etc.) are already active.
276+
277+
```console
278+
$ tmuxp load --no-shell-command-before myproject
279+
```
280+
281+
```{note}
282+
This flag is intentionally broader than tmuxinator's `--no-pre-window`, which only disables the window-level `pre_window` chain. tmuxp's flag strips `shell_command_before` at all levels for a clean reload experience.
283+
```
284+
285+
## Debug mode
286+
287+
The `--debug` flag shows tmux commands as they execute. This disables the progress spinner and attaches a debug handler to libtmux's logger, printing each tmux command to stdout.
288+
289+
```console
290+
$ tmuxp load --debug myproject
291+
```
292+
293+
## Config templating
294+
295+
Workspace configs support simple `{{ variable }}` placeholders for variable substitution. Pass values via `--set KEY=VALUE`:
296+
297+
```console
298+
$ tmuxp load --set project=myapp mytemplate.yaml
299+
```
300+
301+
Multiple variables can be passed:
302+
303+
```console
304+
$ tmuxp load --set project=myapp --set env=staging mytemplate.yaml
305+
```
306+
307+
In the config file, use double-brace syntax:
308+
309+
```yaml
310+
session_name: "{{ project }}"
311+
windows:
312+
- window_name: "{{ project }}-main"
313+
panes:
314+
- echo "Working on {{ project }}"
315+
```
316+
317+
```{note}
318+
Values containing `{{ }}` must be quoted in YAML to avoid parse errors.
319+
```

‎docs/cli/new.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
(cli-new)=
2+
3+
(cli-new-reference)=
4+
5+
# tmuxp new
6+
7+
Create a new workspace configuration file from a minimal template and open it in `$EDITOR`. If the workspace already exists, it opens for editing.
8+
9+
## Command
10+
11+
```{eval-rst}
12+
.. argparse::
13+
:module: tmuxp.cli
14+
:func: create_parser
15+
:prog: tmuxp
16+
:path: new
17+
```
18+
19+
## Basic usage
20+
21+
Create a new workspace:
22+
23+
```console
24+
$ tmuxp new myproject
25+
```

‎docs/cli/stop.md‎

Lines changed: 37 additions & 0 deletions

0 commit comments

Comments
 (0)