git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/worktree/add.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Creates a new linked worktree
+      #
+      # @example Add a worktree at a path (auto-creates a branch)
+      #   Git::Commands::Worktree::Add.new(execution_context).call('/tmp/feature')
+      #
+      # @example Add a worktree and check out an existing branch
+      #   Git::Commands::Worktree::Add.new(execution_context).call('/tmp/hotfix', 'main')
+      #
+      # @example Add a worktree with a new branch
+      #   Git::Commands::Worktree::Add.new(execution_context).call('/tmp/feat', b: 'feature/new')
+      #
+      # @example Add a detached-HEAD worktree locked at creation
+      #   Git::Commands::Worktree::Add.new(execution_context).call('/tmp/exp', detach: true, lock: true)
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Add < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'add'
+          flag_option %i[force f], max_times: 2
+          value_option :b
+          value_option :B
+          flag_option %i[detach d]
+          flag_option :checkout, negatable: true
+          flag_option :guess_remote, negatable: true
+          flag_option :relative_paths, negatable: true
+          flag_option :track, negatable: true
+          flag_option :lock
+          flag_option :orphan
+          flag_option %i[quiet q]
+          value_option :reason
+          end_of_options
+          operand :path, required: true
+          operand :commit_ish
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(path, commit_ish = nil, **options)
+        #
+        #     Create a new linked worktree and check out `commit_ish` into it
+        #
+        #     @param path [String] filesystem path for the new worktree
+        #
+        #     @param commit_ish [String, nil] (nil) branch, tag, or commit to check out
+        #
+        #       When omitted, git creates a new branch named after the final path
+        #       component and checks it out.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, Integer, nil] :force (nil) override safety guards
+        #
+        #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit
+        #       `--force --force`, which also allows adding worktrees for locked branches.
+        #
+        #       Alias: :f
+        #
+        #     @option options [String] :b (nil) create a new branch with this name
+        #       and check it out
+        #
+        #     @option options [String] :B (nil) create or reset a branch with this
+        #       name and check it out
+        #
+        #     @option options [Boolean, nil] :detach (nil) check out in
+        #       detached-HEAD state
+        #
+        #       Alias: :d
+        #
+        #     @option options [Boolean, nil] :checkout (nil) control whether the working
+        #       tree is checked out after creation (`--checkout`)
+        #
+        #     @option options [Boolean, nil] :no_checkout (nil) suppress the initial
+        #       checkout after worktree creation (`--no-checkout`)
+        #
+        #     @option options [Boolean, nil] :guess_remote (nil) base new branch on a
+        #       matching remote-tracking branch (`--guess-remote`)
+        #
+        #       Applied when no `commit_ish` argument is provided.
+        #
+        #     @option options [Boolean, nil] :no_guess_remote (nil) disable guess-remote
+        #       behavior (`--no-guess-remote`)
+        #
+        #     @option options [Boolean, nil] :relative_paths (nil) link worktrees using
+        #       relative paths (`--relative-paths`)
+        #
+        #       Overrides the `worktree.useRelativePaths` config option.
+        #
+        #     @option options [Boolean, nil] :no_relative_paths (nil) use absolute paths
+        #       for worktree links (`--no-relative-paths`)
+        #
+        #       Overrides the `worktree.useRelativePaths` config option.
+        #
+        #     @option options [Boolean, nil] :track (nil) mark the upstream branch for
+        #       tracking (`--track`)
+        #
+        #     @option options [Boolean, nil] :no_track (nil) do not mark the upstream
+        #       branch for tracking (`--no-track`)
+        #
+        #     @option options [Boolean, nil] :lock (nil) lock the worktree immediately
+        #       after creation
+        #
+        #     @option options [Boolean, nil] :orphan (nil) create an empty worktree
+        #       associated with a new unborn branch
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #       Alias: :q
+        #
+        #     @option options [String] :reason (nil) explanation for why the worktree
+        #       is locked
+        #
+        #       Only meaningful when used with `:lock`.
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree add`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/list.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Worktree
+      # Lists all worktrees attached to the repository
+      #
+      # @example List all worktrees in porcelain format
+      #   Git::Commands::Worktree::List.new(execution_context).call(porcelain: true)
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class List < Git::Commands::Base
+        arguments do
+          literal 'worktree'
+          literal 'list'
+          flag_option :porcelain
+          flag_option :z
+          flag_option %i[verbose v]
+          value_option :expire
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(**options)
+        #
+        #     List all worktrees attached to the repository
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :porcelain (nil) produce machine-readable
+        #       output
+        #
+        #     @option options [Boolean, nil] :z (nil) terminate output lines with NUL
+        #       bytes (use with `:porcelain`)
+        #
+        #     @option options [Boolean, nil] :verbose (nil) output additional information
+        #       about worktrees
+        #
+        #       Alias: :v
+        #
+        #     @option options [String] :expire (nil) annotate missing worktrees as
+        #       prunable if older than this time expression
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree list`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/lock.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Locks a worktree to prevent it from being pruned
+      #
+      # @example Lock a worktree
+      #   Git::Commands::Worktree::Lock.new(execution_context).call('/tmp/feature')
+      #
+      # @example Lock with a reason message
+      #   Git::Commands::Worktree::Lock.new(execution_context).call('/tmp/feature', reason: 'on NFS share')
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Lock < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'lock'
+          value_option :reason
+          end_of_options
+          operand :worktree, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(worktree, **options)
+        #
+        #     Lock a worktree to prevent it from being pruned
+        #
+        #     @param worktree [String] path or unique suffix identifying the
+        #       worktree to lock
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :reason (nil) human-readable explanation stored
+        #       alongside the lock
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree lock`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/management_base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Worktree
+      # Shared base class for worktree management subcommands
+      #
+      # Overrides the `env` method from {Git::Commands::Base} to unconditionally
+      # unset `GIT_INDEX_FILE` in the subprocess environment. Git worktrees
+      # maintain their own index files; passing a `GIT_INDEX_FILE` override when
+      # running management commands causes silent corruption of both the main
+      # worktree and linked worktree indexes.
+      #
+      # All worktree management subcommands ({Add}, {Lock}, {Move}, {Prune},
+      # {Remove}, {Repair}, {Unlock}) inherit from this class. The read-only
+      # {List} subcommand uses {Git::Commands::Base} directly.
+      #
+      # @example Defining a new worktree management subcommand
+      #   class Archive < Git::Commands::Worktree::ManagementBase
+      #     arguments do
+      #       literal 'worktree'
+      #       literal 'archive'
+      #       operand :path, required: true
+      #     end
+      #   end
+      #
+      # @see Git::Commands::Base
+      #
+      # @see Git::Commands::Worktree
+      #
+      # @api private
+      #
+      class ManagementBase < Git::Commands::Base
+        private
+
+        # Returns environment variable overrides that unset `GIT_INDEX_FILE`
+        #
+        # @return [Hash] the environment variable overrides, always
+        #   `{ 'GIT_INDEX_FILE' => nil }`
+        #
+        # @api private
+        #
+        def env
+          { 'GIT_INDEX_FILE' => nil }
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/move.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Moves a linked worktree to a new filesystem location
+      #
+      # @example Move a worktree to a new path
+      #   Git::Commands::Worktree::Move.new(execution_context).call('/tmp/old', '/tmp/new')
+      #
+      # @example Force-move a locked worktree
+      #   Git::Commands::Worktree::Move.new(execution_context).call('/tmp/feat', '/tmp/feat2', force: true)
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Move < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'move'
+          flag_option %i[force f], max_times: 2
+          end_of_options
+          operand :worktree, required: true
+          operand :new_path, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(worktree, new_path, **options)
+        #
+        #     Move a linked worktree to a new filesystem location
+        #
+        #     @param worktree [String] path or unique suffix identifying the
+        #       worktree to move
+        #
+        #     @param new_path [String] destination path for the worktree
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, Integer, nil] :force (nil) allow moving a
+        #       locked worktree
+        #
+        #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit
+        #       `--force --force`, which also handles locked or missing destinations.
+        #
+        #       Alias: :f
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree move`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/prune.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Prunes stale worktree administrative files
+      #
+      # @example Prune stale worktree info
+      #   Git::Commands::Worktree::Prune.new(execution_context).call
+      #
+      # @example Dry-run to see what would be pruned
+      #   Git::Commands::Worktree::Prune.new(execution_context).call(dry_run: true)
+      #
+      # @example Prune entries older than 2 weeks
+      #   Git::Commands::Worktree::Prune.new(execution_context).call(expire: '2.weeks.ago')
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Prune < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'prune'
+          flag_option %i[dry_run n]
+          flag_option %i[verbose v]
+          value_option :expire
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(**options)
+        #
+        #     Prune stale worktree administrative files
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :dry_run (nil) report what would be removed
+        #       without removing anything
+        #
+        #       Alias: :n
+        #
+        #     @option options [Boolean, nil] :verbose (nil) report all removals
+        #
+        #       Alias: :v
+        #
+        #     @option options [String] :expire (nil) only prune entries older than
+        #       this time expression
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree prune`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/remove.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Removes a linked worktree
+      #
+      # @example Remove a clean worktree
+      #   Git::Commands::Worktree::Remove.new(execution_context).call('/tmp/feature')
+      #
+      # @example Force-remove an unclean worktree
+      #   Git::Commands::Worktree::Remove.new(execution_context).call('/tmp/feature', force: true)
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Remove < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'remove'
+          flag_option %i[force f], max_times: 2
+          end_of_options
+          operand :worktree, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(worktree, **options)
+        #
+        #     Remove a linked worktree
+        #
+        #     @param worktree [String] path or unique suffix identifying the
+        #       worktree to remove
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, Integer, nil] :force (nil) remove even if the
+        #       worktree has uncommitted changes
+        #
+        #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit
+        #       `--force --force`, which also removes locked worktrees.
+        #
+        #       Alias: :f
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree remove`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/repair.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Repairs worktree administrative files
+      #
+      # Resolves broken links between the repository and one or more linked
+      # worktrees. Useful after a worktree directory is moved manually.
+      #
+      # @example Repair all registered worktrees
+      #   Git::Commands::Worktree::Repair.new(execution_context).call
+      #
+      # @example Repair specific moved worktrees
+      #   Git::Commands::Worktree::Repair.new(execution_context).call('/tmp/moved1', '/tmp/moved2')
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Repair < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'repair'
+          flag_option :relative_paths, negatable: true
+          end_of_options
+          operand :path, repeatable: true
+        end
+
+        # git worktree repair was introduced in git 2.29.0
+        requires_git_version '2.29.0'
+
+        # @!method call(*, **)
+        #
+        #   @overload call(*path, **options)
+        #
+        #     Repair worktree administrative files
+        #
+        #     @param path [Array<String>] paths to specific worktrees to repair
+        #
+        #       When omitted, all registered worktrees are repaired.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :relative_paths (nil) link worktrees using
+        #       relative paths (`--relative-paths`)
+        #
+        #       Overrides the `worktree.useRelativePaths` config option.
+        #
+        #     @option options [Boolean, nil] :no_relative_paths (nil) use absolute paths
+        #       for worktree links (`--no-relative-paths`)
+        #
+        #       Overrides the `worktree.useRelativePaths` config option. Also causes
+        #       repair to update linking files if there is an absolute/relative
+        #       mismatch, even if the links are already correct.
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree repair`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @raise [Git::VersionError] if git version is below 2.29.0
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree/unlock.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'git/commands/worktree/management_base'
+
+module Git
+  module Commands
+    module Worktree
+      # Unlocks a worktree, allowing it to be pruned, moved, or deleted
+      #
+      # @example Unlock a worktree
+      #   Git::Commands::Worktree::Unlock.new(execution_context).call('/tmp/feature')
+      #
+      # @note `arguments` block audited against
+      #   https://git-scm.com/docs/git-worktree/2.54.0
+      #
+      # @see Git::Commands::Worktree Git::Commands::Worktree for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+      #
+      # @api private
+      #
+      class Unlock < ManagementBase
+        arguments do
+          literal 'worktree'
+          literal 'unlock'
+          end_of_options
+          operand :worktree, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(worktree)
+        #
+        #     Unlock a worktree, allowing it to be pruned, moved, or deleted
+        #
+        #     @param worktree [String] path or unique suffix identifying the worktree
+        #       to unlock
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git worktree unlock`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/worktree.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'worktree/add'
+require_relative 'worktree/list'
+require_relative 'worktree/lock'
+require_relative 'worktree/management_base'
+require_relative 'worktree/move'
+require_relative 'worktree/prune'
+require_relative 'worktree/remove'
+require_relative 'worktree/repair'
+require_relative 'worktree/unlock'
+
+module Git
+  module Commands
+    # Implements `git worktree` subcommands for managing multiple working trees
+    #
+    # Split into subclasses because each subcommand has a distinct call shape
+    # and option set:
+    #
+    # - {Worktree::Add} — create a new linked worktree
+    # - {Worktree::List} — list all worktrees
+    # - {Worktree::Lock} — prevent a worktree from being pruned
+    # - {Worktree::Move} — move a worktree to a new location
+    # - {Worktree::Prune} — prune stale worktree administrative files
+    # - {Worktree::Remove} — remove a worktree
+    # - {Worktree::Repair} — repair worktree administrative files
+    # - {Worktree::Unlock} — allow a worktree to be pruned
+    #
+    # Management subcommands ({Add}, {Lock}, {Move}, {Prune}, {Remove},
+    # {Repair}, {Unlock}) inherit from {Worktree::ManagementBase}, which
+    # unconditionally unsets `GIT_INDEX_FILE` in the subprocess environment.
+    # Git worktrees maintain their own index files; leaving `GIT_INDEX_FILE`
+    # set causes silent corruption of both the main and the linked worktree
+    # indexes.
+    #
+    # @see https://git-scm.com/docs/git-worktree git-worktree documentation
+    #
+    # @api private
+    #
+    module Worktree
+    end
+  end
+end