git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/status.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git status` command
+    #
+    # Shows the working tree status — the differences between the index and
+    # the current HEAD commit, and between the working directory and the index.
+    #
+    # @example Show working tree status
+    #   status = Git::Commands::Status.new(execution_context)
+    #   status.call
+    #
+    # @example Show short-format status
+    #   status = Git::Commands::Status.new(execution_context)
+    #   status.call(short: true)
+    #
+    # @example Show status in porcelain v2 format
+    #   status = Git::Commands::Status.new(execution_context)
+    #   status.call(porcelain: 'v2')
+    #
+    # @example Show status for specific paths
+    #   status = Git::Commands::Status.new(execution_context)
+    #   status.call('lib/', 'spec/')
+    #
+    # @example Show all untracked files
+    #   status = Git::Commands::Status.new(execution_context)
+    #   status.call(untracked_files: 'all')
+    #
+    # @note `arguments` block audited against
+    #   https://git-scm.com/docs/git-status/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-status git-status
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Status < Git::Commands::Base
+      arguments do
+        literal 'status'
+
+        # Output format
+        flag_option %i[short s]
+        flag_option %i[branch b]
+        flag_option :show_stash
+        flag_or_value_option :porcelain, inline: true
+        flag_option :long
+        flag_option %i[verbose v]
+
+        # Untracked files
+        flag_or_value_option %i[untracked_files u], inline: true
+
+        # Submodule handling
+        flag_or_value_option :ignore_submodules, inline: true
+
+        # Ignored files
+        flag_or_value_option :ignored, inline: true
+
+        # NUL-terminated output
+        flag_option :z
+
+        # Column display
+        flag_or_value_option :column, inline: true, negatable: true
+
+        # Upstream tracking
+        flag_option :ahead_behind, negatable: true
+
+        # Rename detection
+        flag_option :renames, negatable: true
+        flag_or_value_option :find_renames, inline: true
+
+        end_of_options
+
+        operand :pathspec, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*pathspecs, **options)
+      #
+      #     Execute the git status command
+      #
+      #     @param pathspecs [Array<String>] limit output to the named paths
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :short (nil) give output in short format
+      #
+      #       Alias: :s
+      #
+      #     @option options [Boolean, nil] :branch (nil) show the branch and tracking info
+      #       even in short-format
+      #
+      #       Alias: :b
+      #
+      #     @option options [Boolean, nil] :show_stash (nil) show the number of entries
+      #       currently stashed away
+      #
+      #     @option options [Boolean, String, nil] :porcelain (nil) give the output in an
+      #       easy-to-parse format for scripts
+      #
+      #       When `true`, gives porcelain format. When a string (e.g. `'v1'`, `'v2'`),
+      #       gives the specified porcelain format version.
+      #
+      #     @option options [Boolean, nil] :long (nil) give output in long format (the default)
+      #
+      #     @option options [Boolean, nil] :verbose (nil) in addition to names of files that
+      #       have been changed, also show the textual changes that are staged
+      #
+      #       Alias: :v
+      #
+      #     @option options [Boolean, String, nil] :untracked_files (nil) show untracked files
+      #
+      #       Mode can be `'no'`, `'normal'`, or `'all'`. When `true`, uses the default
+      #       mode.
+      #
+      #       Alias: :u
+      #
+      #     @option options [Boolean, String, nil] :ignore_submodules (nil) ignore changes
+      #       to submodules
+      #
+      #       Mode can be `'none'`, `'untracked'`, `'dirty'`, or `'all'`.
+      #
+      #     @option options [Boolean, String, nil] :ignored (nil) show ignored files as well
+      #
+      #       Mode can be `'traditional'`, `'no'`, or `'matching'`.
+      #
+      #     @option options [Boolean, nil] :z (nil) terminate entries with NUL instead of
+      #       newline (`-z`)
+      #
+      #       Implies `--porcelain=v1`
+      #
+      #     @option options [Boolean, String, nil] :column (nil) display untracked files in
+      #       columns (`--column`)
+      #
+      #       Pass `true` for `--column` or a string of options for `--column=<options>`.
+      #
+      #     @option options [Boolean, nil] :no_column (nil) disable column output (`--no-column`)
+      #
+      #     @option options [Boolean, nil] :ahead_behind (nil) show ahead/behind counts for
+      #       the branch (`--ahead-behind`)
+      #
+      #     @option options [Boolean, nil] :no_ahead_behind (nil) suppress ahead/behind counts
+      #       for the branch (`--no-ahead-behind`)
+      #
+      #     @option options [Boolean, nil] :renames (nil) turn on rename detection (`--renames`)
+      #
+      #     @option options [Boolean, nil] :no_renames (nil) turn off rename detection
+      #       (`--no-renames`)
+      #
+      #     @option options [Boolean, String, nil] :find_renames (nil) turn on rename detection
+      #       with optional similarity threshold
+      #
+      #       When `true`, enables rename detection without a threshold. When a string
+      #       (e.g. `'50'`), adds `--find-renames=<n>`.
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git status`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #   @api public
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module SymbolicRef
+      # Deletes a symbolic ref via `git symbolic-ref --delete`
+      #
+      # Removes the named symbolic ref. When `quiet: true`, exit status 1
+      # (non-symbolic ref) does not produce an error message.
+      #
+      # @example Delete a symbolic ref
+      #   cmd = Git::Commands::SymbolicRef::Delete.new(execution_context)
+      #   cmd.call('HEAD')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-symbolic-ref/2.53.0
+      #
+      # @see Git::Commands::SymbolicRef
+      #
+      # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
+      #
+      # @api private
+      #
+      class Delete < Git::Commands::Base
+        arguments do
+          literal 'symbolic-ref'
+
+          # Delete the symbolic ref
+          literal '--delete'
+
+          # Suppress error message for non-symbolic (detached) refs
+          flag_option %i[quiet q]
+
+          end_of_options
+
+          # The symbolic ref name to delete (e.g. `HEAD`)
+          operand :name, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, **options)
+        #
+        #     Execute the `git symbolic-ref --delete` command
+        #
+        #     @param name [String] the symbolic ref name to delete
+        #       (e.g. `HEAD`)
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress error message
+        #       when the name is not a symbolic ref
+        #
+        #       Alias: :q
+        #
+        #     @return [Git::CommandLineResult] the result of calling
+        #       `git symbolic-ref --delete`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [ArgumentError] if the name operand is missing
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/symbolic_ref/read.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module SymbolicRef
+      # Reads the target of a symbolic ref via `git symbolic-ref`
+      #
+      # Given one argument, reads which branch head the given symbolic ref
+      # refers to and outputs its path, relative to the `.git/` directory.
+      #
+      # Exits with status 0 if the contents were printed correctly, or
+      # status 1 if the requested name is not a symbolic ref (e.g. a
+      # detached HEAD). When `quiet: true`, exit status 1 is silent
+      # (no error message on stderr).
+      #
+      # @example Read current HEAD
+      #   cmd = Git::Commands::SymbolicRef::Read.new(execution_context)
+      #   result = cmd.call('HEAD')
+      #   result.stdout  # => "refs/heads/main"
+      #
+      # @example Read HEAD with shortened output
+      #   cmd = Git::Commands::SymbolicRef::Read.new(execution_context)
+      #   result = cmd.call('HEAD', short: true)
+      #   result.stdout  # => "main"
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-symbolic-ref/2.53.0
+      #
+      # @see Git::Commands::SymbolicRef
+      #
+      # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
+      #
+      # @api private
+      #
+      class Read < Git::Commands::Base
+        arguments do
+          literal 'symbolic-ref'
+
+          # Suppress error message for non-symbolic (detached) refs
+          flag_option %i[quiet q]
+
+          # Shorten the ref output (e.g. `refs/heads/main` → `main`)
+          flag_option :short
+
+          # Follow (or stop after one level of) symbolic ref chain
+          flag_option :recurse, negatable: true
+
+          end_of_options
+
+          # The symbolic ref name to read (e.g. `HEAD`)
+          operand :name, required: true
+        end
+
+        # Exit status 1 indicates the name is not a symbolic ref
+        # (e.g. detached HEAD) — this is not an error
+        allow_exit_status 0..1
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, **options)
+        #
+        #     Execute the `git symbolic-ref` command to read a symbolic ref
+        #
+        #     @param name [String] the symbolic ref name to read
+        #       (e.g. `HEAD`)
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress error message
+        #       when the name is not a symbolic ref
+        #
+        #       Alias: :q
+        #
+        #     @option options [Boolean, nil] :short (nil) shorten the ref output
+        #       (e.g. `refs/heads/main` → `main`)
+        #
+        #     @option options [Boolean, nil] :recurse (nil) follow chain of symbolic refs
+        #       until result no longer points at a symbolic ref (`--recurse`)
+        #
+        #     @option options [Boolean, nil] :no_recurse (nil) stop after a single level
+        #       of dereferencing (`--no-recurse`)
+        #
+        #     @return [Git::CommandLineResult] the result of calling
+        #       `git symbolic-ref`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [ArgumentError] if the name operand is missing
+        #
+        #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+      end
+    end
+  end
+end

