Repository navigation
revert(hooks): keep docs on pre-start/post-start; code accepts both - #2857
Conversation
Reverts the docs portion of #2840 (pre-start/post-start → pre-create/post-create rename, Phase 1) while keeping the code change so both names continue to work. Per #2838 discussion, docs continue to recommend the original names until users have updated to a version that accepts both — preventing the experience reported in the issue where docs advised post-create on a version that still rejects it. What stays user-visible as pre-start/post-start: - README, docs site, skill mirrors, dev/*.example.toml, plugins/, flake.nix - src/cli/mod.rs / src/cli/config.rs / src/cli/step.rs / src/help.rs and the generated command-page mirrors - wt hook --help canonical subcommand names; completion advertises -start only - Strum / serde / clap-ValueEnum canonical Display for HookType is `*-start`; the Rust variant names `PreCreate`/`PostCreate` stay (internal-only, paid for in the original rename; the eventual flip becomes a Display-only change) - HooksConfig serde field rename canonical is `pre-start`/`post-start` What still works from `*-create` (kept code): - `wt hook pre-create` / `post-create` (CLI alias on the canonical subcommand) - `pre-create` / `post-create` in config (top-level, [hooks.*], and per-project in string, table, and array-of-tables form) via serde `alias = ...` on the field, plus a silent in-memory rename in `migrate_content()` so the unknown- key round-trip in `unknown_tree` doesn't flag table forms as schema-unknown. - The pre-0.32.0 `post-create` fatal-load-error machinery stays removed — the name is reclaimed and both forms load. Notes: - `valid_user_config_keys()` / `valid_project_config_keys()` append the two aliases so the unknown-field warning skips them. `test_valid_*_keys_all_ deserialize` skips both aliases (can't sit alongside the canonical without a duplicate-field error). - `DEPRECATED_SECTION_KEYS` drops the `pre-start`/`post-start` entries that the original PR added; deprecation warnings stay silent for hook renames (this was already the policy — Phase 2 was months out). - The `find_pre_start_from_doc` / `migrate_start_hooks_doc` / `snapshot_ migrate_start_to_create` helpers and tests are removed; the migration direction flips via the new `migrate_create_hooks_doc`. Re #2838 thread; closes the immediate confusion reported by @EcksDy. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
worktrunk-bot
left a comment
There was a problem hiding this comment.
Self-review on a bot PR — read it sceptically.
The mechanical pre-create/post-create → pre-start/post-start text replacement broke several alias-direction tests. After this revert the canonical name is pre-start and the alias is pre-create, but multiple tests still write [pre-start]/[post-start] in the fixture TOML and only assert against pre-start/post-start on the CLI — so they exercise neither the load-time migration nor the value-parser alias. Two of them have inline fixes below; the rest need broader rework (doc comment, function name, fixture TOML) and I'd rather leave that to the author than commit something half-converted.
Tests that need follow-up beyond the inline suggestions:
tests/integration_tests/config_show.rs:365-413— the doc comment ("uses the deprecatedpre-start/post-starthook keys keeps working… migrates the keys topre-start/post-start"), the function nametest_hook_show_accepts_deprecated_start_hooks, the inline comment about-createarg /-startarg (lines 384-386), and the[pre-start]/[post-start]fixture all describe the old direction. To exercise the new alias the fixture should use[pre-create]/[post-create]and the cases array should test both names on the CLI side (the inline suggestion below covers the cases-array half).tests/integration_tests/post_start_commands.rs:63-103—test_deprecated_start_hook_key_runs_silentlywritespre-start = "…"(canonical), comments say "deprecatedpre-starthook key… silently migrated topre-start", assertion message says "deprecated pre-start hook should have run". No alias is exercised. If the intent is still to cover the alias direction, fixture should bepre-create = "…".tests/integration_tests/user_hooks.rs:1594-1621—test_standalone_hook_start_alias_runs_silentlydoc-comments itself as "wt hook pre-startis a deprecated alias forwt hook pre-start" (self-referential), config writespre-start, CLI invokeswt hook pre-start. To test the new alias direction this should writepre-create(config) or invokewt hook pre-create(CLI).
Other follow-ups:
src/commands/hook_commands.rs:385— comment says "canonical name or deprecated-startalias"; the alias is now-create.src/config/deprecation.rs:1572-1573(outside this diff, but the reason the line is wrong is this revert) — "Some deprecations migrate silently (e.g. the-start→-createhook rename)"; direction is now reversed.- The five unit tests for
migrate_start_hooks_docinsrc/config/deprecation.rs(test_find_start_hook_deprecation_*,test_migrate_start_hooks_skips_when_create_exists,snapshot_migrate_start_to_create) were removed but no equivalents added formigrate_create_hooks_doc. The new direction's edge cases (skip when canonical already exists,[projects."…"]table form, array-of-tables) now have no unit coverage — only the integration suite would catch a regression. src/config/deprecation.rs:479-481—Deprecations::pre_start/post_startare kept aspubfields that are alwaysfalse. Per CLAUDE.md's "Don't suppress warnings" rule that's either a delete-and-re-add when the flip happens, or a// TODO(#2838): reused when the direction flipscomment so the intent isn't lost in the "always false" docstring.
Not a blocker: I can't approve a self-authored PR; flagging so a maintainer can decide whether to land as-is or want the test follow-up first.
| ("pre-start", "pre-start-tool"), | ||
| ("post-start", "post-start-tool"), |
There was a problem hiding this comment.
These two new entries duplicate the lines above and below, so the cases array exercises only pre-start/post-start (the canonical names) — never the pre-create/post-create alias the PR is adding. Replace them so the second case in each pair tests the alias path:
| ("pre-start", "pre-start-tool"), | |
| ("post-start", "post-start-tool"), | |
| ("pre-create", "pre-start-tool"), | |
| ("post-create", "post-start-tool"), |
This half-fixes the test; the surrounding doc comment, function name, inline comment (lines 384-386), and fixture TOML (lines 376-381) still describe the pre-revert direction and need updating too — see the review body for the full list.
| assert!( | ||
| stdout.contains("npm install"), | ||
| "post-start in system config should migrate to post-create and stay active, got: {stdout}" | ||
| "post-start in system config should migrate to post-start and stay active, got: {stdout}" |
There was a problem hiding this comment.
After the revert post-start is canonical, so this is self-referential — there's no migration to assert. The assertion is just "the configured hook loads and stays active":
| "post-start in system config should migrate to post-start and stay active, got: {stdout}" | |
| "post-start in system config should load and stay active, got: {stdout}" |
(If the goal is still to exercise the post-create alias here, the fixture on line 655 needs to be post-create = "npm install" and this message should reflect that — the surrounding context already tests [select] deprecation handling, which is the main point of the test.)
Follow-up to #2857. That PR reverted the docs half of the `pre-start`/`post-start` → `pre-create`/`post-create` hook rename while keeping the code that accepts both names. Its self-review landed 26 seconds after the merge, so none of its findings were addressed — several tests still described the pre-revert direction and exercised only canonical names, so they would pass even if the deprecated alias broke. ## Changes The three deprecated-alias tests now use `pre-create`/`post-create` in their fixtures (or invoke `wt hook pre-create`), so they exercise the migration and the CLI alias rather than canonical names: `test_hook_show_accepts_deprecated_create_hooks`, `test_deprecated_create_hook_key_runs_silently`, `test_standalone_hook_create_alias_runs_silently`. `test_parse_hook_type_aliases` had the same defect — it parsed only the canonical names — and now parses both forms and asserts they map to the same `HookType`. Added unit tests for `migrate_create_hooks_doc` (every value shape, per-project tables, skip-when-canonical-exists, invalid TOML) plus a migration-diff snapshot; the revert removed the `migrate_start_hooks_doc` tests with no equivalent. Deleted `Deprecations::pre_start`/`post_start` — always-false dead fields once the revert removed their detection. Deleted `test_config_show_displays_start_hook_migration`: post-revert there is no detection for `pre-create`, so `wt config show` shows no migration diff and the test verified nothing (its regenerated snapshot confirmed this). Also corrected reversed-direction comments in `deprecation.rs` and `hook_commands.rs`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two small follow-ups noticed while fixing the test comments in #2877. **`pre_create` docstring was wrong.** It read "Commands to execute before worktree creation (blocking)", but `pre-start` actually runs *after* the worktree is created (`switch.rs:1142` executes it against "the new worktree (created just above)", and the renamed test below asserts the worktree exists after a failing pre-start). The wrong wording entered in #2840 as part of the mechanical `pre-start` → `pre-create` rename — someone "corrected" the docstring to match the new name. #2857 reverted the name but left the docstring. Restoring "after worktree creation (blocking, fail-fast)" matches the actual behavior, `docs/content/hook.md` ("Runs once when a new worktree is created, blocking…"), and the parallel `post_create` docstring. Because `HooksConfig` derives `JsonSchema`, this docstring is user-visible in generated schema descriptions. **`test_user_post_start_hook_failure` was misnamed.** The fixture is `[pre-start]`, the comment and assertion describe a failing pre-start, and only the function name said post-start. Renamed to `test_user_pre_start_hook_failure` along with its snapshot name and file (`git mv`, so the rename shows as a rename). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…2857) Per @max-sixty's [direction in #2838](#2838 (comment)): revert the docs portion of #2840 and keep the code. Docs continue to recommend `pre-start`/`post-start`; both names work in code so anyone who already followed the briefly-changed docs (e.g. @EcksDy) isn't stranded once a release ships these aliases. ## User-visible — back to `pre-start`/`post-start` - README, docs site, skill mirrors, `dev/*.example.toml`, `plugins/worktrunk/README.md`, `flake.nix`, `.config/wt.toml` - `src/cli/mod.rs` / `src/cli/config.rs` / `src/cli/step.rs` / `src/help.rs` after_long_help and example snippets — and the auto-synced `docs/content/` and `skills/worktrunk/reference/` mirrors - `wt hook --help` canonical subcommand names; completion advertises `-start` only - `HookType` Display via strum, serde `rename`, and clap `ValueEnum` name — all `pre-start`/`post-start`. The Rust variant identifiers stay `PreCreate`/`PostCreate` (internal; we already paid for that rename in #2840, and now the eventual flip is a Display-only change) - `HooksConfig` serde canonical fields ## `*-create` still works (kept code) - `wt hook pre-create` / `post-create` — CLI alias on the canonical subcommand - `pre-create` / `post-create` in config: top-level, `[hooks.*]`, and per-project, in string, `[table]`, and `[[array-of-tables]]` form. Mechanism: serde `alias = ...` on the field, plus a silent in-memory rename in `migrate_content()` so the round-trip in `unknown_tree` doesn't flag table forms as schema-unknown. - The pre-0.32.0 `post-create` fatal-load-error machinery stays removed — the name is reclaimed, and both forms load without error. ## Smaller bits - `valid_user_config_keys()` / `valid_project_config_keys()` append `pre-create` / `post-create` so the unknown-field round-trip skips them. `test_valid_*_keys_all_deserialize` skips both aliases (they can't sit alongside the canonical without a duplicate-field error). - `DEPRECATED_SECTION_KEYS` drops the `pre-start`/`post-start` entries #2840 added — `pre-start`/`post-start` are canonical again. - `find_pre_start_from_doc` / `find_post_start_from_doc` / `find_renamed_hook_key` / `is_non_empty_item` / `migrate_start_hooks_doc` and their tests are removed; the migration direction flips via a new `migrate_create_hooks_doc` (silent, mirrors the prior shape). - Test files `e2e_shell_post_create.rs` and `post_create_commands.rs` rename back to `_post_start_` (via `git mv`, so the rename shows as a rename). ## Testing `cargo run -- hook pre-merge --yes` — 3806 tests pass; the 10 failures are all `case_4` of `shell_wrapper::unix_tests::*` (nu-shell case; `nu` isn't installed in this runner; same failures occur on `main`). Also manually verified that a fresh `wt switch --create` against a project config with `[post-create]` loads cleanly with no unknown-field warning and the hook fires as `post-start`. ## Follow-up Per @max-sixty: in a couple of weeks, once a release with both-names-work is out and users have had a chance to upgrade, the docs flip is straightforward (most of it is in `src/cli/mod.rs`'s `after_long_help` and the doc-sync test propagates). Re #2838. Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Follow-up to #2857. That PR reverted the docs half of the `pre-start`/`post-start` → `pre-create`/`post-create` hook rename while keeping the code that accepts both names. Its self-review landed 26 seconds after the merge, so none of its findings were addressed — several tests still described the pre-revert direction and exercised only canonical names, so they would pass even if the deprecated alias broke. ## Changes The three deprecated-alias tests now use `pre-create`/`post-create` in their fixtures (or invoke `wt hook pre-create`), so they exercise the migration and the CLI alias rather than canonical names: `test_hook_show_accepts_deprecated_create_hooks`, `test_deprecated_create_hook_key_runs_silently`, `test_standalone_hook_create_alias_runs_silently`. `test_parse_hook_type_aliases` had the same defect — it parsed only the canonical names — and now parses both forms and asserts they map to the same `HookType`. Added unit tests for `migrate_create_hooks_doc` (every value shape, per-project tables, skip-when-canonical-exists, invalid TOML) plus a migration-diff snapshot; the revert removed the `migrate_start_hooks_doc` tests with no equivalent. Deleted `Deprecations::pre_start`/`post_start` — always-false dead fields once the revert removed their detection. Deleted `test_config_show_displays_start_hook_migration`: post-revert there is no detection for `pre-create`, so `wt config show` shows no migration diff and the test verified nothing (its regenerated snapshot confirmed this). Also corrected reversed-direction comments in `deprecation.rs` and `hook_commands.rs`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two small follow-ups noticed while fixing the test comments in #2877. **`pre_create` docstring was wrong.** It read "Commands to execute before worktree creation (blocking)", but `pre-start` actually runs *after* the worktree is created (`switch.rs:1142` executes it against "the new worktree (created just above)", and the renamed test below asserts the worktree exists after a failing pre-start). The wrong wording entered in #2840 as part of the mechanical `pre-start` → `pre-create` rename — someone "corrected" the docstring to match the new name. #2857 reverted the name but left the docstring. Restoring "after worktree creation (blocking, fail-fast)" matches the actual behavior, `docs/content/hook.md` ("Runs once when a new worktree is created, blocking…"), and the parallel `post_create` docstring. Because `HooksConfig` derives `JsonSchema`, this docstring is user-visible in generated schema descriptions. **`test_user_post_start_hook_failure` was misnamed.** The fixture is `[pre-start]`, the comment and assertion describe a failing pre-start, and only the function name said post-start. Renamed to `test_user_pre_start_hook_failure` along with its snapshot name and file (`git mv`, so the rename shows as a rename). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per @max-sixty's direction in #2838: revert the docs portion of #2840 and keep the code. Docs continue to recommend
pre-start/post-start; both names work in code so anyone who already followed the briefly-changed docs (e.g. @EcksDy) isn't stranded once a release ships these aliases.User-visible — back to
pre-start/post-startdev/*.example.toml,plugins/worktrunk/README.md,flake.nix,.config/wt.tomlsrc/cli/mod.rs/src/cli/config.rs/src/cli/step.rs/src/help.rsafter_long_help and example snippets — and the auto-synceddocs/content/andskills/worktrunk/reference/mirrorswt hook --helpcanonical subcommand names; completion advertises-startonlyHookTypeDisplay via strum, serderename, and clapValueEnumname — allpre-start/post-start. The Rust variant identifiers stayPreCreate/PostCreate(internal; we already paid for that rename in feat(hooks): rename worktree-creation hooks to pre-create/post-create #2840, and now the eventual flip is a Display-only change)HooksConfigserde canonical fields*-createstill works (kept code)wt hook pre-create/post-create— CLI alias on the canonical subcommandpre-create/post-createin config: top-level,[hooks.*], and per-project, in string,[table], and[[array-of-tables]]form. Mechanism: serdealias = ...on the field, plus a silent in-memory rename inmigrate_content()so the round-trip inunknown_treedoesn't flag table forms as schema-unknown.post-createfatal-load-error machinery stays removed — the name is reclaimed, and both forms load without error.Smaller bits
valid_user_config_keys()/valid_project_config_keys()appendpre-create/post-createso the unknown-field round-trip skips them.test_valid_*_keys_all_deserializeskips both aliases (they can't sit alongside the canonical without a duplicate-field error).DEPRECATED_SECTION_KEYSdrops thepre-start/post-startentries feat(hooks): rename worktree-creation hooks to pre-create/post-create #2840 added —pre-start/post-startare canonical again.find_pre_start_from_doc/find_post_start_from_doc/find_renamed_hook_key/is_non_empty_item/migrate_start_hooks_docand their tests are removed; the migration direction flips via a newmigrate_create_hooks_doc(silent, mirrors the prior shape).e2e_shell_post_create.rsandpost_create_commands.rsrename back to_post_start_(viagit mv, so the rename shows as a rename).Testing
cargo run -- hook pre-merge --yes— 3806 tests pass; the 10 failures are allcase_4ofshell_wrapper::unix_tests::*(nu-shell case;nuisn't installed in this runner; same failures occur onmain).Also manually verified that a fresh
wt switch --createagainst a project config with[post-create]loads cleanly with no unknown-field warning and the hook fires aspost-start.Follow-up
Per @max-sixty: in a couple of weeks, once a release with both-names-work is out and users have had a chance to upgrade, the docs flip is straightforward (most of it is in
src/cli/mod.rs'safter_long_helpand the doc-sync test propagates).Re #2838.