Skip to content

Commit 0ab75ae

Browse files
tonytony
committed
docs(config[top-level]): Document new config keys and lifecycle hooks
why: New configuration keys need user-facing documentation. what: - Document lifecycle hooks (on_project_start/restart/exit/stop) - Document pane titles (enable_pane_titles, title) - Document config templating, synchronize, shell_command_after, clear
1 parent 2428c85 commit 0ab75ae

1 file changed

Lines changed: 148 additions & 0 deletions

File tree

‎docs/configuration/top-level.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,151 @@ Notes:
4040
```
4141

4242
Above: Use `tmux` directly to attach _banana_.
43+
44+
## Lifecycle hooks
45+
46+
Workspace configs support four lifecycle hooks that run shell commands at different stages of the session lifecycle:
47+
48+
```yaml
49+
session_name: myproject
50+
on_project_start: notify-send "Starting myproject"
51+
on_project_restart: notify-send "Reattaching to myproject"
52+
on_project_exit: notify-send "Detached from myproject"
53+
on_project_stop: notify-send "Stopping myproject"
54+
windows:
55+
- window_name: main
56+
panes:
57+
-
58+
```
59+
60+
| Hook | When it runs |
61+
|------|-------------|
62+
| `on_project_start` | Before session build, every `tmuxp load` invocation |
63+
| `on_project_restart` | When reattaching to an existing session |
64+
| `on_project_exit` | On client detach (tmux `client-detached` hook) |
65+
| `on_project_stop` | Before `tmuxp stop` kills the session |
66+
67+
Each hook accepts a string (single command) or a list of strings (multiple commands run sequentially).
68+
69+
```yaml
70+
on_project_start:
71+
- notify-send "Starting"
72+
- ./setup.sh
73+
```
74+
75+
```{note}
76+
These hooks correspond to tmuxinator's `on_project_start`, `on_project_restart`, `on_project_exit`, and `on_project_stop` keys.
77+
```
78+
79+
## Pane titles
80+
81+
Enable pane border titles to display labels on each pane:
82+
83+
```yaml
84+
session_name: myproject
85+
enable_pane_titles: true
86+
pane_title_position: top
87+
pane_title_format: "#{pane_index}: #{pane_title}"
88+
windows:
89+
- window_name: dev
90+
panes:
91+
- title: editor
92+
shell_command:
93+
- vim
94+
- title: tests
95+
shell_command:
96+
- uv run pytest --watch
97+
- shell_command:
98+
- git status
99+
```
100+
101+
| Key | Level | Description |
102+
|-----|-------|-------------|
103+
| `enable_pane_titles` | session | Enable pane border titles (`true`/`false`) |
104+
| `pane_title_position` | session | Position of the title bar (`top`/`bottom`) |
105+
| `pane_title_format` | session | Format string using tmux variables |
106+
| `title` | pane | Title text for an individual pane |
107+
108+
```{note}
109+
These correspond to tmuxinator's `enable_pane_titles`, `pane_title_position`, `pane_title_format`, and named pane (hash-key) syntax.
110+
```
111+
112+
## Config templating
113+
114+
Workspace configs support `{{ variable }}` placeholders that are rendered before YAML/JSON parsing. Pass values via `--set KEY=VALUE` on the command line:
115+
116+
```yaml
117+
session_name: "{{ project }}"
118+
start_directory: "~/code/{{ project }}"
119+
windows:
120+
- window_name: main
121+
panes:
122+
- echo "Working on {{ project }}"
123+
```
124+
125+
```console
126+
$ tmuxp load --set project=myapp mytemplate.yaml
127+
```
128+
129+
```{note}
130+
Values containing `{{ }}` must be quoted in YAML to prevent parse errors.
131+
```
132+
133+
See {ref}`cli-load` for full CLI usage.
134+
135+
## synchronize
136+
137+
Window-level shorthand for setting `synchronize-panes`. Accepts `before`, `after`, or `true`:
138+
139+
```yaml
140+
session_name: sync-demo
141+
windows:
142+
- window_name: synced
143+
synchronize: after
144+
panes:
145+
- echo pane0
146+
- echo pane1
147+
- window_name: not-synced
148+
panes:
149+
- echo pane0
150+
- echo pane1
151+
```
152+
153+
| Value | Behavior |
154+
|-------|----------|
155+
| `before` | Enable synchronize-panes before sending pane commands |
156+
| `after` | Enable synchronize-panes after sending pane commands |
157+
| `true` | Same as `before` |
158+
159+
```{note}
160+
This corresponds to tmuxinator's `synchronize` window key. The `before` and `true` values are accepted for compatibility but `after` is recommended.
161+
```
162+
163+
## shell_command_after
164+
165+
Window-level key. Commands are sent to every pane in the window after all panes have been created and their individual commands executed:
166+
167+
```yaml
168+
session_name: myproject
169+
windows:
170+
- window_name: servers
171+
shell_command_after:
172+
- echo "All panes ready"
173+
panes:
174+
- ./start-api.sh
175+
- ./start-worker.sh
176+
```
177+
178+
## clear
179+
180+
Window-level boolean. When `true`, sends `clear` to every pane after all commands (including `shell_command_after`) have completed:
181+
182+
```yaml
183+
session_name: myproject
184+
windows:
185+
- window_name: dev
186+
clear: true
187+
panes:
188+
- cd src
189+
- cd tests
190+
```

0 commit comments

Comments
 (0)