rails-worktree 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd8698c3bbb798a625214a84c2f0e6cc585b4759cd9ef6ae9d3806eb6e6c572a
-  data.tar.gz: 98611afb823f7b713a6c12412232d1cc6e85ef023eaad9b0518bb211aa41e628
+  metadata.gz: 2513c2eb6cd2e0d754ecdfb27482038c94204584a4b7edf076c15f36e9e7c9d8
+  data.tar.gz: cde0e84643776ce5e030c62ae4f6d5fd59635b6923b1401abddd660747c4dfdd
 SHA512:
-  metadata.gz: 71ce31463125cb9756e54f0b66f0b153f39cc8658a9af88c6d8a2a726c22521b5ac5649d5b0a204bfc9775f4c925bfe77648120c734a13953b77eff3781345d2
-  data.tar.gz: 96f6e366bdd38b682df8735b368ac26c2b56398bb750d278b0d1556af99cdb7cd97ff811628ce6ed53aaf8d9f061717488d8a84757f354b2d4d03f67802aaed0
+  metadata.gz: 6b54cce1aea73f3e20c7c7e560395121fd984e2e848b671ffd7385291e566bc825e95eb7880c1d438b30a8fddb6cec59fb9b370e7f91b617972c6d616157a56b
+  data.tar.gz: ec8c82d608897e3addafec37509703a6a4529eb7edd65017d5383c355c98db66d3a7278533e0cf8ca979019b5e871f0c768f80731fa88ce5266e75204207175d

data/README.md

@@ -1,16 +1,20 @@
 # Rails Worktree
 
-Git worktree management for Rails projects with isolated databases and configurations.
+Provisions git worktrees for Rails projects: configuration files, node_modules and optional
+isolated databases, in a checkout created by `bin/worktree`, plain git, herdr, Claude Code or Codex.
 
 ## Features
 
-- Create git worktrees from an explicit base with automatic branch creation
-- Run commands with worktree-local Bundler and binstubs
-- Verify the recorded base before execution and push
-- Isolated databases per worktree (separate development and test databases)
-- Automatic configuration file copying
-- Copy node_modules from main worktree
-- Easy cleanup with database dropping and directory removal
+- `bin/worktree init` prepares any linked worktree at one of three levels, and is safe to repeat:
+  - `minimal`: copies gitignored configuration from the main checkout, creates directories, links `node_modules`.
+  - `test`: minimal plus your isolated test setup command, or an own test database.
+  - `full`: minimal plus own development and test databases. The development database is cloned
+    from the main one with `CREATE DATABASE ... TEMPLATE` (PostgreSQL), so it is ready in seconds.
+- `bin/worktree create NAME BASE` creates a worktree under `.worktrees/` from an explicit base and provisions it.
+- `bin/worktree install` writes the integration files other tools read: `.worktreeinclude` for Claude Code,
+  a `## Worktrees` block in `AGENTS.md`/`CLAUDE.md` for coding agents, and a herdr plugin.
+- `exec` and `verify` run commands with worktree-local Bundler and binstubs and check the recorded base.
+- `close` drops the worktree-local databases, removes the checkout and deletes its branch.
 
 ## Installation
 
@@ -22,126 +26,137 @@ group :development do
 end
 ```
 
-Run `bundle install`. A binstub will be automatically created at `bin/worktree`.
-When Rails loads in development, installation also adds `/.worktrees/` to the project's
-`.gitignore`. The manual installer does the same, including when the binstub already exists.
+Run `bundle install`. When Rails loads in development the gem installs `bin/worktree` and the
+integration files below. The same happens with `bin/worktree install` or `bundle exec rake worktree:install`
+(`--force` / `FORCE=1` also replaces an existing launcher).
 
-Manual binstub installation (if needed):
-```bash
-bundle exec rake worktree:install
-```
+| File | Purpose |
+| --- | --- |
+| `bin/worktree` | Launcher that pins `BUNDLE_GEMFILE` to its own checkout before Ruby starts |
+| `.gitignore` | Adds `/.worktrees/` |
+| `.worktree.yml` | Project configuration (written once with the defaults, then yours) |
+| `.worktreeinclude` | Generated from the `copy` list; Claude Code copies these files into every worktree it creates |
+| `AGENTS.md`, `CLAUDE.md` | A marked `## Worktrees` block that tells agents to run `bin/worktree init`; a symlinked pair is updated once |
+| `.worktree/herdr/` | A herdr plugin that runs `bin/worktree init --level minimal` on `worktree.created`; link it once with `herdr plugin link .worktree/herdr` |
 
