git 1.19.1 → 5.5.0

data/lib/git/commands/branch/create.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # `git branch` command for creating new branches
+      #
+      # This command creates a new branch head pointing to the current HEAD
+      # or a specified start point.
+      #
+      # @example Basic branch creation
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch')
+      #
+      # @example Create branch from a specific start point
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch', 'main')
+      #
+      # @example Force create (reset existing branch)
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch', 'main', force: true)
+      #
+      # @example Create with upstream tracking
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch', 'origin/main', track: true)
+      #
+      # @example Create without upstream tracking
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch', 'origin/main', no_track: true)
+      #
+      # @example Create with inherited tracking configuration
+      #   create = Git::Commands::Branch::Create.new(execution_context)
+      #   create.call('feature-branch', 'origin/main', track: 'inherit')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class Create < Git::Commands::Base
+        arguments do
+          literal 'branch'
+          flag_or_value_option %i[track t], negatable: true, inline: true
+          flag_option %i[force f]
+          flag_option :recurse_submodules
+          flag_option %i[quiet q]
+          flag_option :create_reflog, negatable: true
+          end_of_options
+          operand :branch_name, required: true
+          operand :start_point
+        end
+
+        # @overload call(branch_name, **options)
+        #
+        #   Create a new branch from the current HEAD
+        #
+        #   @param branch_name [String] the name of the branch to create
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, String, nil] :track (nil) configure upstream tracking for
+        #     the new branch
+        #
+        #     - `true`: Set up tracking using the start-point branch itself (`--track`)
+        #     - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
+        #     - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
+        #
+        #     Alias: :t
+        #
+        #   @option options [Boolean, nil] :no_track (nil) do not set up tracking even if
+        #     `branch.autoSetupMerge` is set (`--no-track`)
+        #
+        #   @option options [Boolean, nil] :force (nil) reset the branch to start point even if
+        #     it already exists
+        #
+        #     Without this, git branch refuses to change an existing branch
+        #
+        #     Alias: :f
+        #
+        #   @option options [Boolean, nil] :recurse_submodules (nil) create the branch in the
+        #     superproject and all submodules
+        #
+        #     This is an experimental feature
+        #
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #     Alias: :q
+        #
+        #   @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
+        #     (`--create-reflog`)
+        #
+        #     Enables date-based sha1 expressions such as `branch@\\{yesterday}`
+        #     In non-bare repositories, reflogs are usually enabled by default via
+        #     `core.logAllRefUpdates`
+        #
+        #   @option options [Boolean, nil] :no_create_reflog (nil) forcibly disable the
+        #     branch's reflog (`--no-create-reflog`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        # @overload call(branch_name, start_point, **options)
+        #
+        #   Create a new branch from the specified start point
+        #
+        #   @param branch_name [String] the name of the branch to create
+        #
+        #   @param start_point [String, nil] the commit, branch, or tag to
+        #     start the new branch from
+        #
+        #     Can also use `<rev-A>...<rev-B>` syntax for merge base
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, String, nil] :track (nil) configure upstream tracking for
+        #     the new branch
+        #
+        #     - `true`: Set up tracking using the start-point branch itself (`--track`)
+        #     - `'direct'`: Same as `true`, explicitly use start-point as upstream (`--track=direct`)
+        #     - `'inherit'`: Copy upstream configuration from start-point branch (`--track=inherit`)
+        #
+        #     Alias: :t
+        #
+        #   @option options [Boolean, nil] :no_track (nil) do not set up tracking even if
+        #     `branch.autoSetupMerge` is set (`--no-track`)
+        #
+        #   @option options [Boolean, nil] :force (nil) reset the branch to start point even if
+        #     it already exists
+        #
+        #     Without this, git branch refuses to change an existing branch
+        #
+        #     Alias: :f
+        #
+        #   @option options [Boolean, nil] :recurse_submodules (nil) create the branch in the
+        #     superproject and all submodules
+        #
+        #     This is an experimental feature
+        #
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #     Alias: :q
+        #
+        #   @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
+        #     (`--create-reflog`)
+        #
+        #     Enables date-based sha1 expressions such as `branch@\\{yesterday}`
+        #     In non-bare repositories, reflogs are usually enabled by default via
+        #     `core.logAllRefUpdates`
+        #
+        #   @option options [Boolean, nil] :no_create_reflog (nil) forcibly disable the
+        #     branch's reflog (`--no-create-reflog`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/branch/delete.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # Implements the `git branch --delete` command for deleting branches
+      #
+      # @example Delete a single branch
+      #   delete = Git::Commands::Branch::Delete.new(execution_context)
+      #   result = delete.call('feature-branch')
+      #
+      # @example Delete multiple branches
+      #   delete = Git::Commands::Branch::Delete.new(execution_context)
+      #   result = delete.call('branch1', 'branch2')
+      #
+      # @example Force delete (works even if not merged)
+      #   delete = Git::Commands::Branch::Delete.new(execution_context)
+      #   result = delete.call('feature-branch', force: true)
+      #
+      # @example Delete remote-tracking branch
+      #   delete = Git::Commands::Branch::Delete.new(execution_context)
+      #   result = delete.call('origin/feature', remotes: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class Delete < Git::Commands::Base
+        arguments do
+          literal 'branch'
+          literal '--delete'
+          flag_option %i[force f]
+          flag_option %i[remotes r]
+
+          end_of_options
+
+          operand :branch_name, repeatable: true, required: true
+        end
+
+        # git branch --delete exits 1 when one or more branches cannot be deleted
+        allow_exit_status 0..1
+
+        # Executes the git branch --delete command to delete branches
+        #
+        # @overload call(*branch_name, **options)
+        #
+        #   @param branch_name [Array<String>] one or more branch names to delete
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :force (nil) allow deleting the branch irrespective of
+        #     its merged status, or whether it even points to a valid commit
+        #
+        #     Equivalent to the `-D` shortcut (`--delete --force`)
+        #
+        #     Alias: :f
+        #
+        #   @option options [Boolean, nil] :remotes (nil) delete remote-tracking branches
+        #
+        #     Use this together with `--delete` to remove remote-tracking branches that no
+        #     longer exist in the remote repository, or if `git fetch` was configured not to
+        #     fetch them again
+        #
+        #     Alias: :r
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --delete`
+        #
+        #   @raise [ArgumentError] if no branch names are provided
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # Implements the `git branch --list` command
+      #
+      # @example Basic branch listing
+      #   list = Git::Commands::Branch::List.new(execution_context)
+      #   branches = list.call
+      #
+      # @example List all branches (local and remote)
+      #   list = Git::Commands::Branch::List.new(execution_context)
+      #   all_branches = list.call(all: true)
+      #
+      # @example List branches containing a commit
+      #   list = Git::Commands::Branch::List.new(execution_context)
+      #   branches = list.call(contains: 'abc123')
+      #
+      # @example List branches with patterns
+      #   list = Git::Commands::Branch::List.new(execution_context)
+      #   feature_branches = list.call('feature/*')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class List < Git::Commands::Base
+        arguments do
+          literal 'branch'
+          literal '--list'
+
+          flag_or_value_option :color, inline: true, negatable: true
+          flag_option %i[verbose v], max_times: 2
+          flag_or_value_option :abbrev, inline: true, negatable: true
+          flag_or_value_option :column, inline: true, negatable: true
+          value_option :sort, inline: true, repeatable: true
+          flag_or_value_option :merged
+          flag_or_value_option :no_merged
+          flag_or_value_option :contains
+          flag_or_value_option :no_contains
+          value_option :points_at
+          value_option :format, inline: true
+          flag_option %i[remotes r]
+          flag_option %i[all a]
+          flag_option %i[ignore_case i]
+          flag_option :omit_empty
+
+          end_of_options
+
+          operand :pattern, repeatable: true
+        end
+
+        # @overload call(*pattern, **options)
+        #
+        #   Execute the `git branch --list` command
+        #
+        #   @param pattern [Array<String>] shell wildcard patterns to filter branches
+        #
+        #     If multiple patterns are given, a branch is shown if it matches any
+        #     of the patterns
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, String, nil] :color (nil) color branches output
+        #
+        #     Pass `true` for `--color` or a string (`'always'`, `'never'`,
+        #     `'auto'`) for `--color=<when>`
+        #
+        #   @option options [Boolean, nil] :no_color (nil) suppress colored output
+        #     (`--no-color`)
+        #
+        #   @option options [Boolean, Integer, nil] :verbose (nil) show sha1 and
+        #     commit subject for each branch
+        #
+        #     Pass `true` for `--verbose` (show sha1 and subject); pass `2` for
+        #     `--verbose --verbose` (also show the linked worktree path and
+        #     upstream branch name)
+        #
+        #     Alias: :v
+        #
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) minimum sha1
+        #     display length when used with verbose mode
+        #
+        #     Pass an integer for `--abbrev=<n>` or `true` for `--abbrev`
+        #     (default length)
+        #
+        #   @option options [Boolean, nil] :no_abbrev (nil) show full sha1s
+        #     (`--no-abbrev`)
+        #
+        #   @option options [Boolean, String, nil] :column (nil) display branch
+        #     listing in columns
+        #
+        #     Pass `true` for `--column` or a string of options for
+        #     `--column=<options>`
+        #
+        #     Only applicable in non-verbose mode
+        #
+        #   @option options [Boolean, nil] :no_column (nil) disable column output
+        #     (`--no-column`)
+        #
+        #   @option options [String, Array<String>] :sort (nil) sort branches by
+        #     the specified key(s)
+        #
+        #     Give an array to add multiple --sort options
+        #     Prefix each key with '-' for descending order
+        #     For example, sort: ['refname', '-committerdate']
+        #
+        #   @option options [Boolean, String, nil] :merged (nil) list only branches
+        #     merged into the specified commit
+        #
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
+        #
+        #   @option options [Boolean, String, nil] :no_merged (nil) list only
+        #     branches not merged into the specified commit
+        #
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
+        #
+        #   @option options [Boolean, String, nil] :contains (nil) list only
+        #     branches that contain the specified commit
+        #
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
+        #
+        #   @option options [Boolean, String, nil] :no_contains (nil) list only
+        #     branches that don't contain the specified commit
+        #
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
+        #
+        #   @option options [String] :points_at (nil) list only branches that
+        #     point at the specified object
+        #
+        #   @option options [String] :format (nil) output format string for each
+        #     branch
+        #
+        #   @option options [Boolean, nil] :remotes (nil) list only remote-tracking
+        #     branches
+        #
+        #     Alias: :r
+        #
+        #   @option options [Boolean, nil] :all (nil) list both local and remote
+        #     branches
+        #
+        #     Alias: :a
+        #
+        #   @option options [Boolean, nil] :ignore_case (nil) sort and filter
+        #     branches case insensitively
+        #
+        #     Alias: :i
+        #
+        #   @option options [Boolean, nil] :omit_empty (nil) do not print a
+        #     newline after formatted refs where the format expands to the empty
+        #     string
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --list`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # Implements the `git branch --move` command for renaming branches
+      #
+      # This command moves/renames a branch, together with its config and reflog.
+      # If the old branch name is omitted, renames the current branch.
+      #
+      # @example Rename the current branch
+      #   move = Git::Commands::Branch::Move.new(execution_context)
+      #   move.call('new-branch-name')
+      #
+      # @example Rename a specific branch
+      #   move = Git::Commands::Branch::Move.new(execution_context)
+      #   move.call('old-branch-name', 'new-branch-name')
+      #
+      # @example Force rename (overwrite existing branch)
+      #   move = Git::Commands::Branch::Move.new(execution_context)
+      #   move.call('old-branch', 'existing-branch', force: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class Move < Git::Commands::Base
+        # NOTE: The positional arguments follow Ruby semantics:
+        # - When one positional is provided, it fills new_branch (required)
+        # - When two positionals are provided, they fill old_branch and new_branch
+        #
+        # This matches the git CLI: `git branch -m [<old-branch>] <new-branch>`
+        arguments do
+          literal 'branch'
+          literal '--move'
+          flag_option %i[force f]
+
+          end_of_options
+
+          operand :old_branch
+          operand :new_branch, required: true
+        end
+
+        # Executes the git branch --move command to rename a branch
+        #
+        # @overload call(new_branch, **options)
+        #
+        #   Rename the current branch to new_branch
+        #
+        #   @param new_branch [String] the new name for the branch
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already
+        #     exists
+        #
+        #     Alias: :f
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --move`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        # @overload call(old_branch, new_branch, **options)
+        #
+        #   Rename old_branch to new_branch
+        #
+        #   @param old_branch [String] the current name of the branch
+        #
+        #   @param new_branch [String] the new name for the branch
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already
+        #     exists
+        #
+        #     Alias: :f
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --move`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/branch/set_upstream.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # Implements the `git branch --set-upstream-to` command for configuring upstream tracking
+      #
+      # This command sets up tracking information so the specified upstream branch is considered
+      # the upstream for the given branch (or current branch if not specified).
+      #
+      # @example Set upstream for current branch
+      #   set_upstream = Git::Commands::Branch::SetUpstream.new(execution_context)
+      #   set_upstream.call(set_upstream_to: 'origin/main')
+      #
+      # @example Set upstream for a specific branch
+      #   set_upstream = Git::Commands::Branch::SetUpstream.new(execution_context)
+      #   set_upstream.call('feature', set_upstream_to: 'origin/main')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class SetUpstream < Git::Commands::Base
+        # NOTE: The set_upstream_to option maps to git's --set-upstream-to=<upstream> syntax.
+        # The branch_name positional is optional; if omitted, git uses the current branch.
+        # The set_upstream_to keyword is required by the Ruby method signature, not the DSL.
+        arguments do
+          literal 'branch'
+          value_option %i[set_upstream_to u], inline: true, required: true, allow_nil: false
+
+          end_of_options
+
+          operand :branch_name
+        end
+
+        # @!method call(*)
+        #
+        #   @overload call(**options)
+        #
+        #     Set upstream for the current branch
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :set_upstream_to (required)
+        #       upstream branch to set (e.g., `origin/main`)
+        #
+        #       Alias: :u
+        #
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --set-upstream-to`
+        #
+        #     @raise [ArgumentError] if set_upstream_to is not provided
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @overload call(branch_name, **options)
+        #
+        #     Set upstream for the specified branch
+        #
+        #     @param branch_name [String] the branch to set upstream for
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :set_upstream_to (required)
+        #       upstream branch to set (e.g., `origin/main`)
+        #
+        #       Alias: :u
+        #
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --set-upstream-to`
+        #
+        #     @raise [ArgumentError] if set_upstream_to is not provided
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/branch/show_current.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Branch
+      # Implements the `git branch --show-current` command
+      #
+      # Prints the name of the current branch. In detached HEAD state, nothing
+      # is printed.
+      #
+      # @example Print the current branch name
+      #   show_current = Git::Commands::Branch::ShowCurrent.new(execution_context)
+      #   result = show_current.call
+      #   puts result.stdout  # => "main\n"
+      #
+      # @example Check for detached HEAD state
+      #   show_current = Git::Commands::Branch::ShowCurrent.new(execution_context)
+      #   result = show_current.call
+      #   # result.stdout is empty ("") when in detached HEAD state
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-branch/2.53.0
+      #
+      # @see Git::Commands::Branch
+      #
+      # @see https://git-scm.com/docs/git-branch git-branch
+      #
+      # @api private
+      #
+      class ShowCurrent < Git::Commands::Base
+        arguments do
+          literal 'branch'
+          literal '--show-current'
+        end
+
+        # @!method call(*)
+        #
+        #   @overload call()
+        #
+        #     Execute the `git branch --show-current` command
+        #
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --show-current`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end