Tracking: rename creation hooks pre-start/post-start → pre-create/post-create

Open
  • Is something wrong?
#2,838 6 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
git, rust
Domain
cli, devtools

Research direction

Start with the Phase 1 details in this issue and inspect the existing hook configuration, migration, and CLI parsing code; reuse the mechanical edits on the hooks/rename-start-to-create branch. Update the primary docs in src/cli/mod.rs, regenerate the docs/content/ and skills/worktrunk/reference/ mirrors, and run cargo test --test integration test_docs_are_in_sync. Done means the Phase 1 checklist is complete, including config migration coverage, examples and schema, and a changelog entry explaining the semantic flip.

Written by the indexing model from the issue text.

Description

Summary

Rename the worktree-creation hooks from pre-start/post-start to pre-create/post-create. post-start keeps confusing users ("start of what?", #1571). Hook names are protected interfaces (the wt.toml format and the wt hook CLI), so this ships as a staged deprecation rather than the breaking change already on the hooks/rename-start-to-create branch.

End state: -create canonical everywhere, -start accepted through a silent migration and then a warned one.

The semantic flip (main risk)

pre-create is a new name with no history. post-create is being reclaimed, and its meaning inverts: the old post-create was blocking (the pre-0.32.0 name for pre-start), the new one is background (an alias of post-start). A config still holding a stale post-create would flip from blocking to background silently. This is contained: post-create has been a fatal load error since 0.44.0, so by Phase 1 it will have been a hard error for roughly ten releases. The Phase 1 changelog states the flip plainly.

Plan

Releases land roughly weekly, so phases are paced in months.

  • Phase 1 (~June 2026): both names work, no warnings. -create becomes the canonical serde field; migrate_content() rewrites -start silently; docs and wt config update move to -create. The dead pre-0.32.0 post-create machinery is removed first.
  • Phase 2 (~September 2026): add deprecation warnings on config load and on wt hook pre-start/post-start, both pointing at wt config update.
  • Phase 3 (deferred): decide whether -start keeps migrating indefinitely, becomes a fatal error, or is removed.

Open decisions

  1. Bundle the post-create fatal-error removal into Phase 1 (default), or hold it one release longer.
  2. Cross-link #1571 now, and close it once its docs point lands in Phase 1.
  3. Phase 3 disposition.
History, current state, and Phase 1 implementation detail
History

This is the third naming move, and it partly reverses the second.

When Release Change
Before 0.32.0 Two creation hooks: post-create (blocking) and post-start (background).
0.32.0 #1679 Hooks reorganized into symmetric pre-/post- pairs. post-create renamed to pre-start, kept as a silently-migrated alias.
0.34.0 #1776 post-create removed from the docs.
2026-03-17 #1571 Issue filed: hook execution order is confusing and post-start is an unclear name.
0.44.0 #2361 post-create config key becomes a fatal load error. Clears the silent migration so the name can be reclaimed.
0.45.1 #2436 wt hook post-create CLI alias starts printing a deprecation warning.
0.52.0 (now) The actual rename never shipped. This issue resumes it.
Current state
  • Canonical: pre-start / post-start, across config keys, HookType, and wt hook subcommands.
  • post-create config key: fatal load error (POST_CREATE_REMOVED_MSG).
  • post-create CLI: wt hook post-create resolves to pre-start with a warning.
  • Dead machinery from the unfinished 0.32.0 cycle: HooksConfig::post_create and its folds, Deprecations::post_create, find_post_create_from_doc.
  • pre-create: never existed.
Phase 1 implementation

Prerequisite, same PR: remove the dead post-create machinery so the name is free.

Config:

  • pre-create/post-create become the canonical serde fields; rename HookType::PreStart/PostStart to PreCreate/PostCreate.
  • migrate_content() rewrites -start to -create, covering top-level keys, [hooks.*], [projects."id"] flattened and [projects."id".hooks], and the string, [table], and [[array-of-tables]] value forms.
  • wt config update and the startup warning both run off detect_deprecations(). Add the -start entry there so update finds it, but leave format_deprecation_warnings() silent until Phase 2.

CLI:

  • parse_hook_type and HOOK_TYPE_NAMES accept -create; -start stays accepted with no warning.

Docs:

  • Rewrite src/cli/mod.rs (the primary source), regenerate the docs/content/ and skills/worktrunk/reference/ mirrors, update README.md, the dev/*.example.toml files, and the JSON schema. Run cargo test --test integration test_docs_are_in_sync.
  • Per #1571, tighten the definition of when the hook fires.
  • The hooks/rename-start-to-create branch already has correct mechanical edits to reuse.
Checklist

Phase 1:

  • Remove dead post-create machinery
  • migrate_content() rewrite covering all config shapes
  • Canonical serde fields and HookType variants renamed
  • parse_hook_type / HOOK_TYPE_NAMES accept -create
  • Docs, examples, README, JSON schema updated
  • wt config update migrates -start with no startup warning
  • Changelog entry naming the semantic flip

Phase 2:

  • -start warning in format_deprecation_warnings()
  • CLI stderr warning for wt hook pre-start/post-start

Phase 3:

  • Decide keep, fatal, or remove

This was written by Claude Code on behalf of Maximilian Roos

Dominant language
Rust
Stars
8.8k
Forks
315
Avg merge
1d 6h
Merged PRs (30d)
204

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from max-sixty/worktrunk

All issues in max-sixty/worktrunk

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.