-## Usage
+Commit `.worktree.yml`, `.worktreeinclude`, the agents block and `.worktree/herdr/`. They are project configuration.
 
-### Create a worktree
+## Configuration
 
-```bash
-git fetch origin
-bin/worktree feature-branch origin/main  # Explicit base required
+`.worktree.yml` in the repository root, all keys optional:
+
+```yaml
+level: full                      # default level for create and init
+copy:                            # gitignored files to copy from the main checkout (globs)
+  - .env
+  - .env.*
+  - config/database.yml
+  - config/master.key
+  - config/credentials/*.key
+  - Procfile.dev
+directories: [tmp/pids]          # created in every provisioned checkout
+touch: [tmp/caching-dev.txt]     # touched in every provisioned checkout
+node_modules: link               # link (symlink to the main checkout), copy or skip
+database:
+  development_variable: DATABASE_NAME   # written to .env.development.local
+  test_variable: DATABASE_NAME          # written to .env.test.local
+  template: true                        # clone the main development database (PostgreSQL TEMPLATE, SQLite copy)
+  template_max_gb: 5                    # larger source databases load the schema instead
+test_command: bin/agent-test-setup      # --level test runs this instead of creating a test database
 ```
 
-The base is required: omitting it fails before creating a branch or directory. The exact local
-commit resolved from that reference is recorded; creation does not fetch or change your base branch.
-Worktrees are created under `.worktrees/` in the repository root, including when invoked from a subdirectory.
+### Databases
 
-This creates a new worktree with:
-- Separate databases: `myapp_feature-branch_development` and `myapp_feature-branch_test`
-- Copied configuration files (`.env`, `database.yml`, `Procfile.dev`, credentials)
-- Copied `node_modules`
-- Migrated and seeded databases
+Before it touches a database, `init` asks Rails how `config/database.yml` resolves in the worktree and
+picks one of three paths:
 
-### Run commands in the worktree
+- **SQLite files inside the checkout** (the `rails new` default, `storage/development.sqlite3`): every
+  checkout already has its own files. `full` copies the main development database into the worktree
+  (subject to `template` and `template_max_gb`) and prepares the test database; `test` prepares only the
+  test database. No `.env.*.local` files are written and `close` simply removes them with the checkout.
+- **A database name read from the configured variable, with dotenv loaded**: the names go into
+  `.env.development.local` and `.env.test.local` and the databases are created as described below.
+- **Anything else**, such as a fresh `rails new -d postgresql` app with fixed names: `init` warns and
+  skips the database setup, so the checkout shares the main databases and nothing in them is changed.
 
-```bash
-cd .worktrees/feature-branch
-bin/worktree exec -- bundle exec rspec
-bin/worktree exec -- bin/rails db:migrate
-bin/worktree verify
-```
+To give PostgreSQL or MySQL worktrees their own databases, add `gem "dotenv-rails", groups: [:development, :test]`
+and read the name from the configured variable in `config/database.yml`:
 
-`exec` runs from the Git worktree root, including when called from a subdirectory. It checks the
-recorded branch and base ancestry, verifies Bundler's effective root in a fresh Ruby process, and
-pins `BUNDLE_GEMFILE` to this worktree. It clears inherited Bundler state and Git directory overrides,
-removes other repositories' `bin` directories from PATH, and puts this checkout's `bin` first.
-An explicit `bundle` command uses Bundler's gem executable rather than an inherited project binstub.
-Initialization commands use the same isolated environment.
+```yaml
+development:
+  <<: *default
+  database: <%= ENV.fetch("DATABASE_NAME", "myapp_development") %>
+test:
+  <<: *default
+  database: <%= ENV.fetch("DATABASE_NAME", "myapp_test") %>
+```
 
-Direct commands, `bundle exec` commands, and Ruby script invocations reject binstubs that resolve
-into another repository, including symlinks. Arguments are passed directly without shell expansion;
-command exit status is preserved. Use an explicit `sh -c` when shell syntax is intended. This wrapper
-is an execution-context guard, not a sandbox: it does not inspect shell scripts or prevent application
-code from spawning commands elsewhere. Commands run outside the wrapper are not intercepted.
+Database names are `<prefix>_<worktree>_development` and `<prefix>_<worktree>_test`. The prefix comes from
+`config/database.yml` in the main checkout, the worktree name from the directory, with other characters
+replaced by `_`. The names go into `.env.development.local` and `.env.test.local`, which dotenv loads per
+environment and which stay out of git. `database.yml` is copied unchanged. An application without
+`db/schema.rb` or `db/structure.sql` yet gets `db:migrate` instead of `db:schema:load`.
 
-Generated `bin/worktree` launchers are shell scripts that set `BUNDLE_GEMFILE` before starting Ruby,
-so an inherited `RUBYOPT=-rbundler/setup` cannot activate the previous checkout's bundle first.
-Both automatic installation and the Rake installer use the same generator. To replace an existing
-launcher in a project after updating the gem:
+## Usage
 
 ```bash
-bundle exec rake worktree:install FORCE=1
+git fetch origin
+bin/worktree create feature origin/main                 # full provisioning
+bin/worktree create spike origin/main --level minimal   # shares the main development database
+bin/worktree create feature origin/main --seed          # also run db:seed
+
+# In a checkout another tool created (herdr, claude --worktree, Codex, git worktree add)
+bin/worktree init                     # level from .worktree.yml
+bin/worktree init --level test        # plus the isolated test setup
+bin/worktree init --base origin/main  # also record the base and install the push guard
+bin/worktree init --force             # overwrite copied files with the main checkout's
+
+bin/worktree close feature            # from the main checkout, by directory or branch name
+bin/worktree close                    # from inside the worktree
 ```
 
-Creation replaces the new worktree's launcher with the current generator. Symlinked launchers
-are refused rather than followed. Existing worktrees without recorded metadata cannot use `exec`
-or `verify`; create a managed worktree from an explicit base to use these checks.
-
-### Verify before pushing
+The base for `create` is required and the resolved commit is recorded; creation does not fetch or change
+your base branch. If the template clone cannot run, because the main development database is in use or larger
+than `template_max_gb`, `init` creates the database and loads the schema instead and says so.
 
-Creation stores the base reference, its resolved commit, and the feature branch in the private
-`rails-worktree.json` file under `git rev-parse --git-dir`. It does not add this metadata to tracked
-project files. The recorded commit remains fixed even if the base reference advances.
+`close` drops only databases named in the worktree's `.env.development.local` and `.env.test.local`.
+A `minimal` checkout shares the main databases and they stay untouched.
 
-Creation also installs a pre-push wrapper at Git's configured hook location, including a custom
-`core.hooksPath`. An existing hook is preserved as `pre-push.before-rails-worktree` and runs after
-verification with the same arguments and input. Its exit status is preserved. Repeated installation
-is idempotent; an unexpected existing backup causes an actionable error instead of overwriting it.
-
-In managed worktrees the hook checks the branch, base ancestry, and bundle root, then prints the
-change summary against the recorded base. Non-deletion updates must push the current HEAD; push
-other branches from their own checkout. In checkouts without metadata, the wrapper only runs the
-previous hook. Git hooks are shared by worktrees unless configured otherwise.
-
-A branch mismatch tells you to switch back; a base mismatch tells you to rebase onto the recorded
-base. These checks cannot decide whether you chose the right base or whether a change belongs in
-the feature. Review the printed diff before publishing. Git's `--no-verify` still bypasses hooks.
-
-### Close a worktree
+## Verified execution
 
 ```bash
-bin/worktree --close feature-branch  # From main repo
-bin/worktree --close                 # From within worktree
+cd .worktrees/feature
+bin/worktree exec -- bundle exec rspec
+bin/worktree verify
 ```
 
-Drops both databases, removes the directory, deletes the branch, and cleans up git references.
-
-## Database Configuration
+`exec` runs from the worktree root with `BUNDLE_GEMFILE` pinned to this checkout, clears inherited Bundler
+state and Git directory overrides, removes other repositories' `bin` directories from PATH and puts this
+checkout's `bin` first. It rejects binstubs that resolve into another repository. It needs the metadata
+that `create` or `init --base` records in the private `rails-worktree.json` under `git rev-parse --git-dir`;
+checkouts without it skip the guard.
 
-The gem uses environment variables for database names:
+`create` and `init --base` also install a pre-push wrapper at Git's configured hook location. An existing
+hook is preserved as `pre-push.before-rails-worktree` and runs after verification. In managed worktrees the
+hook checks the branch, base ancestry and bundle root, then prints the change summary against the recorded
+base. Git's `--no-verify` still bypasses hooks.
 
-- `DATABASE_NAME_DEVELOPMENT` - Development database name
-- `DATABASE_NAME_TEST` - Test database name
+If `core.hooksPath` points at a directory that Git tracks (for example `script/hooks`), the gem does not
+write there and prints a warning instead. Call the check from your own pre-push hook:
 
-Your `config/database.yml` should look like:
-
-```yaml
-development:
-  <<: *default
-  database: <%= ENV.fetch("DATABASE_NAME_DEVELOPMENT", "myapp_development") %>
-test:
-  <<: *default
-  database: <%= ENV.fetch("DATABASE_NAME_TEST", "myapp_test") %>
+```sh
+bin/worktree verify --push || exit 1
 ```
 
-The gem automatically:
-1. Sets these variables in the worktree's `.env` file
-2. Updates the worktree's `database.yml` to use them
-3. Creates both development and test databases with unique names
+It reads the pushed refs from standard input and does nothing in checkouts without worktree metadata.
 
 ## Requirements
 
-- Ruby >= 2.6.0
-- Rails project with standard structure
-- PostgreSQL (or modify for your database)
+- Ruby >= 3.0
+- Rails project with `bin/rails`
+- For own databases: SQLite files in the checkout, or dotenv and a `database.yml` that reads the configured
+  variable (see Databases)
+- PostgreSQL for template cloning; other server databases fall back to `db:create` and `db:schema:load`
 
 ## License
 

data/lib/rails-worktree.rb

@@ -3,6 +3,8 @@ module RailsWorktree
 end
 
 require_relative "worktree/version"
+require_relative "worktree/config"
+require_relative "worktree/managed_block"
 require_relative "worktree/context"
 require_relative "worktree/launcher"
 require_relative "worktree/installer"

data/lib/worktree/cli.rb

@@ -1,5 +1,37 @@
 module RailsWorktree
   class CLI
+    USAGE = <<~USAGE.freeze
+      Usage: worktree create <name> <base> [--level LEVEL] [--seed]
+             worktree <name> <base> [--level LEVEL] [--seed]
+             worktree init [name] [--level LEVEL] [--seed] [--base REF] [--force]
+             worktree close [name]
+             worktree exec -- <command> [arguments]
+             worktree verify [--push]
+             worktree install [--force]
+
+      Commands:
+        create NAME BASE    Create .worktrees/NAME from BASE and provision it
+        init [NAME]         Provision the current checkout, whoever created it (safe to repeat)
+        close [NAME]        Drop the worktree-local databases, remove the checkout and its branch
+        exec -- COMMAND     Run a command with verified worktree context
+        verify              Check the recorded base and bundle root
+        install             Write bin/worktree, .worktree.yml, .worktreeinclude, the AGENTS.md block
+                            and the herdr plugin into this repository
+
+      Options:
+        --level LEVEL       minimal (config files), test (plus test setup) or full (plus own databases).
+                            Default: the level in .worktree.yml, or full
+        --seed              Seed the development database (full level)
+        --base REF          Record REF as the base and install the push guard (init)
+        --force             Overwrite copied files (init) or the launcher and plugin files (install)
+
+      Examples:
+        worktree create feature origin/main
+        worktree create spike origin/main --level minimal
+        worktree init --level minimal          # inside a herdr, Claude Code or Codex checkout
+        worktree close feature
+    USAGE
+
     def self.run(args)
       new(args).run
     end
@@ -9,33 +41,33 @@ module RailsWorktree
     end
 
     def run
-      if @args.empty?
-        print_usage
-        exit 1
-      end
-
-      case @args.first
+      command = @args.shift
+      case command
+      when nil, "--help", "-h", "help"
+        puts USAGE
+        exit 1 if command.nil?
       when "exec"
-        return Commands::Exec.new(@args.drop(1)).run
+        Commands::Exec.new(@args).run
       when "verify"
-        return Context.new.verify(push: @args.include?("--push"))
-      end
-
-      # Extract flags
-      @skip_seeds = @args.delete("--skip-seeds")
-
-      case @args[0]
-      when "--close", "close"
-        @args.shift
-        Commands::Close.new(@args).run
-      when "--init", "init"
-        @args.shift
-        Commands::Init.new(@args, skip_seeds: @skip_seeds).run
-      when "--help", "-h", "help"
-        print_usage
+        Context.new.verify(push: @args.include?("--push"))
+      when "install"
+        positional, options = parse_options
+        raise Error, "install takes no arguments" unless positional.empty?
+        Installer.install(Context.new.root, replace: options[:force], quiet: false)
+        puts "✓ rails-worktree is installed. Link the herdr plugin once with: herdr plugin link #{Installer::HERDR_DIR}"
+      when "create"
+        positional, options = parse_options
+        Commands::Create.new(positional, level: options[:level], seed: options[:seed]).run
+      when "init", "--init"
+        positional, options = parse_options
+        Commands::Init.new(positional, level: options[:level], seed: options[:seed], base: options[:base], force: options[:force]).run
+      when "close", "--close"
+        positional, _options = parse_options
+        Commands::Close.new(positional).run
       else
-        # Default: create worktree
-        Commands::Create.new(@args, skip_seeds: @skip_seeds).run
+        @args.unshift(command)
+        positional, options = parse_options
+        Commands::Create.new(positional, level: options[:level], seed: options[:seed]).run
       end
     rescue Error => error
       warn "Error: #{error.message}"
@@ -44,37 +76,26 @@ module RailsWorktree
 
     private
 
-    def print_usage
-      puts <<~USAGE
-        Usage: worktree <name> <base-branch> [options]
-               worktree --close [worktree-name]
-               worktree exec -- <command> [arguments]
-               worktree verify [--push]
-               worktree --init <worktree-name> [options]
-
-        Creates a new git worktree and initializes it with configuration
-
-        Commands:
-          <name>              Create a new worktree with the given name
-          exec -- COMMAND     Run a command with verified worktree context
-          verify              Check the recorded base and bundle root
-          --close [name]      Close and remove a worktree
-          --init <name>       Initialize a worktree (usually called automatically)
-          --help, -h          Show this help message
-
-        Options:
-          --skip-seeds        Skip database seeding during initialization
-
-        Arguments:
-          <name>              Name of the worktree (required)
-          <base-branch>       Explicit branch or commit to create worktree from (required)
-
-        Examples:
-          worktree feature-branch origin/main      # Create from an explicit base
-          worktree feature-branch origin/main --skip-seeds     # Create without seeding database
-          worktree --close feature-branch          # Close worktree from main repo
-          worktree --close                         # Close worktree from within it
-      USAGE
+    def parse_options
+      positional = []
+      options = {seed: false, force: false}
+      until @args.empty?
+        argument = @args.shift
+        case argument
+        when "--seed" then options[:seed] = true
+        when "--skip-seeds" then options[:seed] = false
+        when "--force" then options[:force] = true
+        when /\A--(level|base)(?:=(.*))?\z/
+          value = Regexp.last_match(2) || @args.shift
+          raise Error, "#{argument} needs a value" if value.nil? || value.start_with?("--")
+          options[Regexp.last_match(1).to_sym] = value
+        when /\A--/
+          raise Error, "Unknown option #{argument}"
+        else
+          positional << argument
+        end
+      end
+      [positional, options]
     end
   end
 end

data/lib/worktree/clone_database.rb

@@ -0,0 +1,23 @@
+# Runs inside `bin/rails runner` in the worktree, without the worktree database
+# override, so the configured development database is the main checkout's.
+# Usage: bin/rails runner clone_database.rb TARGET
+# RAILS_WORKTREE_TEMPLATE_MAX_BYTES caps the source size; a larger database is not cloned.
+target = ARGV.fetch(0)
+max_bytes = ENV.fetch("RAILS_WORKTREE_TEMPLATE_MAX_BYTES", "0").to_i
+config = ActiveRecord::Base.connection_db_config.configuration_hash
+source = config[:database]
+abort "Template cloning needs PostgreSQL (adapter #{config[:adapter]})." unless config[:adapter].to_s.include?("postg")
+abort "Source and target databases are the same: #{source}" if source == target
+
+ActiveRecord::Base.establish_connection(config.merge(database: "postgres"))
+connection = ActiveRecord::Base.connection
+if connection.select_value("SELECT 1 FROM pg_database WHERE datname = #{connection.quote(target)}")
+  puts "Database #{target} already exists"
+else
+  size = connection.select_value("SELECT pg_database_size(#{connection.quote(source)})").to_i
+  if max_bytes.positive? && size > max_bytes
+    abort format("Source database %s is %.1f GB, above database.template_max_gb in .worktree.yml; not cloning.", source, size / 1024.0**3)
+  end
+  connection.execute("CREATE DATABASE #{connection.quote_table_name(target)} TEMPLATE #{connection.quote_table_name(source)}")
+  puts "Cloned #{source} into #{target}"
+end