wtr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95f22dbf8fd43c6bbab7163b62aca82e614ec28e76a0756703887ef996c6c228
+  data.tar.gz: e1bb5116ced20e3b42f2d9dec7d17140084f3428d83d55fdf7524c73d4d8228a
+SHA512:
+  metadata.gz: aa83072d28ccdf3eb89046b09ee1364e5f2daecb3e65ac5c39c21564a01a3e8c3e774b68c63e06057ebb0b3bbc38b2d33eb36878367515fed8517b55ebf82b5a
+  data.tar.gz: 7bbb0e7452bad31d39e2c853be913d305fb443406acfe23c025c98f281e87fd9476394b1bb2ca71af9ff158f463ad8f6c35b38b28d876817a3096d7f20cf3e60

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-20
+
+- Initial release: port of wt (Crystal) to Ruby, with `cd`, `new`, `rm [-b]`, `ls [-l]` and zsh integration

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"wtr" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["arzezak@gmail.com"](mailto:"arzezak@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ariel Rzezak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+# 🌳💻 wtr
+
+A small Ruby CLI for managing git worktrees. A port of [wt](https://github.com/arzezak/wt) from Crystal to Ruby.
+
+## Who this is for
+
+wtr is for people who want to create, switch between, and remove worktrees by hand from the terminal, and keep an eye on what exists. If you want manual control over your worktrees rather than delegating that to automation, wtr is for you.
+
+## Install
+
+```sh
+gem install wtr
+```
+
+Add to your `.zshrc`:
+
+```sh
+eval "$(command wtr init zsh)"
+```
+
+Reload your shell (`exec zsh`) and you're set.
+
+## Usage
+
+Switch to a worktree (exact or unique-prefix match, tab-completes):
+
+```sh
+wtr [name]
+wtr cd <name>
+wtr cd main    # back to the main worktree (also matches the main branch name)
+wtr cd -       # back to the previous worktree
+```
+
+Create a worktree, optionally from a base ref:
+
+```sh
+wtr new <branch> [base]
+```
+
+When the branch exists, `wtr new` checks it out into a new worktree. When the branch is new, it creates it from `[base]`, or from the current `HEAD` if no base is provided. Either way, it switches into the worktree when it finishes.
+
+Remove a worktree (branch preserved):
+
+```sh
+wtr rm [name]
+```
+
+Pass `-b`/`--branch` to also delete the worktree's branch. This force-deletes it, so it works even when the branch isn't merged:
+
+```sh
+wtr rm [name] -b
+```
+
+List worktrees (`-l`/`--long` adds the HEAD sha):
+
+```sh
+wtr ls
+```
+
+Other commands:
+
+```sh
+wtr help
+wtr --version
+```
+
+### Resolution
+
+When you pass a name, `wtr` resolves it directly: exact match first, then unique prefix, then error with candidates.
+
+When you omit the name, `wtr` lists the available worktrees. `wtr cd main` returns to the main worktree, and `wtr cd -` returns to the worktree you came from.
+
+### Tab completion
+
+Tab completion is set up automatically by `wtr init zsh`. It completes:
+
+- `wtr cd <tab>` / `wtr rm <tab>`: worktree names
+- `wtr new <tab>`: branch names
+- `wtr new <branch> <tab>`: branch/ref names for the base
+
+## Configuration
+
+Per-repo `.wtr.yml` (committed, shared with the team) with an optional `.wtr.local.yml` override (gitignored, personal). Global defaults in `~/.config/wtr/config.yml`. Merge order: global, repo, local.
+
+```yaml
+copy:
+  - .env
+  - .env.local
+  - config/master.key
+
+after_create:
+  - bundle install
+  - yarn install
+```
+
+### `copy`
+
+Files to copy from the main worktree into the new one. These are typically gitignored, so they don't come across with the checkout. Missing sources are skipped with a warning.
+
+### `after_create`
+
+Commands run in the new worktree's directory, in order, streaming output. Stops on first non-zero exit. The worktree is already created, so it stays in place for you to fix manually.
+
+Each command is announced on stderr with a 🌳 prefix (as are `copy` files) so it's easy to tell wtr's own output apart from the command's.
+
+Each command runs with `WTR_WORKTREE_NAME` set to the worktree's directory name (e.g. `feature-foo`), useful for isolating per-worktree resources like a database name.
+
+For example, giving each worktree its own Rails development/test database:
+
+```yaml
+after_create:
+  - |
+    cat > .env.local << ENV
+    DB_DATABASE=${WTR_WORKTREE_NAME}_development
+    DB_TEST_DATABASE=${WTR_WORKTREE_NAME}_test
+    ENV
+  - bundle install
+  - yarn install
+  - bin/rails db:create db:schema:load
+```
+
+### `--no-hooks`
+
+Skip all copy and after_create steps on `wtr new`.
+
+### Trust model
+
+`.wtr.yml` can be committed to a repo, and `after_create` runs arbitrary shell commands. This is the same trust model as Makefiles and npm scripts: review `.wtr.yml` before running `wtr new` in an untrusted repo, or pass `--no-hooks`.
+
+## Shell integration
+
+### The cd problem
+
+A program can't `cd` your shell (it's a child process). So `wtr` is an **executable + thin shim**, like zoxide or rbenv:
+
+- The **executable** holds all logic (resolve paths, create/remove worktrees, format output).
+- A tiny **shell function** calls the executable and `eval`s its stdout for navigation commands.
+
+Both are named `wtr`. The function shadows the executable for interactive use and delegates with `command wtr` (which bypasses functions and runs the executable on PATH).
+
+### Stdout protocol
+
+The executable emits two kinds of output on stdout:
+
+1. **Directives** the shim `eval`s (e.g. `cd <path>`)
+2. **Plain text** the shim prints as-is (ls, help, messages)
+
+Errors and human messages go to stderr so they never get `eval`d and hook output (bundle install, etc.) streams live.
+
+## Worktree conventions
+
+- Worktrees live in `<repo>/.worktrees/<branch>`.
+- `/` in branch names becomes `-` for the directory (`feature/foo` becomes `.worktrees/feature-foo`).
+- `.worktrees/` is added to `.git/info/exclude` (local-only, never the committed `.gitignore`).
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake   # tests + standard
+```
+
+The unit tests exercise the library directly; the command tests drive `exe/wtr` in throwaway git repos. Point `WTR_BIN` at another executable to run them against it instead.
+
+The code sticks to the Ruby subset supported by [Spinel](https://github.com/matz/spinel), Matz's ahead-of-time compiler, so it can also be compiled to a native binary. Keep new code inside that subset.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/exe/wtr

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative "../lib/wtr"
+
+Wtr::CLI.new.run(ARGV.dup)

data/lib/wtr/cli.rb

@@ -0,0 +1,110 @@
+module Wtr
+  class CLI
+    HELP = <<~HELP
+      wtr — git worktrees
+
+      USAGE
+        wtr [cd] [name]          switch to a worktree (resolve by name, tab-completes)
+        wtr new <branch> [base]  create/checkout a worktree, cd into it
+        wtr rm [name] [-b]       remove a worktree (-b/--branch also deletes its branch)
+        wtr ls [-l]              list all worktrees (-l/--long adds the HEAD sha)
+        wtr help                 this text
+
+      WHERE
+        worktrees live in <repo>/.worktrees/<branch> (auto git-ignored; slashes become dashes)
+
+      cd
+        bare "wtr" is "wtr cd". with a name, resolves by exact match then unique prefix.
+        with no name, lists available worktrees.
+        "wtr cd main" returns to the main worktree (also matches the main branch name).
+        "wtr cd -" returns to the previous worktree.
+        errors out if the repo only has one worktree (nothing to switch to).
+
+      new
+        branch exists: checks it out into the new worktree
+        branch is new: creates it from <base> (default: current HEAD)
+        then cd into the worktree.
+        note: git refuses a branch already checked out elsewhere (e.g. main).
+        pass --no-hooks to skip copy + after_create steps.
+
+      rm
+        removes the picked worktree but preserves its branch.
+        refuses the main worktree; git refuses if there are uncommitted changes.
+        pass -b/--branch to also delete the branch (force-deletes, even if unmerged).
+    HELP
+
+    def initialize
+      @worktrees = nil
+    end
+
+    def run(args)
+      dispatch(args).render($stdout)
+    rescue => e
+      Log.puts(e.message)
+      exit 1
+    end
+
+    private
+
+    def dispatch(args)
+      subcommand = args.empty? ? "cd" : args.shift
+
+      case subcommand
+      when "help", "-h", "--help"
+        Result.print(HELP)
+      when "--version", "-v"
+        Result.print("wtr #{VERSION}")
+      when "init"
+        Completion.init_script(args.first || "zsh")
+      when "cd"
+        Commands::Cd.new(worktrees).run(args.first)
+      when "new"
+        dispatch_new(args)
+      when "rm"
+        dispatch_rm(args)
+      when "ls", "list"
+        dispatch_ls(args)
+      when "__complete"
+        Completion.new(worktrees).complete(args.first || "subcommands")
+      else
+        raise "unknown subcommand '#{subcommand}'\n#{HELP}"
+      end
+    end
+
+    def dispatch_ls(args)
+      long = flag?(args, "-l", "--long")
+      reject_unknown_flags(args, "ls")
+
+      Commands::Ls.new(worktrees).run(long: long)
+    end
+
+    def dispatch_rm(args)
+      delete_branch = flag?(args, "-b", "--branch")
+      reject_unknown_flags(args, "rm")
+
+      Commands::Rm.new(worktrees).run(args.first, delete_branch: delete_branch)
+    end
+
+    def dispatch_new(args)
+      hooks = !flag?(args, "--no-hooks")
+      branch = args.shift
+      base = args.shift
+      raise "usage: wtr new <branch> [base] [--no-hooks]" unless branch
+
+      Commands::New.new(worktrees).run(branch, base, hooks: hooks)
+    end
+
+    def flag?(args, *names)
+      names.map { |name| args.delete(name) }.compact.any? # Spinel: matz/spinel#9883
+    end
+
+    def reject_unknown_flags(args, subcommand)
+      unknown = args.find { |arg| arg.start_with?("-") }
+      raise "unknown flag '#{unknown}' for #{subcommand}" if unknown
+    end
+
+    def worktrees
+      @worktrees ||= Worktrees.new
+    end
+  end
+end

data/lib/wtr/commands/cd.rb

@@ -0,0 +1,39 @@
+module Wtr
+  module Commands
+    class Cd
+      def initialize(worktrees)
+        @worktrees = worktrees
+      end
+
+      def run(query = nil)
+        return cd_previous if query == "-"
+
+        Result.cd(@worktrees.find(query, main_alias: true).path)
+      rescue Worktrees::NothingToPick
+        Log.puts "only one worktree here, use 'wtr new <branch>' to create another"
+        Result.none
+      rescue Worktrees::NameRequired => e
+        Log.puts e.message
+        Result.none
+      end
+
+      private
+
+      def cd_previous
+        previous = ENV["WTR_PREV"]
+
+        if previous.nil? || previous.strip.empty?
+          Log.puts "no previous worktree"
+          return Result.none
+        end
+
+        unless Dir.exist?(previous)
+          Log.puts "previous worktree is gone: #{previous}"
+          return Result.none
+        end
+
+        Result.cd(previous)
+      end
+    end
+  end
+end

data/lib/wtr/commands/ls.rb

@@ -0,0 +1,56 @@
+module Wtr
+  module Commands
+    class Ls
+      def initialize(worktrees)
+        @worktrees = worktrees
+      end
+
+      def run(long: false)
+        worktrees = @worktrees.all
+        return Result.print("no worktrees") if worktrees.empty?
+
+        rows = [header(long)] + worktrees.map { |worktree| row_for(worktree, long) }
+        Result.print(render_table(rows))
+      end
+
+      private
+
+      def header(long)
+        long ? ["BRANCH", "HEAD", "PATH"] : ["BRANCH", "PATH"]
+      end
+
+      def row_for(worktree, long)
+        columns = [branch_label(worktree)]
+        columns << worktree.short_head if long
+        columns << tilde(worktree.path)
+        columns
+      end
+
+      def render_table(rows)
+        widths = column_widths(rows)
+        lines = rows.map do |row|
+          cells = []
+          row.each_with_index do |cell, i|
+            cells << ((i < widths.size) ? cell.ljust(widths[i]) : cell)
+          end
+          cells.join("  ")
+        end
+        lines.join("\n")
+      end
+
+      def column_widths(rows)
+        (0...rows.first.size - 1).map { |i| rows.map { |row| row[i].size }.max }
+      end
+
+      def tilde(path)
+        home = Dir.home
+        path.start_with?(home) ? "~#{path[home.size..-1]}" : path # standard:disable Style/SlicingWithRange -- Spinel
+      end
+
+      def branch_label(worktree)
+        label = worktree.branch || "(detached)"
+        worktree.main? ? "#{label} *" : label
+      end
+    end
+  end
+end

data/lib/wtr/commands/new.rb

@@ -0,0 +1,81 @@
+require "fileutils"
+
+module Wtr
+  module Commands
+    class New
+      def initialize(worktrees)
+        @worktrees = worktrees
+      end
+
+      def run(branch, base = nil, hooks: true)
+        added = @worktrees.create(branch, base: base)
+
+        if added.existed
+          Log.puts "worktree already exists at #{added.path}"
+        elsif hooks
+          run_hooks(@worktrees.main.path, added.path)
+        end
+
+        Result.cd(added.path)
+      end
+
+      private
+
+      def run_hooks(main_path, worktree_path)
+        config = Config.load(main_path)
+        copy_files(config, main_path, worktree_path)
+        run_after_create(config, worktree_path)
+      end
+
+      def copy_files(config, main_path, worktree_path)
+        main_root = File.realpath(main_path)
+        worktree_root = File.realpath(worktree_path)
+
+        config.copy.each do |relative_path|
+          source = File.expand_path(relative_path, main_path)
+          destination = File.expand_path(relative_path, worktree_path)
+          unless File.exist?(source)
+            Log.puts "copy: skipping #{relative_path} (not found in main worktree)"
+            next
+          end
+          unless within?(File.realpath(source), main_root) && within?(existing_ancestor(destination), worktree_root)
+            Log.puts "copy: skipping #{relative_path} (path escapes repo)"
+            next
+          end
+          if File.symlink?(destination)
+            Log.puts "copy: skipping #{relative_path} (destination is a symlink)"
+            next
+          end
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(source, destination)
+          Log.step("copy", relative_path)
+        end
+      end
+
+      def within?(path, root)
+        path == root || path.start_with?(root + "/")
+      end
+
+      def existing_ancestor(path)
+        dir = File.dirname(path)
+        dir = File.dirname(dir) until File.exist?(dir)
+        File.realpath(dir)
+      end
+
+      def run_after_create(config, worktree_path)
+        env = {"WTR_WORKTREE_NAME" => File.basename(worktree_path)}
+
+        config.after_create.each do |command|
+          Log.step("run", command)
+          pid = Process.spawn(env, "sh", "-c", command, chdir: worktree_path, out: $stderr, err: $stderr)
+          Process.wait(pid)
+          status = $?
+          unless status.success?
+            Log.puts "after_create failed: #{command} (exit #{status.exitstatus})"
+            break
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wtr/commands/rm.rb

@@ -0,0 +1,44 @@
+module Wtr
+  module Commands
+    class Rm
+      def initialize(worktrees)
+        @worktrees = worktrees
+      end
+
+      def run(query = nil, delete_branch: false)
+        worktree = @worktrees.find(query)
+        inside = worktree.contains?(Dir.pwd)
+        return Result.none if inside && !confirm_removal?(worktree)
+
+        deleted = @worktrees.remove(worktree, delete_branch: delete_branch)
+        Log.puts removal_message(worktree, delete_branch, deleted)
+
+        inside ? Result.cd(@worktrees.main.path) : Result.none
+      rescue Worktrees::NothingToPick
+        Log.puts "no worktrees to remove"
+        Result.none
+      rescue Worktrees::NameRequired => e
+        Log.puts e.message
+        Result.none
+      end
+
+      private
+
+      def removal_message(worktree, delete_branch, deleted)
+        if deleted
+          "removed #{worktree.name} and deleted branch #{deleted}"
+        elsif delete_branch
+          "removed #{worktree.name} (detached HEAD, no branch to delete)"
+        else
+          "removed #{worktree.name} (branch preserved)"
+        end
+      end
+
+      def confirm_removal?(worktree)
+        Log.print "you're inside #{worktree.name}, remove and cd to main? [y/n] "
+        answer = $stdin.gets
+        !answer.nil? && answer.strip.downcase == "y"
+      end
+    end
+  end
+end

data/lib/wtr/completion.rb

@@ -0,0 +1,90 @@
+module Wtr
+  class Completion
+    def initialize(worktrees)
+      @worktrees = worktrees
+    end
+
+    def complete(kind)
+      candidates = case kind
+      when "worktrees"
+        @worktrees.names
+      when "cd_targets"
+        @worktrees.names(main_alias: true)
+      when "branches"
+        @worktrees.branches
+      when "refs"
+        @worktrees.refs
+      when "subcommands"
+        ["cd", "new", "rm", "ls", "help"]
+      else
+        []
+      end
+      Result.print(candidates.join("\n"))
+    end
+
+    def self.init_script(shell)
+      case shell
+      when "zsh"
+        Result.print(ZSH_INIT_SCRIPT)
+      else
+        Log.puts "unsupported shell '#{shell}' (available: zsh)"
+        Result.none
+      end
+    end
+
+    ZSH_INIT_SCRIPT = <<~'ZSH'
+      wtr() {
+        local output
+        output=$(command wtr "$@") || return
+
+        if [[ "$output" == cd\ * ]]; then
+          export WTR_PREV="$PWD"
+          eval "$output"
+        elif [[ -n "$output" ]]; then
+          print -r -- "$output"
+        fi
+      }
+
+      _wtr() {
+        local -a subcommands=(
+          'cd:switch to a worktree'
+          'new:create a worktree'
+          'rm:remove a worktree'
+          'ls:list worktrees'
+          'help:show help'
+        )
+
+        if (( CURRENT == 2 )); then
+          _describe 'subcommand' subcommands
+          return
+        fi
+
+        case "${words[2]}" in
+          cd)
+            local -a worktrees
+            worktrees=(${(f)"$(command wtr __complete cd_targets)"})
+            _describe 'worktree' worktrees
+            ;;
+          rm)
+            local -a worktrees
+            worktrees=(${(f)"$(command wtr __complete worktrees)"})
+            _describe 'worktree' worktrees
+            ;;
+          new)
+            if (( CURRENT == 3 )); then
+              local -a branches
+              branches=(${(f)"$(command wtr __complete branches)"})
+              _describe 'branch' branches
+            elif (( CURRENT == 4 )); then
+              local -a refs
+              refs=(${(f)"$(command wtr __complete refs)"})
+              _describe 'ref' refs
+            fi
+            ;;
+        esac
+      }
+
+      compdef _wtr wtr
+    ZSH
+  end
+end

data/lib/wtr/config.rb

@@ -0,0 +1,56 @@
+require "yaml"
+
+module Wtr
+  class Config
+    attr_reader :copy, :after_create
+
+    def initialize(copy: [], after_create: [])
+      @copy = copy
+      @after_create = after_create
+    end
+
+    def self.load(main_repo_path)
+      global = load_file(global_path)
+      repo = load_file(File.join(main_repo_path, ".wtr.yml"))
+      local = load_file(File.join(main_repo_path, ".wtr.local.yml"))
+      merge([global, repo, local])
+    end
+
+    def self.global_path
+      config_home = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config")
+      File.join(config_home, "wtr", "config.yml")
+    end
+
+    def self.load_file(path)
+      return Config.new unless File.exist?(path)
+
+      parse(File.read(path))
+    rescue Psych::SyntaxError => e
+      Log.puts "failed to parse #{path}: #{e.message}"
+      Config.new
+    end
+
+    def self.parse(content)
+      yaml = YAML.safe_load(content)
+      yaml = {} unless yaml.is_a?(Hash)
+      Config.new(copy: string_array(yaml, "copy"), after_create: string_array(yaml, "after_create"))
+    end
+
+    def self.string_array(yaml, key)
+      node = yaml[key]
+      return [] unless node.is_a?(Array) && node.all? { |item| item.is_a?(String) }
+
+      node
+    end
+
+    def self.merge(configs)
+      copy = []
+      after_create = []
+      configs.each do |config|
+        copy = config.copy unless config.copy.empty?
+        after_create = config.after_create unless config.after_create.empty?
+      end
+      Config.new(copy: copy, after_create: after_create)
+    end
+  end
+end

data/lib/wtr/log.rb

@@ -0,0 +1,15 @@
+module Wtr
+  module Log
+    def self.puts(message)
+      warn message
+    end
+
+    def self.print(message)
+      $stderr.print message
+    end
+
+    def self.step(label, subject)
+      warn "🌳 #{label}: #{subject}"
+    end
+  end
+end

data/lib/wtr/result.rb

@@ -0,0 +1,35 @@
+module Wtr
+  class Result
+    def initialize(cd_path: nil, stdout: nil)
+      @cd_path = cd_path
+      @stdout = stdout
+    end
+
+    def self.cd(path)
+      new(cd_path: path)
+    end
+
+    def self.print(text)
+      new(stdout: text)
+    end
+
+    def self.none
+      new
+    end
+
+    def render(io)
+      if @cd_path
+        io.puts "cd #{Result.shell_quote(@cd_path)}"
+      elsif @stdout
+        io.puts @stdout
+      end
+    end
+
+    def self.shell_quote(arg)
+      return "''" if arg.empty?
+      return arg unless arg.match?(/[^a-zA-Z0-9%+,\-.\/:=@_]/)
+
+      "'" + arg.gsub("'", %('"'"')) + "'"
+    end
+  end
+end

data/lib/wtr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wtr
+  VERSION = "0.1.0"
+end

data/lib/wtr/worktrees.rb

@@ -0,0 +1,190 @@
+require "fileutils"
+require "open3"
+
+module Wtr
+  class Worktrees
+    Worktree = Data.define(:path, :head, :branch, :main) do
+      def main?
+        main
+      end
+
+      def name
+        File.basename(path)
+      end
+
+      def short_head
+        head[0, 7]
+      end
+
+      def contains?(dir)
+        dir == path || dir.start_with?(path + "/")
+      end
+    end
+
+    Added = Data.define(:path, :existed)
+
+    DIRECTORY = ".worktrees"
+
+    class Error < StandardError; end
+
+    class GitError < Error; end
+
+    class NothingToPick < Error; end
+
+    class NameRequired < Error
+      def initialize(names)
+        super("pass a name (tab-completes): #{names.join(", ")}")
+      end
+    end
+
+    class Ambiguous < Error; end
+
+    class NotFound < Error; end
+
+    def self.resolve(query, candidates)
+      raise NothingToPick if candidates.empty?
+
+      names = candidates.map(&:name)
+      raise NameRequired.new(names) if query.nil? || query.strip.empty?
+
+      exact = candidates.find { |worktree| worktree.name == query }
+      return exact if exact
+
+      matches = candidates.select { |worktree| worktree.name.start_with?(query) }
+      return matches.first if matches.size == 1
+
+      if matches.size > 1
+        raise Ambiguous, "ambiguous name '#{query}', matches: #{matches.map(&:name).join(", ")}"
+      end
+
+      raise NotFound, "no worktree matching '#{query}' (available: #{names.join(", ")})"
+    end
+
+    def initialize
+      @all = nil
+      @main = nil
+    end
+
+    def all
+      @all ||= parse_list(git("worktree", "list", "--porcelain"))
+    end
+
+    def main
+      @main ||= all.find(&:main?) || raise(Error, "cannot find the main worktree")
+    end
+
+    def names(main_alias: false)
+      names = others.map(&:name)
+      main_alias ? names + ["main"] : names
+    end
+
+    def find(query, main_alias: false)
+      return main if main_alias && main_query?(query)
+
+      Worktrees.resolve(query, others)
+    end
+
+    def create(branch, base: nil)
+      root = File.join(main.path, DIRECTORY)
+      path = File.join(root, branch.tr("/", "-"))
+      return Added.new(path: path, existed: true) if Dir.exist?(path)
+
+      FileUtils.mkdir_p(root)
+      ensure_ignored
+      if branch_exists?(branch)
+        git("worktree", "add", path, branch)
+      else
+        args = ["worktree", "add", "-b", branch, path]
+        args << base if base
+        git(*args)
+      end
+      @all = nil
+      Added.new(path: path, existed: false)
+    end
+
+    def remove(worktree, delete_branch: false)
+      raise Error, "refusing to remove the main worktree" if worktree.main?
+
+      main_path = main.path
+      git("worktree", "remove", worktree.path)
+      @all = nil
+      return nil unless delete_branch && worktree.branch
+
+      # Run from the main repo: the removed worktree may have been the cwd.
+      git("-C", main_path, "branch", "-D", worktree.branch)
+      worktree.branch
+    end
+
+    def branches
+      lines(git("branch", "--format=%(refname:short)"))
+    end
+
+    def refs
+      lines(git("for-each-ref", "--format=%(refname:short)", "refs/heads/", "refs/tags/", "refs/remotes/"))
+    end
+
+    private
+
+    def others
+      all.reject(&:main?)
+    end
+
+    def main_query?(query)
+      query == "main" || (!query.nil? && query == main.branch)
+    end
+
+    def ensure_ignored
+      marker = "#{DIRECTORY}/"
+      exclude_file = git("rev-parse", "--path-format=absolute", "--git-path", "info/exclude")
+      return if File.exist?(exclude_file) && File.read(exclude_file).lines.any? { |line| line.strip == marker }
+
+      FileUtils.mkdir_p(File.dirname(exclude_file))
+      File.open(exclude_file, "a") { |file| file.puts marker }
+    end
+
+    def branch_exists?(branch)
+      system("git", "show-ref", "--verify", "--quiet", "refs/heads/#{branch}") == true
+    end
+
+    def git(*args)
+      stdout, stderr, status = Open3.capture3("git", *args)
+      raise GitError, (stderr.strip.empty? ? "git command failed" : stderr.strip) unless status.success?
+
+      stdout.strip
+    end
+
+    def lines(output)
+      output.split("\n").reject(&:empty?)
+    end
+
+    def parse_list(output)
+      worktrees = []
+      output.split("\n\n").each do |stanza|
+        # git lists the main worktree first.
+        worktree = parse_stanza(stanza, main: worktrees.empty?)
+        worktrees << worktree if worktree
+      end
+      worktrees
+    end
+
+    def parse_stanza(stanza, main:)
+      path = ""
+      head = ""
+      branch = nil
+
+      stanza.each_line do |raw|
+        line = raw.chomp
+        if line.start_with?("worktree ")
+          path = line.delete_prefix("worktree ")
+        elsif line.start_with?("HEAD ")
+          head = line.delete_prefix("HEAD ")
+        elsif line.start_with?("branch ")
+          branch = line.delete_prefix("branch refs/heads/")
+        end
+      end
+      return nil if path.empty?
+
+      Worktree.new(path: path, head: head, branch: branch, main: main)
+    end
+  end
+end

data/lib/wtr.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "wtr/version"
+require_relative "wtr/log"
+require_relative "wtr/result"
+require_relative "wtr/worktrees"
+require_relative "wtr/config"
+require_relative "wtr/completion"
+require_relative "wtr/commands/cd"
+require_relative "wtr/commands/ls"
+require_relative "wtr/commands/new"
+require_relative "wtr/commands/rm"
+require_relative "wtr/cli"

data/sig/wtr.rbs

@@ -0,0 +1,3 @@
+module Wtr
+  VERSION: String
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: wtr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ariel Rzezak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Create, switch between, and remove git worktrees from the terminal, with
+  a zsh wrapper that cds into them.
+email:
+- arzezak@gmail.com
+executables:
+- wtr
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/wtr
+- lib/wtr.rb
+- lib/wtr/cli.rb
+- lib/wtr/commands/cd.rb
+- lib/wtr/commands/ls.rb
+- lib/wtr/commands/new.rb
+- lib/wtr/commands/rm.rb
+- lib/wtr/completion.rb
+- lib/wtr/config.rb
+- lib/wtr/log.rb
+- lib/wtr/result.rb
+- lib/wtr/version.rb
+- lib/wtr/worktrees.rb
+- sig/wtr.rbs
+homepage: https://github.com/arzezak/wtr
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/arzezak/wtr
+  source_code_uri: https://github.com/arzezak/wtr
+  changelog_uri: https://github.com/arzezak/wtr/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: A small CLI for managing git worktrees.
+test_files: []