Skip to content

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

docs: remove deprecated post-create from documentation (#1776)

Maximilian Roos5c1672932ff0
diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md
index 2ae9ad91b..7105d62ab 100644
--- a/.claude-plugin/README.md
+++ b/.claude-plugin/README.md
@@ -4,7 +4,7 @@ Git worktree management CLI integration with activity tracking.
## Features
-1. **Configuration skill** — Guides LLM-powered commit message setup, project hooks (post-create, pre-merge), and worktree path customization
+1. **Configuration skill** — Guides LLM-powered commit message setup, project hooks (pre-start, pre-merge), and worktree path customization
2. **Activity tracking** — Shows which branches have active Claude sessions via indicators in `wt list`
## Examples
@@ -19,6 +19,6 @@ These markers appear in `wt list` output, making it easy to see which worktrees
The configuration skill guides through configuring an AI tool (Claude Code, Codex, llm, or aichat) and adding `[commit.generation]` to the user config so `wt merge` can auto-generate commit messages.
-**Add post-create hooks to run npm install automatically**
+**Add pre-start hooks to run npm install automatically**
-The skill configures `.config/wt.toml` with project hooks. Post-create hooks run when creating worktrees, pre-merge hooks validate before merging.
+The skill configures `.config/wt.toml` with project hooks. Pre-start hooks run when creating worktrees, pre-merge hooks validate before merging.
diff --git a/.claude/skills/writing-user-outputs/SKILL.md b/.claude/skills/writing-user-outputs/SKILL.md
index 373bbaf70..fd8d143cd 100644
--- a/.claude/skills/writing-user-outputs/SKILL.md
+++ b/.claude/skills/writing-user-outputs/SKILL.md
@@ -187,7 +187,7 @@ Use the appropriate helper function:
2. **Post-hooks** — User will cd to destination if shell integration is active.
Use `output::post_hook_display_path(destination)`.
- Examples: post-create, post-switch, post-start, post-merge (after removal).
+ Examples: pre-start, post-switch, post-start, post-merge (after removal).
```rust
// Pre-hooks: user is at cwd, no cd happens
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index c505f2cc3..daa45ae73 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -10,10 +10,10 @@
# All hooks support two formats:
#
# Single command:
-# post-create = "npm install"
+# pre-start = "npm install"
#
# Named table (multiple commands):
-# [post-create]
+# [pre-start]
# deps = "npm install"
# build = "npm run build"
#
@@ -39,10 +39,10 @@
# Hooks
# ============================================================================
-# Post-Create: Runs after worktree creation, BLOCKS until complete
+# Pre-Start: Runs after worktree creation, BLOCKS until complete
# Use for: installing dependencies, setting up databases, copying configs
#
-# [post-create]
+# [pre-start]
# deps = "npm ci"
# env = "cp .env.example .env"
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index e328c69a4..7ebac2528 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -24,7 +24,7 @@ $ claude plugin install worktrunk@worktrunk
The plugin includes a skill — documentation that Claude Code can read — covering worktrunk's configuration system. After installation, Claude Code can help with:
- Setting up LLM-generated commit messages
-- Adding project hooks (post-create, pre-merge, pre-commit)
+- Adding project hooks (pre-start, pre-merge, pre-commit)
- Configuring worktree path templates
- Fixing shell integration issues
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 31ded8454..71367be16 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -28,7 +28,7 @@ Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored
copy = "wt step copy-ignored"
```
-Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.
+Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.
@@ -91,10 +91,10 @@ Jinja2's operator precedence has pipe `|` with higher precedence than concatenat
The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).
-Generate `.env.local` with the correct `DATABASE_URL` using a `post-create` hook:
+Generate `.env.local` with the correct `DATABASE_URL` using a `pre-start` hook:
```toml
-[post-create]
+[pre-start]
env = """
cat > .env.local << EOF
DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}
@@ -200,7 +200,7 @@ git rebase $(wt config state default-branch)
Reference Taskfile/Justfile/Makefile in hooks:
```toml
-[post-create]
+[pre-start]
"setup" = "task install"
[pre-merge]
@@ -258,7 +258,7 @@ Each worktree gets its own tmux session with a multi-pane layout. Sessions are n
```toml
# .config/wt.toml
-[post-create]
+[pre-start]
tmux = """
S={{ branch | sanitize }}
W={{ worktree_path }}
diff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.json
index c18365db2..e2295a3c0 100644
--- a/docs/static/.well-known/agent-skills/index.json
+++ b/docs/static/.well-known/agent-skills/index.json
@@ -6,7 +6,7 @@
"type": "skill-md",
"description": "Guidance for Worktrunk, a CLI tool for managing git worktrees. Covers configuration (user config at ~/.config/worktrunk/config.toml and project hooks at .config/wt.toml), usage, and troubleshooting. Use for \"setting up commit message generation\", \"configuring hooks\", \"automating tasks\", or general worktrunk questions.",
"url": "./worktrunk/SKILL.md",
- "digest": "sha256:cd06144c1319cd9bc139f436ee66c7de17b3bddbe7100b3b30666d7bea0e5a1a"
+ "digest": "sha256:c2c851a6f448b112709ae42d70271da7308a2b69c91f0a3ad4d134e97506ab5c"
}
]
}
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index 2402afe17..5d3f83679 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -38,7 +38,7 @@ Worktrunk uses two separate config files with different scopes and behaviors:
### Project Config (`.config/wt.toml`)
- **Scope**: Team-wide automation shared by all developers
- **Location**: `<repo>/.config/wt.toml` (checked into git)
-- **Contains**: Hooks for worktree lifecycle (post-create, pre-merge, etc.)
+- **Contains**: Hooks for worktree lifecycle (pre-start, pre-merge, etc.)
- **Permission model**: Proactive (create directly, changes are reversible via git)
- **See**: `reference/hook.md` for detailed guidance
@@ -106,7 +106,7 @@ Common request for workflow automation. Follow discovery process:
- For Python: Check pyproject.toml
3. **Design appropriate hooks** (7 hook types available)
- - Dependencies (fast, must complete) → `post-create`
+ - Dependencies (fast, must complete) → `pre-start`
- Tests/linting (must pass) → `pre-commit` or `pre-merge`
- Long builds, dev servers → `post-start`
- Terminal/IDE updates → `post-switch`
@@ -122,7 +122,7 @@ Common request for workflow automation. Follow discovery process:
5. **Create `.config/wt.toml`**
```toml
# Install dependencies when creating worktrees
- post-create = "npm install"
+ pre-start = "npm install"
# Validate code quality before committing
[pre-commit]
@@ -149,7 +149,7 @@ When users want to add automation to an existing project:
1. **Read existing config**: `cat .config/wt.toml`
2. **Determine hook type** - When should this run?
- - Creating worktree (blocking) → `post-create`
+ - Creating worktree (blocking) → `pre-start`
- Creating worktree (background) → `post-start`
- Every switch → `post-switch`
- Before committing → `pre-commit`
@@ -162,10 +162,10 @@ When users want to add automation to an existing project:
Single command to named table:
```toml
# Before
- post-create = "npm install"
+ pre-start = "npm install"
# After (adding db:migrate)
- [post-create]
+ [pre-start]
install = "npm install"
migrate = "npm run db:migrate"
```
@@ -242,7 +242,7 @@ Load **reference files** for detailed configuration, hook specifications, and tr
Find specific sections with grep:
```bash
grep -A 20 "## Setup" reference/llm-commits.md
-grep -A 30 "### post-create" reference/hook.md
+grep -A 30 "### pre-start" reference/hook.md
grep -A 20 "## Warning Messages" reference/shell-integration.md
```
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index fd3ab6562..fe8515c54 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -17,7 +17,7 @@ $ claude plugin install worktrunk@worktrunk
The plugin includes a skill — documentation that Claude Code can read — covering worktrunk's configuration system. After installation, Claude Code can help with:
- Setting up LLM-generated commit messages
-- Adding project hooks (post-create, pre-merge, pre-commit)
+- Adding project hooks (pre-start, pre-merge, pre-commit)
- Configuring worktree path templates
- Fixing shell integration issues
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 74368844f..f0152b043 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -21,7 +21,7 @@ Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) t
copy = "wt step copy-ignored"
```
-Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.
+Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.
@@ -80,10 +80,10 @@ Jinja2's operator precedence has pipe `|` with higher precedence than concatenat
The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).
-Generate `.env.local` with the correct `DATABASE_URL` using a `post-create` hook:
+Generate `.env.local` with the correct `DATABASE_URL` using a `pre-start` hook:
```toml
-[post-create]
+[pre-start]
env = """
cat > .env.local << EOF
DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}
@@ -189,7 +189,7 @@ git rebase $(wt config state default-branch)
Reference Taskfile/Justfile/Makefile in hooks:
```toml
-[post-create]
+[pre-start]
"setup" = "task install"
[pre-merge]
@@ -247,7 +247,7 @@ Each worktree gets its own tmux session with a multi-pane layout. Sessions are n
```toml
# .config/wt.toml
-[post-create]
+[pre-start]
tmux = """
S={{ branch | sanitize }}
W={{ worktree_path }}
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index 125fbbc6f..ea991a3c4 100644
--- a/skills/worktrunk/reference/troubleshooting.md
+++ b/skills/worktrunk/reference/troubleshooting.md
@@ -67,10 +67,10 @@ Move long-running commands to background:
```toml
# Before — blocks for minutes
-post-create = "npm run build"
+pre-start = "npm run build"
# After — fast setup, build in background
-post-create = "npm install"
+pre-start = "npm install"
post-start = "npm run build"
```
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 5f4da42f3..7621f61e5 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -10,7 +10,7 @@ pub enum HookCommand {
/// Lists user and project hooks. Project hooks show approval status (❓ = needs approval).
Show {
/// Hook type to show (default: all)
- #[arg(value_parser = ["pre-switch", "post-switch", "pre-start", "post-create", "post-start", "pre-commit", "post-commit", "pre-merge", "post-merge", "pre-remove", "post-remove"])]
+ #[arg(value_parser = ["pre-switch", "post-switch", "pre-start", "post-start", "pre-commit", "post-commit", "pre-merge", "post-merge", "pre-remove", "post-remove"])]
hook_type: Option<String>,
/// Show expanded commands with current variables
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
index b76835795..61054d936 100644
--- a/tests/CLAUDE.md
+++ b/tests/CLAUDE.md
@@ -218,7 +218,7 @@ assert_snapshot!("readme_example_name", combined_output);
**README examples using standard snapshots (working, but require manual editing):**
- `test_readme_example_simple()` - Quick start merge example
- `test_readme_example_complex()` - LLM commit example
-- `test_readme_example_hooks_post_create()` - Post-create hooks
+- `test_readme_example_hooks_pre_start()` - Pre-start hooks
- `test_readme_example_hooks_pre_merge()` - Pre-merge hooks
**Current workflow:** These tests work correctly and generate accurate snapshots. However, the snapshots separate stdout and stderr into different sections, which means they cannot be directly copied into README.md. Instead, the README examples are manually edited versions that merge stdout/stderr in the correct temporal order and remove ANSI codes.
diff --git a/tests/integration_tests/merge.rs b/tests/integration_tests/merge.rs
index 5e86756a5..210c747a2 100644
--- a/tests/integration_tests/merge.rs
+++ b/tests/integration_tests/merge.rs
@@ -1182,7 +1182,7 @@ command = "{llm_path_str}"
);
}
-// NOTE: test_readme_example_hooks_post_create and test_readme_example_hooks_pre_merge
+// NOTE: test_readme_example_hooks_pre_start and test_readme_example_hooks_pre_merge
// were removed - they're covered by PTY-based tests in shell_wrapper.rs that capture
// combined stdout/stderr for README examples.
diff --git a/tests/integration_tests/shell_wrapper.rs b/tests/integration_tests/shell_wrapper.rs
index ead9cb05e..405a6e283 100644
--- a/tests/integration_tests/shell_wrapper.rs
+++ b/tests/integration_tests/shell_wrapper.rs
@@ -2628,9 +2628,9 @@ command = "{}"
///
/// Uses shell wrapper to avoid "To enable automatic cd" hint.
///
- /// Source: tests/snapshots/shell_wrapper__tests__readme_example_hooks_post_create.snap
+ /// Source: tests/snapshots/shell_wrapper__tests__readme_example_hooks_pre_start.snap
#[rstest]
- fn test_readme_example_hooks_post_create(repo: TestRepo) {
+ fn test_readme_example_hooks_pre_start(repo: TestRepo) {
// Create project config with pre-start and post-start hooks
let config_dir = repo.root_path().join(".config");
fs::create_dir_all(&config_dir).unwrap();
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 9855849ce..05bed92d3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -322,10 +322,10 @@ With --project, creates .config/wt.toml in the current repositor
  # All hooks support two formats:
  #
  # Single command:
-  # post-create = "npm install"
+  # pre-start = "npm install"
  #
  # Named table (multiple commands):
-  # [post-create]
+  # [pre-start]
  # deps = "npm install"
  # build = "npm run build"
  #
@@ -351,10 +351,10 @@ With --project, creates .config/wt.toml in the current repositor
  # Hooks
  # ============================================================================
  
-  # Post-Create: Runs after worktree creation, BLOCKS until complete
+  # Pre-Start: Runs after worktree creation, BLOCKS until complete
  # Use for: installing dependencies, setting up databases, copying configs
  #
-  # [post-create]
+  # [pre-start]
  # deps = "npm ci"
  # env = "cp .env.example .env"
  
diff --git a/tests/snapshots/integration__integration_tests__shell_wrapper__unix_tests__readme_example_hooks_post_create.snap b/tests/snapshots/integration__integration_tests__shell_wrapper__unix_tests__readme_example_hooks_pre_start.snap
similarity index 100%
rename from tests/snapshots/integration__integration_tests__shell_wrapper__unix_tests__readme_example_hooks_post_create.snap
rename to tests/snapshots/integration__integration_tests__shell_wrapper__unix_tests__readme_example_hooks_pre_start.snap