Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Add dev server URL workflow to tips-patterns docs (#290)

Maximilian Roos10fead752e33
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index fbd1bf40f..ba7676f37 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -29,6 +29,37 @@ wsc new-feature # Creates worktree, runs hooks, launches Claude
See [Worktrunk's own `.config/wt.toml`](https://github.com/max-sixty/worktrunk/blob/main/.config/wt.toml) for a complete example.
+## Dev server per worktree
+
+Each worktree can run its own dev server on a deterministic port. The `hash_port` filter generates a stable port (10000-19999) from the branch name:
+
+```toml
+# .config/wt.toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }} &"
+
+[list]
+url = "http://localhost:{{ branch | hash_port }}"
+```
+
+`post-start` runs in background after worktree creation (like `post-create`, but non-blocking). The URL column in `wt list` shows each worktree's dev server:
+
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap — edit source to update -->
+
+{% terminal() %}
+<span class="prompt">$</span> <span class="cmd">wt list</span>
+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>URL</b> <b>Commit</b> <b>Age</b>
+@ main <span class=c>?</span> <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>http://localhost:12107</span> <span class=d>6088adb3</span> <span class=d>4d</span>
++ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>http://localhost:10703</span> <span class=d>ec97decc</span> <span class=d>30m</span>
++ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=d>|</span> <span class=d>http://localhost:16460</span> <span class=d>127407de</span> <span class=d>5h</span>
+
+<span class=d>○</span> <span class=d>Showing 3 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
+
+Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
+
## Local CI gate
`pre-merge` hooks run before merging. Failures abort the merge:
@@ -79,7 +110,7 @@ wt list --format=json
Structured output for dashboards, statuslines, and scripts. See [wt list](@/list.md) for query examples.
-## Side-effects of using Worktrunk
+## Reuse `default-branch`
Worktrunk maintains useful state. Default branch [detection](@/config.md#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index 41462beb1..5c7fa04d9 100644
--- a/tests/integration_tests/list.rs
+++ b/tests/integration_tests/list.rs
@@ -1745,6 +1745,33 @@ fn test_readme_example_list_branches(mut repo: TestRepo) {
);
}
+/// Generate tips-patterns.md example: dev server per worktree workflow
+///
+/// Uses the realistic README example repo and adds URL config.
+/// URLs appear dimmed (no servers running) - realistic for documentation.
+#[rstest]
+fn test_tips_dev_server_workflow(mut repo: TestRepo) {
+ // Set up the realistic README example repo
+ let _feature_api = setup_readme_example_repo(&mut repo);
+
+ // Add project config with URL template for dev servers
+ repo.write_project_config(
+ r#"[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }} &"
+
+[list]
+url = "http://localhost:{{ branch | hash_port }}"
+"#,
+ );
+
+ // Run from main worktree (URLs dim since no servers running)
+ run_snapshot(
+ setup_snapshot_settings(&repo),
+ "tips_dev_server_workflow",
+ list_snapshots::command_readme(&repo, repo.root_path()),
+ );
+}
+
#[rstest]
fn test_list_progressive_flag(mut repo: TestRepo) {
repo.add_worktree("feature-a");
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 780802a0e..c1e8b3dab 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1099,7 +1099,11 @@ fn test_docs_quickstart_examples_are_in_sync() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
// Process all docs files with AUTO-GENERATED-HTML markers
- let doc_files = ["docs/content/worktrunk.md", "docs/content/claude-code.md"];
+ let doc_files = [
+ "docs/content/worktrunk.md",
+ "docs/content/claude-code.md",
+ "docs/content/tips-patterns.md",
+ ];
let mut all_errors = Vec::new();
let mut total_updated = 0;
diff --git a/tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap b/tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap
new file mode 100644
index 000000000..f17a150b0
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap
@@ -0,0 +1,37 @@
+---
+source: tests/integration_tests/list.rs
+info:
+ program: wt
+ args:
+ - list
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "98"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SOURCE_DATE_EPOCH: "1735776000"
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+ Branch Status HEAD± main↕ Remote⇅ URL Commit Age
+@ main ? ^⇅ ⇡1 ⇣1 http://localhost:12107 6088adb3 4d
++ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ⇡3 http://localhost:10703 ec97decc 30m
++ fix-auth ↕| ↑2 ↓1 | http://localhost:16460 127407de 5h
+
+○ Showing 3 worktrees, 2 with changes, 2 ahead, 2 columns hidden
+
+----- stderr -----