rails-worktrees 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46ec0bdd9361eabe4925e37760bcd5d050c8f71072ec93cfdb427e244186ea8e
-  data.tar.gz: 965a2ea5c6d454739f833cf0a534a4b195903531d159e2fb25f5eff9bb71083c
+  metadata.gz: 9f11c54fe45c6061774b7181c80c7a25ba1c824d04fe06668ca0d6fe0bc3c453
+  data.tar.gz: 9470d8a967f77f0188679e8f9b50fd5a78c4aebe6f10e268cba00ffaff1ebea0
 SHA512:
-  metadata.gz: fa02fa0f6786fb3865326f8cef1e4beb804a25411cc7b5d15676236424b23a5cd4e5b55bd21550f1b1e3f422384f1c06662ff05b9d40e291e931b1bd09775af2
-  data.tar.gz: 43269ef67990a1a4986f407a96696b9b01faabf8a64930e676c3c505a214d38b228ba3dae5e9ffa76fc74dc59d96bbdad3eafceb42c99236c64a23954fbefced
+  metadata.gz: c3775b72de293d0cf888f9b94cbbeae5b6031f001c641a1365f8f2662caa38de8b04bd4235a4e5c3f7b81279f6a23ce4637f4b2cfa6d6e1ba9d0fd0619daede2
+  data.tar.gz: 0c07249ae8bad61d6ae0cdad68f58752579145175e0d43005772e0d91f2f04b8d672f99a1952ce168e881d04e0b88ab4bbb8603183d4a9a2ace12f5c1767584e

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.3.0"}
+{".":"0.5.0"}

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.0](https://github.com/asjer/rails-worktrees/compare/v0.4.0...v0.5.0) (2026-04-02)
+
+
+### Features
+
+* **maintenance:** add doctor and update maintenance commands ([fce44f7](https://github.com/asjer/rails-worktrees/commit/fce44f757ce9835eb663010f30a192c23f82080c))
+
+
+### Bug Fixes
+
+* **install:** support development-only gem installs ([bf9e742](https://github.com/asjer/rails-worktrees/commit/bf9e74260a88ba37674a5318b48ad5c93f1c0399))
+
+## [0.4.0](https://github.com/asjer/rails-worktrees/compare/v0.3.0...v0.4.0) (2026-03-30)
+
+
+### Features
+
+* **delete:** add `bin/wt remove` command to delete worktrees and local branches ([5905723](https://github.com/asjer/rails-worktrees/commit/5905723712e3ca11fd6614633e68855e33bb50e3))
+
 ## [0.3.0](https://github.com/asjer/rails-worktrees/compare/v0.2.2...v0.3.0) (2026-03-30)
 
 
@@ -45,12 +64,3 @@
 ### Features
 
 * add wt command and rails installer ([5d798d5](https://github.com/asjer/rails-worktrees/commit/5d798d5129585331780f0259b39061194feb66e3))
-
-## [Unreleased]
-
-- Add a gem-managed `wt` CLI for creating Rails worktrees.
-- Add an optional gem-managed `ob` CLI plus generated `bin/ob` wrapper for opening `localhost:$DEV_PORT` routes.
-- Add a Rails installer generator that creates `bin/wt` and `config/initializers/rails_worktrees.rb`.
-- Add conservative `config/database.yml` patching for common development/test database names.
-- Add a manual-dispatch GitHub Actions workflow for the disposable Rails smoke test.
-- Add smoke-test workflow debug controls for retained artifacts and verbose output.

data/README.md

@@ -11,7 +11,7 @@
 ## Installation
 
 ```bash
-bundle add rails-worktrees
+bundle add rails-worktrees --group development
 bin/rails generate worktrees:install
 # or, to also generate bin/ob without the yolo follow-ups:
 bin/rails generate worktrees:install --browser
@@ -19,6 +19,8 @@ bin/rails generate worktrees:install --browser
 bin/rails generate worktrees:install --yolo
 ```
 
+The generated initializer checks that `rails-worktrees` is actually loaded before it calls `Rails::Worktrees.configure`, so the app can still boot in environments like `test` when the gem is only bundled for `:development`.
+
 The installer adds:
 
 - `bin/wt` — a thin wrapper that executes the gem-owned CLI
@@ -42,6 +44,13 @@ bin/wt                          # auto-pick a name from bundled *.txt lists
 bin/wt my-feature               # use an explicit worktree name
 bin/wt --dry-run my-feature     # preview the full setup without changing anything
 bin/wt --print-env my-feature   # preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
+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 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/ob                          # open http://localhost:$DEV_PORT/
 bin/ob contact                  # open http://localhost:$DEV_PORT/contact
@@ -55,7 +64,8 @@ bin/ob --print-url '?from=nav'  # print the resolved URL without opening a brows
 |------|-------------|
 | `-h`, `--help` | Show the help message |
 | `-v`, `--version` | Show the script version |
-| `--dry-run [name]` | Preview the full worktree setup without changing anything |
+| `--dry-run [name]` | Preview worktree creation or cleanup without changing anything |
+| `--force` | Force branch deletion for `bin/wt remove` / `bin/wt delete` |
 | `--env`, `--print-env <name>` | Preview `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` |
 
 ### Default behavior
@@ -80,6 +90,45 @@ workspace/
 
 `WT_WORKSPACES_ROOT` or `config.workspace_root` overrides the destination root and uses the layout `<root>/<project>/<name>`.
 
+### Cleanup commands
+
+`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 delete <name>` — alias for `bin/wt remove <name>`
+- `bin/wt prune` — remove merged worktrees created by `bin/wt` in bulk
+
+`bin/wt remove` and `bin/wt prune` can be run from the main checkout or any sibling worktree in the same repository family.
+
+`bin/wt remove` refuses to remove the worktree you're currently in, and by default only deletes a local branch after confirming it is already merged into `origin`'s default branch. Use `bin/wt remove --force <name>` when you intentionally want to delete an unmerged local branch too.
+
+`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`:
+
+```bash
+bin/wt remove --dry-run feature-auth
+```
+
+If you want to see what `bin/wt prune` would clean up before saying yes, use `--dry-run`:
+
+```bash
+bin/wt prune --dry-run
+```
+
+### Maintenance commands
+
+`bin/wt` also includes a small maintenance surface for installer drift and checkout health:
+
+- `bin/wt doctor` — audit managed files plus basic Git/worktree health without changing anything
+- `bin/wt update --dry-run` — preview safe file-based fixes
+- `bin/wt update` — apply safe file-based fixes for supported managed files
+
+`bin/wt doctor` checks the generated initializer, `bin/wt`, optional `bin/ob`, supported config files such as `config/database.yml`, `Procfile.dev`, `config/puma.rb`, and `mise.toml`/`.mise.toml`, plus basic repository/worktree conditions like resolving `origin`'s default branch and spotting stale registered worktree paths.
+
+`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.
+
+
 ### Interactive prompts
 
 `bin/wt` handles several edge cases interactively:
@@ -88,6 +137,7 @@ workspace/
 - **Branch already exists on origin** — asks whether to create a local tracking worktree
 - **Target directory already exists with matching branch** — asks whether to reuse it
 - **Target directory already exists with a different branch** — asks whether to remove and recreate it
+- **Prune found merged worktrees created by `wt`** — asks whether to delete the batch
 - **Retired bundled name used explicitly** — rejects it and suggests running `wt` with no argument
 
 ### Name validation
@@ -98,6 +148,8 @@ Worktree names must not contain `/` or whitespace, must not be `.` or `..`, and
 
 The installer generates `config/initializers/rails_worktrees.rb` where you can override:
 
+The initializer becomes a no-op whenever `rails-worktrees` is not loaded in the current bundle groups.
+
 | Option | Default | Description |
 |--------|---------|-------------|
 | `bootstrap_env` | `true` | Write `.env` when creating a worktree |
@@ -197,7 +249,7 @@ This smoke test:
 - installs `rails-worktrees` from the current checkout path
 - runs `bin/rails generate worktrees:install --yolo`
 - verifies `bin/wt`, `bin/ob`, the generated initializer, that `--yolo` skips the Procfile example, yolo updates to `Procfile.dev`, `config/puma.rb`, and `mise.toml`, `config/database.yml` patching, and worktree `.env` bootstrapping
-- creates a temporary bare `origin` and confirms `bin/wt smoke-branch` creates a real worktree
+- creates a temporary bare `origin`, confirms `bin/wt smoke-branch` creates a real worktree, and confirms `bin/wt remove smoke-branch` can remove that merged worktree from a sibling worktree checkout
 
 By default, the script cleans up all temp directories after the run. Set `KEEP_SMOKE_TEST_ARTIFACTS=1` to keep them around for debugging, or set `RAILS_WORKTREES_SMOKE_RAILS_VERSION` to try a different compatible Rails version.
 

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

@@ -1,19 +1,23 @@
-Rails::Worktrees.configure do |config|
+if Gem.loaded_specs.key?('rails-worktrees') &&
+    defined?(Rails::Worktrees) &&
+    Rails::Worktrees.respond_to?(:configure)
+  Rails::Worktrees.configure do |config|
 <% if options['conductor'] -%>
-  config.workspace_root = <%= conductor_workspace_root %>
+    config.workspace_root = <%= conductor_workspace_root %>
 <% else -%>
-  # 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')
+    # 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')
 <% end -%>
-  # config.bootstrap_env = false
-  # config.dev_port_range = 3000..3999
-  # config.worktree_database_suffix_max_length = 18
-  # config.branch_prefix = '🚂'
-  # config.name_sources_path = Rails.root.join('config/worktree_names').to_s
-  # config.used_names_file = File.join(
-  #   ENV.fetch('XDG_STATE_HOME', File.expand_path('~/.local/state')),
-  #   'rails-worktrees',
-  #   'used-names.tsv'
-  # )
+    # config.bootstrap_env = false
+    # config.dev_port_range = 3000..3999
+    # config.worktree_database_suffix_max_length = 18
+    # config.branch_prefix = '🚂'
+    # config.name_sources_path = Rails.root.join('config/worktree_names').to_s
+    # config.used_names_file = File.join(
+    #   ENV.fetch('XDG_STATE_HOME', File.expand_path('~/.local/state')),
+    #   'rails-worktrees',
+    #   'used-names.tsv'
+    # )
+  end
 end

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

@@ -1,9 +1,11 @@
 require 'open3'
+require 'fileutils'
 
 module Rails
   module Worktrees
     class Command
       # Shell-level git helpers, branch/worktree queries, and worktree creation.
+      # rubocop:disable Metrics/ModuleLength
       module GitOperations
         private
 
@@ -40,14 +42,18 @@ module Rails
           worktree_branch_checked_out?(branch_name, worktree_list_output)
         end
 
+        def current_checkout_branch
+          git_capture('branch', '--show-current', allow_failure: true).strip
+        end
+
         def registered_worktree_path?(target_dir)
           normalized_target = canonical_path(target_dir)
 
-          worktree_list_output.each_line.any? do |line|
-            next unless line.start_with?('worktree ')
+          worktree_entries.any? { |entry| entry[:path] == normalized_target }
+        end
 
-            canonical_path(line.delete_prefix('worktree ').strip) == normalized_target
-          end
+        def worktree_entries_for_branch(branch_name)
+          worktree_entries.select { |entry| entry[:branch_name] == branch_name }
         end
 
         def worktree_branch_checked_out?(branch_name, output)
@@ -59,11 +65,38 @@ module Rails
 
         def worktree_list_output = git_capture('worktree', 'list', '--porcelain')
 
+        def worktree_entries
+          worktree_list_output.split("\n\n").filter_map do |block|
+            entry = parse_worktree_entry(block)
+            entry[:path] ? entry : nil
+          end
+        end
+
+        def parse_worktree_entry(block)
+          entry = { branch_name: nil }
+
+          block.each_line(chomp: true) do |line|
+            case line
+            when /\Aworktree /
+              entry[:path] = canonical_path(line.delete_prefix('worktree '))
+            when %r{\Abranch refs/heads/}
+              entry[:branch_name] = line.delete_prefix('branch refs/heads/')
+            end
+          end
+
+          entry
+        end
+
         def canonical_path(path)
           File.realpath(path)
         rescue Errno::ENOENT then File.expand_path(path)
         end
 
+        def branch_merged_into_default?(branch_name)
+          default_branch = resolve_default_branch
+          git_success?('merge-base', '--is-ancestor', branch_name, "origin/#{default_branch}")
+        end
+
         def create_new_branch_worktree(branch_name, target_dir)
           default_branch = resolve_default_branch
           if dry_run?
@@ -101,6 +134,33 @@ module Rails
           git!('worktree', 'remove', '--force', target_dir)
         end
 
+        def remove_target_path(target_dir)
+          if registered_worktree_path?(target_dir)
+            remove_registered_worktree(target_dir)
+          else
+            info("Removing existing target path '#{target_dir}'")
+            FileUtils.rm_rf(target_dir)
+          end
+        end
+
+        def delete_local_branch(branch_name, force: false)
+          ensure_local_branch_removable!(branch_name, force: force)
+
+          info("Deleting local branch '#{branch_name}'")
+          git!('branch', force ? '-D' : '-d', branch_name)
+        end
+
+        def ensure_local_branch_removable!(branch_name, force: false)
+          return if force
+
+          default_branch = resolve_default_branch
+          return if branch_merged_into_default?(branch_name)
+
+          raise Error,
+                "Local branch '#{branch_name}' is not merged into origin/#{default_branch}. " \
+                'Re-run with --force to delete it.'
+        end
+
         def git!(*)
           stdout_str, stderr_str, status = Open3.capture3(@env.to_h, 'git', *, chdir: @cwd)
           return stdout_str if status.success?
@@ -137,6 +197,7 @@ module Rails
           git!('worktree', 'add', '--force', target_dir, branch_name)
         end
       end
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

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

@@ -2,6 +2,7 @@ module Rails
   module Worktrees
     class Command
       # User-facing output, prompts, and help text.
+      # rubocop:disable Metrics/ModuleLength
       module Output
         private
 
@@ -26,16 +27,22 @@ module Rails
         def usage
           <<~USAGE
             wt #{::Rails::Worktrees::VERSION}
-            Create Git worktrees for the current repository.
+            Create and clean up Git worktrees for the current repository.
 
             Usage: wt [worktree-name]
                    wt --dry-run [worktree-name]
                    wt --print-env <worktree-name>
+                   wt doctor
+                   wt update [--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
-              --dry-run [name]            Preview the full worktree setup without changing anything
+              --dry-run [name]            Preview worktree creation or cleanup without changing anything
+              --force                     Delete an unmerged local branch with wt remove/delete
               --env, --print-env <name>   Preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
 
             Quick start:
@@ -43,12 +50,21 @@ module Rails
               wt my-feature      Use an explicit worktree name
               wt --dry-run my-feature
               wt --print-env my-feature
+              wt doctor
+              wt update --dry-run
+              wt remove my-feature
+              wt remove --force my-feature
+              wt prune
 
             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>
               - always uses the branch name #{@configuration.branch_prefix}/<name>
               - bases new branches on the repository's origin default branch
+              - 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 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}
               - retires bundled names in #{@configuration.used_names_file}
           USAGE
@@ -75,7 +91,7 @@ module Rails
           @stdout.puts("→ #{message}")
         end
 
-        def announce_dry_run = info('Dry run: previewing worktree setup without making changes')
+        def announce_dry_run = info('Dry run: previewing worktree changes without applying them')
 
         def complete_dry_run(context, env_values:)
           success('Dry run complete')
@@ -90,6 +106,76 @@ module Rails
           complete_dry_run(context, env_values: preview_result&.values)
         end
 
+        def complete_remove_dry_run(context, worktree_exists:, branch_exists:)
+          info(remove_dry_run_target_message(context, worktree_exists: worktree_exists))
+          info(remove_dry_run_branch_message(context, branch_exists: branch_exists))
+
+          success('Dry run complete')
+          print_context_summary(context, env_values: nil)
+          info('No changes were made.')
+          0
+        end
+
+        def remove_dry_run_target_message(context, worktree_exists:)
+          return "Would skip worktree removal because '#{context[:target_dir]}' does not exist" unless worktree_exists
+
+          action = if registered_worktree_path?(context[:target_dir])
+                     'remove registered worktree at'
+                   else
+                     'remove existing target path'
+                   end
+          "Would #{action} '#{context[:target_dir]}'"
+        end
+
+        def remove_dry_run_branch_message(context, branch_exists:)
+          unless branch_exists
+            return "Would skip local branch deletion because '#{context[:branch_name]}' does not exist"
+          end
+
+          "Would delete local branch '#{context[:branch_name]}'"
+        end
+
+        def print_prune_candidates(candidates)
+          candidates.each do |context|
+            info("#{context[:worktree_name]} => #{context[:target_dir]} (#{context[:branch_name]})")
+          end
+        end
+
+        def complete_prune_noop
+          info('No merged worktrees created by wt are ready to prune.')
+          0
+        end
+
+        def complete_prune_dry_run(candidates)
+          info("Would prune #{candidates.length} merged worktree#{'s' unless candidates.length == 1}")
+          success('Dry run complete')
+          info('No changes were made.')
+          0
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def print_doctor_report(checks)
+          checks.each do |check|
+            printer = check.ok? ? :info : :warning
+            send(printer, "#{check.category}: #{check.headline}")
+            Array(check.messages).each { |message| info(message) }
+          end
+
+          fixable_count = checks.count(&:fixable?)
+          warning_count = checks.count(&:warning?)
+
+          if fixable_count.zero? && warning_count.zero?
+            success('Doctor found no issues.')
+          else
+            warning(
+              "Doctor found #{fixable_count} fixable issue#{'s' unless fixable_count == 1} and " \
+              "#{warning_count} warning#{'s' unless warning_count == 1}."
+            )
+            info('Run `wt update --dry-run` to preview safe fixes.') if fixable_count.positive?
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
         def warning(message)
           @stderr.puts("⚠️  #{message}")
         end
@@ -124,6 +210,7 @@ module Rails
           @stdout.puts("Suffix: #{suffix}")
         end
       end
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

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

@@ -5,6 +5,28 @@ module Rails
       module WorkspacePaths
         private
 
+        def resolve_repository_context
+          current_root = canonical_path(git_capture('rev-parse', '--show-toplevel').strip)
+          common_dir = expand_git_path(git_capture('rev-parse', '--git-common-dir').strip)
+          primary_root = primary_checkout_root_for(current_root, common_dir)
+
+          repository_context_for(current_root, primary_root)
+        end
+
+        def repository_context_for(current_root, primary_root)
+          project_name = File.basename(primary_root)
+          workspaces = resolve_workspaces(primary_root, project_name)
+
+          {
+            current_root: current_root,
+            primary_root: primary_root,
+            project_name: project_name,
+            workspaces: workspaces,
+            workspaces_root: workspaces[:root],
+            uses_default_workspace_root: workspaces[:uses_default_root]
+          }
+        end
+
         def resolve_workspaces(repo_root, project_name)
           explicit_root = configured_workspaces_root
           return { root: explicit_root, uses_default_root: false } if explicit_root
@@ -38,6 +60,18 @@ module Rails
           FileUtils.mkdir_p(parent_dir)
         end
 
+        def primary_checkout_root_for(current_root, common_dir)
+          return current_root unless File.basename(common_dir) == '.git'
+
+          canonical_path(File.dirname(common_dir))
+        end
+
+        def expand_git_path(path)
+          return path if path.start_with?('/')
+
+          File.expand_path(path, @cwd)
+        end
+
         def present_path?(path)
           !path.nil? && !path.empty?
         end