rails-worktrees 0.7.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eed6634afda26cca90bd9f6e2540a7ace8f865ec53f97a283fc873e137cffe8
-  data.tar.gz: 6a2541a2a026af4ed0ccd8e14f3d1ceac78e0da7c5e4d1fc01c1fb6d4b34e0ad
+  metadata.gz: 6f0667430464dedbea994c715a32e64f226048502f6037186f3c90692c5df6e5
+  data.tar.gz: 1f47027f6cdc16431356c43e4809d801a7537db1558d3ab9b25c1299874d1389
 SHA512:
-  metadata.gz: 0a8cf44f39ec11d98faa0d7e3b18badb5b1c4a8dcb3c31c67a0f26d4442656554cb5658275ccc96df69364d5a46572ab2408f57ea08deb31a0568bf284daf2da
-  data.tar.gz: 588ba219467bee9baa350d06d44a8eaf56fc1eab7e361bb1ff233cd7b9efa1e0e7041ad9f96d90d1bd059ae378789388caf0d4b7c2556cd29b6f7c28cfc63c07
+  metadata.gz: 81a835017246e1cab5fd6acf6ef311b4f9beef54912675602fd454c8ed2aa56904b514be908f69cdc2b84110ec8c38d9d49c9abbc974eea1b309aec2fed3c3f9
+  data.tar.gz: 5aad32825be11a64a0095233ed4068eda727da0af5ca0456657e5a4f0aa33f8aa04c0a6a48929a0e7abe97cbbbff9197aa49845c5b6a4acdf207d6c48e8e0796

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.7.4"}
+{".":"0.9.0"}

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.9.0](https://github.com/asjer/rails-worktrees/compare/v0.8.0...v0.9.0) (2026-11-02)
+
+
+### Features
+
+* **config:** support worktrees inside the repo via worktrees_dir ([#61](https://github.com/asjer/rails-worktrees/issues/61)) ([681f325](https://github.com/asjer/rails-worktrees/commit/681f325584b69fc675f7fce045c5cd8baf36eb83))
+* **setup:** install Playwright Chromium for the pinned version ([#66](https://github.com/asjer/rails-worktrees/issues/66)) ([cdbef7c](https://github.com/asjer/rails-worktrees/commit/cdbef7c24f738674dd209af35da25d4f85e038ed))
+* **wt:** add guarded worktree teardown with dry-run ([#63](https://github.com/asjer/rails-worktrees/issues/63)) ([5592830](https://github.com/asjer/rails-worktrees/commit/5592830849b098e0d904d70cf96390dc55083356))
+
+
+### Bug Fixes
+
+* **wt:** reserve help and version instead of using them as names ([#60](https://github.com/asjer/rails-worktrees/issues/60)) ([d52dba8](https://github.com/asjer/rails-worktrees/commit/d52dba83525ef21f11840db0b691174ccf896a33))
+
+## [0.8.0](https://github.com/asjer/rails-worktrees/compare/v0.7.4...v0.8.0) (2026-10-24)
+
+
+### Features
+
+* **pi:** add opt-in pi-worktree setup hook generation ([ccaa0ea](https://github.com/asjer/rails-worktrees/commit/ccaa0ead9fe31a01ac2c8016a51fd60b1611daef)), closes [#53](https://github.com/asjer/rails-worktrees/issues/53)
+
 ## [0.7.4](https://github.com/asjer/rails-worktrees/compare/v0.7.3...v0.7.4) (2026-08-15)
 
 

data/README.md

@@ -17,6 +17,8 @@ bin/rails generate worktrees:install
 bin/rails generate worktrees:install --browser
 # or, to apply the common Procfile.dev + Puma + mise follow-ups automatically:
 bin/rails generate worktrees:install --yolo
+# optionally, to let the pi-worktree extension run bin/wt setup in new Pi worktrees:
+bin/rails generate worktrees:install --pi
 ```
 
 The generated initializer writes app config under `Rails.application.config.x.rails_worktrees`, so the file stays safe to load even in environments like `test` where the gem is only bundled for `:development`. When `rails-worktrees` is loaded, the gem applies those settings for both the CLI and in-process Rails usage.
@@ -28,6 +30,7 @@ The installer adds:
 - `config/initializers/rails_worktrees.rb` — optional configuration
 - `Procfile.dev.worktree.example` — a copy-paste helper for `${DEV_PORT:-3000}` in `Procfile.dev` on regular installs
 - a safe update to `config/database.yml` for common development/test database names
+- `.pi/worktree.json` — only with `--pi`; see [Pi worktrees](#pi-worktrees-pi-worktree-extension)
 
 With `--yolo`, the installer also:
 
@@ -51,10 +54,15 @@ bin/wt setup ../my-project.worktrees/my-feature # setup a specific checkout with
 bin/wt doctor                   # audit install/config drift and basic worktree health
 bin/wt update --dry-run         # preview safe maintenance fixes
 bin/wt update                   # apply safe maintenance fixes for managed files
-bin/wt remove my-feature        # remove a worktree and delete its local branch
+bin/wt update --pi              # also add the pi-worktree hook in .pi/worktree.json
+bin/wt teardown --dry-run       # preview this worktree's Overmind and development/test databases
+bin/wt teardown                 # stop Overmind and drop worktree databases; keep checkout/branch
+bin/wt remove my-feature        # teardown a worktree, remove it and delete its local branch
 bin/wt delete my-feature        # alias for `bin/wt remove`
 bin/wt remove --force my-feature # also delete an unmerged local branch
 bin/wt prune                    # remove merged worktrees created by wt
+bin/wt help                     # same as --help; never creates a worktree
+bin/wt version                  # same as --version
 
 bin/ob                          # open http://localhost:$DEV_PORT/
 bin/ob contact                  # open http://localhost:$DEV_PORT/contact
@@ -66,12 +74,13 @@ bin/ob --print-url '?from=nav'  # print the resolved URL without opening a brows
 
 | Flag | Description |
 |------|-------------|
-| `-h`, `--help` | Show the help message |
-| `-v`, `--version` | Show the script version |
+| `-h`, `--help`, `help` | Show the help message |
+| `-v`, `--version`, `version` | Show the script version |
 | `--dry-run [name]` | Preview worktree creation or cleanup without changing anything |
 | `--skip-setup` | Create a worktree without running setup steps |
 | `--force` | Force branch deletion for `bin/wt remove` / `bin/wt delete` |
 | `--env`, `--print-env <name>` | Preview `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` |
+| `--pi` | With `bin/wt update`, create or merge `.pi/worktree.json` for the pi-worktree extension |
 
 ### Default behavior
 
@@ -83,7 +92,7 @@ By default `bin/wt`:
 - auto-picks names from bundled `.txt` files when no explicit name is given
 - retires bundled names so they are not picked twice
 - bootstraps a worktree-local `.env` with deterministic `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` values
-- runs setup automatically after creation: credential linking, `bundle install`, `yarn install` when applicable, both `db:prepare` steps, test asset precompile, and a final `bin/rails assets:clobber`
+- runs setup automatically after creation: credential linking, `bundle install`, `yarn install` when applicable, the Playwright Chromium build for the pinned `playwright` package when it is missing, both `db:prepare` steps, test asset precompile, and a final `bin/rails assets:clobber`
 
 ```text
 workspace/
@@ -96,6 +105,32 @@ workspace/
 
 `WT_WORKSPACES_ROOT` or `config.workspace_root` overrides the destination root and uses the layout `<root>/<project>/<name>`.
 
+### Worktrees inside the repository
+
+Set `config.worktrees_dir` to keep worktrees inside the main checkout instead, in `<main checkout>/<worktrees_dir>/<name>`. This is the layout the [pi-worktree](https://www.npmjs.com/package/pi-worktree) extension uses, so `bin/wt` and Pi share one place for worktrees:
+
+```ruby
+Rails.application.config.x.rails_worktrees.tap do |config|
+  config.worktrees_dir = '.worktrees'
+  config.branch_prefix = 'worktree' # wt and pi-worktree both create worktree/<name>
+end
+```
+
+```text
+my-project/
+├── app/
+├── config/
+└── .worktrees/
+    ├── feature-auth/
+    └── bugfix-123/
+```
+
+- `worktrees_dir` must be a relative path inside the repository, such as `.worktrees` or `tmp/worktrees`. It always resolves against the main checkout, also when you run `bin/wt` from inside a worktree.
+- If `.gitignore` does not already ignore the directory, `bin/wt` adds `/.worktrees/` to `.git/info/exclude` when it creates a worktree, so `git status` in the main checkout stays clean. When it cannot write that file it prints a warning; add the directory to `.gitignore` yourself.
+- `bin/wt remove`, `bin/wt prune` and `bin/wt doctor` work in this layout too. `bin/wt doctor` warns when the directory is not ignored.
+- `worktrees_dir` cannot be combined with `workspace_root`. `WT_WORKSPACES_ROOT` still overrides both for a single run.
+- Tools that scan the main checkout's file tree (for example RuboCop, file watchers or Tailwind content globs) can pick up files from the worktrees. Exclude the directory there if needed.
+
 ### Setup command
 
 `bin/wt setup` reruns setup for the **current checkout**. Run it from inside a linked worktree created by `bin/wt`, a worktree created manually with `git worktree`, or a checkout prepared by another tool.
@@ -126,7 +161,8 @@ bin/wt setup
 
 `bin/wt` also supports cleanup commands for worktrees it manages:
 
-- `bin/wt remove <name>` — remove the named worktree and delete its local branch
+- `bin/wt teardown` — stop the current worktree's Overmind and drop its development/test databases, keeping the checkout and branch
+- `bin/wt remove <name>` — run the same teardown, remove the named worktree and delete its local branch
 - `bin/wt delete <name>` — alias for `bin/wt remove <name>`
 - `bin/wt prune` — remove merged worktrees created by `bin/wt` in bulk
 
@@ -136,7 +172,17 @@ bin/wt setup
 
 `bin/wt prune` only targets linked worktrees created by `bin/wt` whose local branches are already merged into `origin`'s default branch. It skips the main checkout, skips the checkout you're currently in, and asks for confirmation before deleting the batch.
 
-If you want to preview a single removal first, use `--dry-run` with `bin/wt remove`:
+### Teardown command
+
+Run `bin/wt teardown` **inside a linked worktree** (including manually created or Pi worktrees). It boots that app separately in test and development (so environment-specific files and database URLs are resolved correctly), checks **all** task-enabled development/test database configurations and Rails' protected-environment metadata, stops Overmind with `overmind quit --socket .overmind.sock` if that local socket exists, and drops only those validated databases through Rails' database tasks. Production databases and the checkout/branch are left alone. Multi-database configurations (primary, cache, queue, cable, etc.) are supported; replicas and configurations with `database_tasks: false` are not dropped.
+
+Teardown refuses the main checkout, a missing/blank `WORKTREE_DATABASE_SUFFIX`, and any database whose name does not contain that suffix. For SQLite, the suffix must be in the filename, not merely a parent directory. **All names are validated before Overmind or any database is touched.** A working app bundle for both environments and `bin/rails` are required; install missing gems or fix unsafe database configuration before retrying. Both environments are booted even for a dry-run, so application initializers still execute. Rails' production/environment-mismatch protection cannot be bypassed with `DISABLE_DATABASE_ENVIRONMENT_CHECK`. The resolved test configuration is passed privately to the development process; all safety checks complete before Overmind is stopped or any database is dropped.
+
+The worktree's `.env` may define a literal `WORKTREE_DATABASE_SUFFIX` (unquoted or single/double quoted, optionally with `export`). Teardown never generates a suffix. When run inside the worktree it can also use the current environment if `.env` does not define one. `remove` reads the **target's** `.env` and starts Rails with only the caller's OS/Ruby runtime variables, never its suffix, database URLs, application settings or bundle. Any other required application settings/credentials must therefore be loadable by the target app itself (for example with dotenv or Rails credentials). Ensure that target file contains the actual suffix used to create its databases.
+
+`bin/wt remove` / `delete` run this same teardown **before** deleting the worktree or branch. If validation, Overmind shutdown, or a database drop fails, removal aborts and keeps the checkout and branch. Database drops are not transactional: databases already dropped before a later failure cannot be restored by this command. If only the branch remains (the worktree directory is already gone), removal only deletes the branch. `prune` retains its existing Git-only behavior; run teardown on its candidates first if they have databases.
+
+Use `bin/wt teardown --dry-run` to list the local Overmind socket and exact development/test database names without stopping or dropping them. To preview both teardown and checkout/branch removal, use `--dry-run` with `bin/wt remove`:
 
 ```bash
 bin/wt remove --dry-run feature-auth
@@ -160,6 +206,53 @@ bin/wt prune --dry-run
 
 `bin/wt update` is intentionally conservative: it only applies safe file-based fixes for managed templates and supported config shapes. It does **not** delete branches, remove worktrees, or rewrite ambiguous custom files automatically.
 
+`bin/wt doctor` and `bin/wt update` only look at `.pi/worktree.json` once it already runs `bin/wt setup`, or when you pass `bin/wt update --pi`.
+
+### Pi worktrees (pi-worktree extension)
+
+If you create worktrees from [Pi](https://github.com/badlogic/pi-mono) with `pi --worktree` or `/worktree`, rails-worktrees can configure them to run `bin/wt setup` automatically. This is opt-in:
+
+```bash
+bin/rails generate worktrees:install --pi
+# or, in an app that already has rails-worktrees installed:
+bin/wt update --pi
+```
+
+Both commands create or update `.pi/worktree.json`:
+
+```json
+{
+  "linkEnvFiles": false,
+  "postCreate": [
+    "bin/wt setup"
+  ]
+}
+```
+
+`.pi/worktree.json` is read by the [pi-worktree](https://www.npmjs.com/package/pi-worktree) npm extension (`pi install pi-worktree`), **not** by Pi core. Without that extension, the file has no effect. pi-worktree places worktrees in `.worktrees/` inside the repository by default. Set `config.worktrees_dir = '.worktrees'` and `config.branch_prefix = 'worktree'` to have `bin/wt` use the same directory and branch names; see [Worktrees inside the repository](#worktrees-inside-the-repository).
+
+`linkEnvFiles: false` matters. By default, pi-worktree symlinks the main checkout's gitignored `.env*` files into a new worktree before `postCreate` runs. `bin/wt setup` keeps existing `.env` values, so every Pi worktree would then reuse the main checkout's `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX`, and setup would write through the symlink into the main checkout. With linking disabled, each worktree gets its own `.env` and database identity.
+
+Existing configuration is merged, not replaced:
+
+- other keys (`dir`, `branchPrefix`, `preRemove`, …) and custom `postCreate` hooks are preserved; `bin/wt setup` is appended once and never duplicated
+- `linkEnvFiles` is only added when it is absent; an explicit `"linkEnvFiles": true`, invalid JSON, or a non-list `postCreate` is left untouched with a message explaining what to change by hand
+- no `preRemove` hook is added automatically, and the worktree directory and branch prefix stay under your control
+
+To opt into environment cleanup when Pi's pi-worktree extension destroys a worktree, add `bin/wt teardown` to `preRemove` (preserve any existing hooks):
+
+```json
+{
+  "linkEnvFiles": false,
+  "postCreate": ["bin/wt setup"],
+  "preRemove": ["bin/wt teardown"]
+}
+```
+
+The extension runs `preRemove` from inside the worktree. Teardown only cleans the environment; the calling tool remains responsible for removing the checkout and branch. Keep `linkEnvFiles: false` so a worktree does not share the main checkout's `.env`. Preview the cleanup inside the worktree with `bin/wt teardown --dry-run` first.
+
+pi-worktree runs each `postCreate` step with a 120-second timeout. If a first `bundle install` or `db:prepare` takes longer, run `bin/wt setup` again inside the worktree.
+
 ### Updating old `bin/wt` wrappers
 
 Versions before 0.7.1 generated `bin/wt` as a Ruby shebang wrapper. On hosts where Ruby is provided by mise but not already on `PATH`, that legacy wrapper can fail with `/usr/bin/env: ruby: No such file or directory` before rails-worktrees can activate mise.
@@ -207,6 +300,8 @@ New installs and repaired apps use a bash bootstrap wrapper that activates mise
 
 Worktree names must not contain `/` or whitespace, must not be `.` or `..`, and must be a valid Git ref component.
 
+These reserved words are commands, so `bin/wt <word>` never creates or reuses a worktree with that name and auto-picking skips them: `help`, `version`, `doctor`, `setup`, `update`, `prune`, `remove` and `delete`. `bin/wt help` and `bin/wt version` behave like `--help` and `--version`. An existing worktree with such a name (for example one created by `bin/wt help` in an older version) can still be cleaned up with `bin/wt remove help` or set up with `bin/wt setup ../<project>.worktrees/help`.
+
 ### Configuration
 
 The installer generates `config/initializers/rails_worktrees.rb` where you can override:
@@ -217,6 +312,7 @@ The initializer stays app-owned and gem-agnostic; `rails-worktrees` reads those
 |--------|---------|-------------|
 | `bootstrap_env` | `true` | Write `.env` when creating a worktree |
 | `workspace_root` | `nil` | Override the destination root (sibling layout when `nil`) |
+| `worktrees_dir` | `nil` | Create worktrees inside the main checkout, e.g. `'.worktrees'`; see [Worktrees inside the repository](#worktrees-inside-the-repository) |
 | `dev_port_range` | `3000..3999` | Port range for deterministic `DEV_PORT` allocation |
 | `branch_prefix` | `🚂` | Prefix for worktree branch names |
 | `name_sources_path` | bundled `names/` | Directory containing `.txt` name lists |

data/lib/generators/rails/worktrees/templates/bin/wt

@@ -77,14 +77,14 @@ exec ruby /dev/fd/3 "$@" 3<<'RUBY'
 def rails_worktrees_bootstrap_safe_invocation?(argv)
   args = argv.map(&:to_s)
   return true if args.empty?
-  return true if %w[-h --help -v --version].include?(args.first)
+  return true if %w[-h --help help -v --version version].include?(args.first)
   return true if %w[--env --print-env].include?(args.first)
 
-  command_args = args.reject { |arg| %w[--dry-run --skip-setup --env --print-env].include?(arg) }
+  command_args = args.reject { |arg| %w[--dry-run --skip-setup --pi --env --print-env].include?(arg) }
   command = command_args.first
 
   return true if %w[setup doctor update].include?(command)
-  return false if %w[remove delete prune].include?(command)
+  return false if %w[remove delete prune teardown].include?(command)
 
   command_args.length <= 1
 end

data/lib/generators/rails/worktrees/templates/rails_worktrees.rb.tt

@@ -5,6 +5,13 @@ Rails.application.config.x.rails_worktrees.tap do |config|
   # By default, worktrees go in a sibling "<project>.worktrees" directory.
   # Uncomment to override with a custom parent directory that uses <root>/<project>/<name>.
   # config.workspace_root = File.expand_path('~/worktrees')
+  #
+  # Or keep worktrees inside this checkout in <app>/.worktrees/<name>, like Pi's pi-worktree
+  # extension. wt adds the directory to .git/info/exclude unless .gitignore already covers it.
+  # Combine with branch_prefix 'worktree' so wt and Pi share worktree/<name> branch names.
+  # Cannot be combined with workspace_root.
+  # config.worktrees_dir = '.worktrees'
+  # config.branch_prefix = 'worktree'
 <% end -%>
   # config.bootstrap_env = false
   # config.dev_port_range = 3000..3999
@@ -21,6 +28,7 @@ Rails.application.config.x.rails_worktrees.tap do |config|
   # config.post_create_command = nil    # nil = built-in steps; false = skip all; 'script/worktree-setup' = custom command
   # config.run_bundle_install = true
   # config.run_yarn_install = true      # auto-skipped when yarn.lock is absent
+  # config.run_playwright_install = true # installs Playwright Chromium when package.json uses playwright
   # config.run_db_prepare = true
   # config.run_test_db_prepare = true
   # config.run_test_assets_precompile = true

data/lib/generators/worktrees/install/install_generator.rb

@@ -7,6 +7,7 @@ require_relative '../../../rails/worktrees/database_config_updater'
 require_relative '../../../rails/worktrees/procfile_updater'
 require_relative '../../../rails/worktrees/mise_toml_updater'
 require_relative '../../../rails/worktrees/puma_config_updater'
+require_relative '../../../rails/worktrees/pi_worktree_config_updater'
 
 module Worktrees
   module Generators
@@ -35,8 +36,13 @@ module Worktrees
                      'Apply common Procfile.dev, config/puma.rb, and mise .env',
                      'follow-up edits when safe; also generate bin/ob'
                    ].join(' ')
+      class_option :pi,
+                   type: :boolean,
+                   default: false,
+                   desc: 'Generate .pi/worktree.json so the pi-worktree extension runs bin/wt setup in new worktrees'
 
       FILE_ENCODING = 'UTF-8'.freeze
+      PI_WORKTREE_CONFIG = ::Rails::Worktrees::PiWorktreeConfigUpdater::RELATIVE_PATH
 
       FOLLOW_UP_TEMPLATE = <<~TEXT.freeze
           ============================================
@@ -97,6 +103,21 @@ module Worktrees
         announce_database_update(result)
       end
 
+      def configure_pi_worktree
+        return unless options[:pi]
+
+        path = pi_worktree_config_path
+        unsafe_reason = ::Rails::Worktrees::PiWorktreeConfigPath.conflict(destination_root)
+        return announce_unsafe_pi_worktree_config(unsafe_reason) if unsafe_reason
+
+        result = ::Rails::Worktrees::PiWorktreeConfigUpdater.new(
+          content: File.exist?(path) ? File.read(path, encoding: FILE_ENCODING) : nil
+        ).call
+        write_pi_worktree_config(path, result.content) if result.changed?
+        @pi_worktree_outcome = result.status
+        announce_updater_result(PI_WORKTREE_CONFIG, result)
+      end
+
       def verify_installation
         if git_repo?
           say_status(:ok, 'git repository detected', :green)
@@ -130,6 +151,21 @@ module Worktrees
         ]
       end
 
+      def pi_worktree_config_path
+        File.join(destination_root, PI_WORKTREE_CONFIG)
+      end
+
+      def write_pi_worktree_config(path, content)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+      end
+
+      def announce_unsafe_pi_worktree_config(reason)
+        @pi_worktree_outcome = :conflict
+        say_status(:skip, PI_WORKTREE_CONFIG, :yellow)
+        say("#{PI_WORKTREE_CONFIG} #{reason}; leaving it unchanged. Add the bin/wt setup hook manually.")
+      end
+
       def database_update_result
         result = ::Rails::Worktrees::DatabaseConfigUpdater.new(
           content: File.read(database_config_path, encoding: FILE_ENCODING)
@@ -145,7 +181,7 @@ module Worktrees
       end
 
       def follow_up_notes_text
-        [super, browser_follow_up_notes_text, puma_follow_up_notes_text].join
+        [super, browser_follow_up_notes_text, puma_follow_up_notes_text, pi_worktree_follow_up_notes_text].join
       end
 
       def installed_items_text
@@ -156,9 +192,31 @@ module Worktrees
         items << '      • bin/ob' if install_browser_wrapper?
         items << '      • Procfile.dev.worktree.example' unless options[:yolo]
         items << database_follow_up_line if database_follow_up_line
+        items << pi_worktree_follow_up_line if pi_worktree_follow_up_line
         items.join("\n")
       end
 
+      def pi_worktree_follow_up_line
+        case @pi_worktree_outcome
+        when :updated, :identical
+          "      • #{PI_WORKTREE_CONFIG} (pi-worktree postCreate runs bin/wt setup)"
+        when :conflict
+          "      • #{PI_WORKTREE_CONFIG} needs manual review — see the message above"
+        end
+      end
+
+      def pi_worktree_follow_up_notes_text
+        return '' unless options[:pi]
+
+        [
+          '',
+          '      Pi worktrees:',
+          "        #{PI_WORKTREE_CONFIG} is read by the pi-worktree extension",
+          '        ($ pi install pi-worktree); it is not native Pi core configuration.',
+          '        Add the worktree directory (default .worktrees/) to .gitignore.'
+        ].join("\n")
+      end
+
       def database_follow_up_line
         case @database_outcome
         when :updated

data/lib/rails/worktrees/cli.rb

@@ -2,8 +2,10 @@ module Rails
   module Worktrees
     # Shell entrypoint for the wt executable.
     class CLI
-      LOADER_OPTIONAL_COMMANDS = %w[doctor update -h --help -v --version].freeze
-      LOADER_IGNORED_FLAGS = %w[--dry-run --force --skip-setup].freeze
+      LOADER_OPTIONAL_COMMANDS = %w[doctor update -h --help help -v --version version].freeze
+      # Commands that use project configuration when it loads, but must keep working when it does not.
+      LOADER_BEST_EFFORT_COMMANDS = %w[doctor].freeze
+      LOADER_IGNORED_FLAGS = %w[--dry-run --force --skip-setup --pi].freeze
       SETUP_SUBCOMMAND = 'setup'.freeze
 
       def initialize(
@@ -20,7 +22,11 @@ module Rails
 
       def start
         configuration = ::Rails::Worktrees.configuration
-        load_project_configuration(configuration) if should_load_project_configuration?
+        if should_load_project_configuration?
+          load_project_configuration(configuration)
+        elsif best_effort_configuration_command?
+          load_project_configuration_best_effort(configuration)
+        end
         command_for(configuration).run
       rescue ::Rails::Worktrees::Error => e
         @io.fetch(:stderr).puts("Error: #{e.message}")
@@ -35,6 +41,17 @@ module Rails
         raise ::Rails::Worktrees::Error, "Failed to load worktrees configuration: #{e.class}: #{e.message}"
       end
 
+      # A broken initializer must not block recovery; wt doctor then reports with default settings.
+      def load_project_configuration_best_effort(configuration)
+        load_project_configuration(configuration)
+      rescue ::Rails::Worktrees::Error
+        configuration
+      end
+
+      def best_effort_configuration_command?
+        LOADER_BEST_EFFORT_COMMANDS.include?(argv_without_flags.first)
+      end
+
       def configuration_root
         return expand_setup_target_path if explicit_setup_path_target?
 

data/lib/rails/worktrees/command/in_repo_worktrees.rb

@@ -0,0 +1,85 @@
+require 'fileutils'
+
+module Rails
+  module Worktrees
+    class Command
+      # Keeps an in-repo worktrees_dir out of the main checkout's untracked files.
+      module InRepoWorktrees
+        private
+
+        def in_repo_layout?(workspaces) = workspaces[:layout] == :in_repo
+
+        def ensure_worktrees_dir_ignored(context)
+          workspaces = context[:workspaces]
+          return unless in_repo_layout?(workspaces)
+          return if worktrees_dir_ignored?(context[:primary_root], workspaces)
+
+          entry = worktrees_dir_exclude_entry(workspaces)
+          exclude_path = info_exclude_path(context[:primary_root])
+          return info("Would add '#{entry}' to #{exclude_path}") if dry_run?
+
+          append_exclude_entry(exclude_path, entry)
+        end
+
+        def worktrees_dir_ignored?(primary_root, workspaces)
+          git_success?('-C', primary_root, 'check-ignore', '-q', "#{workspaces[:relative_dir]}/")
+        end
+
+        # Escapes gitignore metacharacters so the entry matches only the literal directory.
+        def worktrees_dir_exclude_entry(workspaces)
+          escaped = workspaces[:relative_dir]
+                    .gsub(/[\\*?\[\]]/) { |char| "\\#{char}" }
+                    .sub(/ +\z/) { |spaces| spaces.gsub(' ', '\ ') }
+          "/#{escaped}/"
+        end
+
+        def info_exclude_path(primary_root)
+          git_path = git_capture('-C', primary_root, 'rev-parse', '--git-path', 'info/exclude').strip
+          expand_git_path(git_path, base_dir: primary_root)
+        end
+
+        def append_exclude_entry(exclude_path, entry)
+          FileUtils.mkdir_p(File.dirname(exclude_path))
+          separator = missing_trailing_newline?(exclude_path) ? "\n" : ''
+          File.open(exclude_path, 'a') { |file| file.write("#{separator}#{entry}\n") }
+          info("Added '#{entry}' to #{exclude_path} so the main checkout ignores in-repo worktrees")
+        rescue SystemCallError => e
+          warning(
+            "Could not update #{exclude_path} (#{e.class}); add '#{entry}' to .gitignore " \
+            'so the main checkout does not show the worktrees as untracked files.'
+          )
+        end
+
+        def missing_trailing_newline?(path)
+          File.file?(path) && !File.empty?(path) && !File.read(path).end_with?("\n")
+        end
+
+        def in_repo_worktrees_doctor_check(repository)
+          workspaces = repository[:workspaces]
+          return unless in_repo_layout?(workspaces)
+
+          if worktrees_dir_ignored?(repository[:primary_root], workspaces)
+            ignored_worktrees_dir_check(workspaces)
+          else
+            unignored_worktrees_dir_check(workspaces)
+          end
+        end
+
+        def ignored_worktrees_dir_check(workspaces)
+          doctor_check(category: :worktree, status: :ok,
+                       headline: "In-repo worktrees directory #{workspaces[:root]} is ignored by Git.")
+        end
+
+        def unignored_worktrees_dir_check(workspaces)
+          doctor_check(
+            category: :worktree,
+            status: :warning,
+            headline: "In-repo worktrees directory #{workspaces[:root]} is not ignored by Git.",
+            messages: ["Add '#{worktrees_dir_exclude_entry(workspaces)}' to .gitignore, " \
+                       'or create a worktree with wt to add it to .git/info/exclude.']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rails/worktrees/command/name_picking.rb

@@ -45,7 +45,8 @@ module Rails
 
         def list_available_names(source_file, project_name, workspaces)
           source_names(source_file).select do |candidate|
-            valid_auto_name?(candidate) && available_for_auto_pick?(candidate, project_name, workspaces)
+            !RESERVED_WORDS.include?(candidate) && valid_auto_name?(candidate) &&
+              available_for_auto_pick?(candidate, project_name, workspaces)
           end
         end
 

data/lib/rails/worktrees/command/output.rb

@@ -8,10 +8,10 @@ module Rails
 
         def handle_meta_command
           case @argv.first
-          when '-h', '--help'
+          when '-h', '--help', 'help'
             @stdout.print(usage)
             0
-          when '-v', '--version'
+          when '-v', '--version', 'version'
             @stdout.puts("wt #{Rails::Worktrees::VERSION}")
             0
           when '--env', '--print-env'
@@ -30,23 +30,26 @@ module Rails
             Create and clean up Git worktrees for the current repository.
 
             Usage: wt [worktree-name]
+                   wt help | wt version
                    wt [--skip-setup] [worktree-name]
                    wt --dry-run [worktree-name]
                    wt --print-env <worktree-name>
                    wt doctor
                    wt setup [--dry-run] [path|name]
-                   wt update [--dry-run]
+                   wt update [--dry-run] [--pi]
+                   wt teardown [--dry-run]
                    wt remove [--dry-run] [--force] <worktree-name>
                    wt delete [--dry-run] [--force] <worktree-name>
                    wt prune [--dry-run]
 
             Options:
-              -h, --help                  Show this help message
-              -v, --version               Show the script version
+              -h, --help, help            Show this help message
+              -v, --version, version      Show the script version
               --dry-run [name]            Preview worktree creation or cleanup without changing anything
               --skip-setup               Create the worktree without running setup steps
               --force                     Delete an unmerged local branch with wt remove/delete
               --env, --print-env <name>   Preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
+              --pi                        With wt update, add the pi-worktree bin/wt setup hook
 
             Quick start:
               wt                 Auto-pick a name from a bundled *.txt list
@@ -59,6 +62,8 @@ module Rails
               wt setup my-feature
               wt setup ../my-project.worktrees/my-feature
               wt update --dry-run
+              wt teardown --dry-run
+              wt teardown
               wt remove my-feature
               wt remove --force my-feature
               wt prune
@@ -66,12 +71,17 @@ module Rails
             How it works:
               - by default creates worktrees beside the repo in ../<project>.worktrees/<name>
               - when workspace_root or WT_WORKSPACES_ROOT is set, creates worktrees in <root>/<project>/<name>
+              - when worktrees_dir is set (for example '.worktrees'), creates worktrees inside the main checkout in <repo>/<worktrees_dir>/<name>
+              - reserved words are commands, never new worktree names: #{RESERVED_WORDS.join(', ')}
               - always uses the branch name #{@configuration.branch_prefix}/<name>
               - bases new branches on the repository's origin default branch
               - by default wt <name> both creates the worktree and runs setup automatically
               - wt setup reruns setup for the current checkout, a managed worktree name, or a specific checkout path, including manually-created worktrees
               - wt doctor audits install/config drift plus basic worktree health without changing files
               - wt update applies safe file-based fixes for managed installer artifacts and config hints
+              - wt update --pi also writes .pi/worktree.json for the pi-worktree extension (not Pi core)
+              - wt teardown stops local Overmind and drops suffix-validated development/test databases, keeping the checkout
+              - wt remove/delete run teardown before removing the checkout and local branch
               - wt remove/delete can run from the main checkout or any sibling worktree, but never remove the worktree you're currently in
               - wt prune removes merged worktrees created by wt while skipping the main checkout and the checkout you're in
               - auto-discovers bundled *.txt files from #{@configuration.name_sources_path}