data/lib/git/commands/symbolic_ref/update.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module SymbolicRef
+      # Creates or updates a symbolic ref via `git symbolic-ref`
+      #
+      # Given two arguments, creates or updates a symbolic ref `<name>` to
+      # point at the given branch `<ref>`.
+      #
+      # @example Update HEAD to point to a branch
+      #   cmd = Git::Commands::SymbolicRef::Update.new(execution_context)
+      #   cmd.call('HEAD', 'refs/heads/main')
+      #
+      # @example Update HEAD with a reflog message
+      #   cmd = Git::Commands::SymbolicRef::Update.new(execution_context)
+      #   cmd.call('HEAD', 'refs/heads/main', m: 'switching to main')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-symbolic-ref/2.53.0
+      #
+      # @see Git::Commands::SymbolicRef
+      #
+      # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
+      #
+      # @api private
+      #
+      class Update < Git::Commands::Base
+        arguments do
+          literal 'symbolic-ref'
+
+          # Reflog message for the update
+          value_option :m
+
+          end_of_options
+
+          # The symbolic ref name to update (e.g. `HEAD`)
+          operand :name, required: true
+
+          # The target ref to point to (e.g. `refs/heads/main`)
+          operand :ref, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, ref, **options)
+        #
+        #     Execute the `git symbolic-ref` command to create or update a
+        #     symbolic ref
+        #
+        #     @param name [String] the symbolic ref name to update
+        #       (e.g. `HEAD`)
+        #
+        #     @param ref [String] the target ref to point to
+        #       (e.g. `refs/heads/main`)
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :m (nil) a reflog message for
+        #       the update
+        #
+        #     @return [Git::CommandLineResult] the result of calling
+        #       `git symbolic-ref`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [ArgumentError] if the name operand is missing
+        #
+        #     @raise [ArgumentError] if the ref operand is missing
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/symbolic_ref.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'symbolic_ref/delete'
+require_relative 'symbolic_ref/read'
+require_relative 'symbolic_ref/update'
+
+module Git
+  module Commands
+    # Commands for reading, updating, and deleting symbolic refs via
+    # `git symbolic-ref`
+    #
+    # This module contains command classes split by invocation mode:
+    #
+    # - {SymbolicRef::Read} — read the target of a symbolic ref
+    # - {SymbolicRef::Update} — create or update a symbolic ref to point
+    #   at a given branch
+    # - {SymbolicRef::Delete} — delete a symbolic ref
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
+    #
+    # @example Read the current HEAD
+    #   cmd = Git::Commands::SymbolicRef::Read.new(lib)
+    #   cmd.call('HEAD')
+    #
+    # @example Update HEAD to point to a branch
+    #   cmd = Git::Commands::SymbolicRef::Update.new(lib)
+    #   cmd.call('HEAD', 'refs/heads/main')
+    #
+    # @example Delete a symbolic ref
+    #   cmd = Git::Commands::SymbolicRef::Delete.new(lib)
+    #   cmd.call('HEAD')
+    #
+    module SymbolicRef
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Tag
+      # Implements the `git tag` command for creating new tags
+      #
+      # This command creates a new tag reference pointing at the current HEAD
+      # or a specified commit/object.
+      #
+      # @example Create a lightweight tag
+      #   create = Git::Commands::Tag::Create.new(execution_context)
+      #   create.call('v1.0.0')
+      #
+      # @example Create an annotated tag
+      #   create = Git::Commands::Tag::Create.new(execution_context)
+      #   create.call('v1.0.0', message: 'Release version 1.0.0')
+      #
+      # @example Create a signed tag at a specific commit
+      #   create = Git::Commands::Tag::Create.new(execution_context)
+      #   create.call('v1.0.0', 'abc123', sign: true, message: 'Signed release')
+      #
+      # @example Force replace an existing tag
+      #   create = Git::Commands::Tag::Create.new(execution_context)
+      #   create.call('v1.0.0', force: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-tag/2.53.0
+      #
+      # @see Git::Commands::Tag
+      #
+      # @see https://git-scm.com/docs/git-tag git-tag
+      #
+      # @api private
+      #
+      class Create < Git::Commands::Base
+        arguments do
+          literal 'tag'
+          flag_option %i[annotate a]
+          flag_option %i[sign s], negatable: true
+          value_option %i[local_user u], inline: true
+          flag_option %i[force f]
+          value_option %i[message m], inline: true, allow_empty: true
+          value_option %i[file F], inline: true
+          flag_option %i[edit e], negatable: true
+          key_value_option :trailer, key_separator: ': '
+          value_option :cleanup, inline: true
+          flag_option :create_reflog
+
+          end_of_options
+
+          operand :tagname, required: true
+          operand :commit
+        end
+
+        # @!method call(*, **)
+        #
+        #   Execute the git tag command to create a new tag
+        #
+        #   @overload call(tagname, commit = nil, **options)
+        #
+        #     @param tagname [String] the name of the tag to create
+        #
+        #     @param commit [String, nil] the commit, branch, or object to tag
+        #
+        #       Defaults to HEAD when omitted.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :annotate (nil) make an unsigned, annotated tag object
+        #
+        #       Requires a message via `:message` or `:file`.
+        #
+        #       Alias: :a
+        #
+        #     @option options [Boolean, nil] :sign (nil) make a GPG-signed tag using the default signing
+        #       key (`--sign`)
+        #
+        #       Requires a message via `:message` or `:file`.
+        #
+        #       Alias: :s
+        #
+        #     @option options [Boolean, nil] :no_sign (nil) override `tag.gpgSign` config to disable
+        #       signing (`--no-sign`)
+        #
+        #     @option options [String] :local_user (nil) make a cryptographically signed tag using the given key
+        #
+        #       Requires a message via `:message` or `:file`.
+        #
+        #       Alias: :u
+        #
+        #     @option options [Boolean, nil] :force (nil) replace an existing tag with the given name instead of failing
+        #
+        #       Alias: :f
+        #
+        #     @option options [String] :message (nil) use the given message as the tag message
+        #
+        #       Implies `--annotate` if none of `--annotate`, `--sign`, or `--local-user` is given.
+        #
+        #       Alias: :m
+        #
+        #     @option options [String] :file (nil) take the tag message from the given file
+        #
+        #       Use `-` to read from standard input. Implies `--annotate` if none of
+        #       `--annotate`, `--sign`, or `--local-user` is given.
+        #
+        #       Alias: :F
+        #
+        #     @option options [Boolean, nil] :edit (nil) open an editor to further edit the tag message (`--edit`)
+        #
+        #       Alias: :e
+        #
+        #     @option options [Boolean, nil] :no_edit (nil) suppress the editor (`--no-edit`)
+        #
+        #     @option options [Hash, Array<Array>] :trailer (nil) add trailers to the tag message
+        #
+        #       Can be a Hash `{ 'Key' => 'value' }` or Array of pairs `[['Key', 'value']]`.
+        #       Multiple trailers can be specified.
+        #
+        #     @option options [String] :cleanup (nil) set how the tag message is cleaned up
+        #
+        #       Must be one of: `verbatim` (no changes), `whitespace` (remove leading/trailing
+        #       whitespace lines), or `strip` (remove whitespace and commentary). Default is `strip`.
+        #
+        #     @option options [Boolean, nil] :create_reflog (nil) create a reflog for the tag
+        #
+        #       Enables date-based sha1 expressions such as `tag@{yesterday}`.
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git tag`
+        #
+        #     @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/tag/delete.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Tag
+      # Implements the `git tag --delete` command for deleting tags
+      #
+      # This command deletes one or more tag references.
+      #
+      # @example Delete a single tag
+      #   delete = Git::Commands::Tag::Delete.new(execution_context)
+      #   delete.call('v1.0.0')
+      #
+      # @example Delete multiple tags
+      #   delete = Git::Commands::Tag::Delete.new(execution_context)
+      #   delete.call('v1.0.0', 'v2.0.0')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-tag/2.53.0
+      #
+      # @see Git::Commands::Tag
+      #
+      # @see https://git-scm.com/docs/git-tag git-tag
+      #
+      # @api private
+      #
+      class Delete < Git::Commands::Base
+        arguments do
+          literal 'tag'
+          literal '--delete'
+          operand :tagname, repeatable: true, required: true
+        end
+
+        # git tag --delete exits with status 1 when a tag does not exist, which is acceptable
+        allow_exit_status 0..1
+
+        # @!method call(*, **)
+        #
+        #   @overload call(*tagname)
+        #
+        #     Execute the `git tag --delete` command to delete one or more tags.
+        #
+        #     @param tagname [Array<String>] one or more tag names to delete
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git tag --delete`
+        #
+        #     @raise [ArgumentError] if no tag names are provided or unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+        #
+      end
+    end
+  end
+end