git 4.3.2 → 5.0.0.beta.1

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Tag
+      # Implements the `git tag --list` command
+      #
+      # This command lists existing tags with optional filtering and sorting.
+      #
+      # @example Basic tag listing
+      #   list = Git::Commands::Tag::List.new(execution_context)
+      #   tags = list.call
+      #
+      # @example List tags matching a pattern
+      #   list = Git::Commands::Tag::List.new(execution_context)
+      #   tags = list.call('v1.*')
+      #
+      # @example List tags containing a commit
+      #   list = Git::Commands::Tag::List.new(execution_context)
+      #   tags = list.call(contains: 'abc123')
+      #
+      # @example List tags with multiple patterns
+      #   list = Git::Commands::Tag::List.new(execution_context)
+      #   tags = list.call('v1.*', 'v2.*', sort: 'version:refname')
+      #
+      # @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 List < Git::Commands::Base
+        arguments do
+          literal 'tag'
+          literal '--list'
+
+          # Annotation display
+          flag_or_value_option :n, inline: true
+
+          # Output ordering and presentation
+          value_option :sort, inline: true, repeatable: true
+          flag_or_value_option :color, inline: true
+          flag_option %i[ignore_case i]
+          flag_option :omit_empty
+          flag_or_value_option :column, negatable: true, inline: true
+
+          # Filtering
+          flag_or_value_option :contains
+          flag_or_value_option :no_contains
+          flag_or_value_option :merged
+          flag_or_value_option :no_merged
+          flag_or_value_option :points_at
+
+          # Output format
+          value_option :format, inline: true
+
+          end_of_options
+          operand :pattern, repeatable: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   Execute the git tag --list command
+        #
+        #   @overload call(*pattern, **options)
+        #
+        #     @param pattern [Array<String>] Shell wildcard patterns to filter tags
+        #
+        #       Multiple patterns can be provided; a tag is shown if it matches any pattern.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, Integer, nil] :n (nil) Number of annotation lines to print
+        #
+        #       Pass `true` to print the first annotation line, or an integer to print that
+        #       many lines. If the tag is not annotated, the commit message is displayed instead.
+        #
+        #     @option options [String, Array<String>] :sort (nil) Sort tags by the specified
+        #       key(s)
+        #
+        #       Prefix `-` to sort in descending order. Common keys: 'refname',
+        #       '-refname', 'creatordate', '-creatordate', 'version:refname' (for semantic
+        #       version sorting).
+        #
+        #     @option options [Boolean, String, nil] :color (nil) Colorize output per colors
+        #       specified in `--format`
+        #
+        #       Pass `true` for `--color`, or one of `'always'`, `'never'`, `'auto'`.
+        #
+        #     @option options [Boolean, nil] :ignore_case (nil) Sorting and filtering tags are
+        #       case insensitive
+        #
+        #       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
+        #
+        #     @option options [Boolean, String, nil] :column (nil) Display tag listing in columns
+        #
+        #       Pass `true` for `--column` or a comma-separated options string
+        #       (see `column.tag` configuration for syntax) for `--column=<options>`.
+        #
+        #     @option options [Boolean, nil] :no_column (nil) disable column output (`--no-column`)
+        #
+        #     @option options [Boolean, String, nil] :contains (nil) List only tags that contain the
+        #       specified commit
+        #
+        #       Pass `true` to use HEAD, or a commit reference string.
+        #
+        #     @option options [Boolean, String, nil] :no_contains (nil) List only tags that don't contain
+        #       the specified commit
+        #
+        #       Pass `true` to use HEAD, or a commit reference string.
+        #
+        #     @option options [Boolean, String, nil] :merged (nil) List only tags whose commits are
+        #       reachable from the specified commit
+        #
+        #       Pass `true` to use HEAD, or a commit reference string.
+        #
+        #     @option options [Boolean, String, nil] :no_merged (nil) List only tags whose commits are
+        #       not reachable from the specified commit
+        #
+        #       Pass `true` to use HEAD, or a commit reference string.
+        #
+        #     @option options [Boolean, String, nil] :points_at (nil) List only tags that point at the
+        #       specified object
+        #
+        #       Pass `true` to use HEAD, or an object reference string.
+        #
+        #     @option options [String] :format (nil) Output format string for each tag
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git tag --list`
+        #
+        #     @raise [Git::FailedError] if git returns a non-zero exit code
+        #
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Tag
+      # Implements the `git tag --verify` command for verifying tag signatures
+      #
+      # This command verifies the cryptographic signature of the given tag(s).
+      # It requires that the tags were signed with GPG or another supported
+      # signing backend.
+      #
+      # @example Verify a single tag
+      #   verify = Git::Commands::Tag::Verify.new(execution_context)
+      #   verify.call('v1.0.0')
+      #
+      # @example Verify multiple tags
+      #   verify = Git::Commands::Tag::Verify.new(execution_context)
+      #   verify.call('v1.0.0', 'v2.0.0')
+      #
+      # @example Verify with custom format output
+      #   verify = Git::Commands::Tag::Verify.new(execution_context)
+      #   verify.call('v1.0.0', format: '%(refname:short) %(contents:subject)')
+      #
+      # @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 Verify < Git::Commands::Base
+        arguments do
+          literal 'tag'
+          literal '--verify'
+          value_option :format, inline: true
+
+          end_of_options
+
+          operand :tagname, repeatable: true, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   Execute the git tag --verify command to verify tag signatures
+        #
+        #   @overload call(*tagname, **options)
+        #
+        #     @param tagname [Array<String>] one or more tag names to verify
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :format (nil) a format string interpolating
+        #       `%(fieldname)` from the tag ref being shown and the object it points at
+        #
+        #       The format is the same as that of git-for-each-ref(1).
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git tag --verify`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [ArgumentError] if no tagname operands are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+      end
+    end
+  end
+end

data/lib/git/commands/tag.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'tag/create'
+require_relative 'tag/delete'
+require_relative 'tag/list'
+require_relative 'tag/verify'
+
+module Git
+  module Commands
+    # Commands for managing tags via `git tag`
+    #
+    # This module contains command classes split by tag operation:
+    #
+    # - {Tag::Create} — create a new lightweight or annotated tag
+    # - {Tag::Delete} — delete one or more tags (`--delete`)
+    # - {Tag::List} — list tags with optional filtering (`--list`)
+    # - {Tag::Verify} — verify GPG signatures of tags (`--verify`)
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-tag git-tag documentation
+    #
+    module Tag
+    end
+  end
+end

data/lib/git/commands/update_ref/batch.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module UpdateRef
+      # Performs batch ref updates via the `git update-ref --stdin` protocol
+      #
+      # Reads update/create/delete/verify instructions from stdin. By default
+      # all modifications are applied atomically — either all succeed or none do.
+      # Pass `batch_updates: true` to switch to non-atomic mode, where each
+      # instruction is applied independently and individual failures are reported
+      # without aborting the remaining updates (requires git 2.47+).
+      #
+      # This is the batch counterpart to the single-ref {UpdateRef::Update} and
+      # {UpdateRef::Delete} commands.
+      #
+      # Instructions are newline-delimited by default; pass `z: true` to switch
+      # to NUL-delimited format. See the
+      # {https://git-scm.com/docs/git-update-ref#_stdin_mode git-update-ref}
+      # documentation for the full instruction grammar.
+      #
+      # @example Atomically update two refs
+      #   cmd = Git::Commands::UpdateRef::Batch.new(execution_context)
+      #   cmd.call(
+      #     'update refs/heads/main newsha oldsha',
+      #     'delete refs/heads/old-branch'
+      #   )
+      #
+      # @example NUL-delimited instructions
+      #   cmd = Git::Commands::UpdateRef::Batch.new(execution_context)
+      #   cmd.call("update refs/heads/main\0newsha\0oldsha", z: true)
+      #
+      # @example Non-atomic batch (independent failures)
+      #   cmd = Git::Commands::UpdateRef::Batch.new(execution_context)
+      #   cmd.call(
+      #     'update refs/heads/main newsha oldsha',
+      #     'delete refs/heads/old-branch',
+      #     batch_updates: true
+      #   )
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-update-ref/2.53.0
+      #
+      # @see Git::Commands::UpdateRef
+      #
+      # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+      #
+      # @api private
+      #
+      class Batch < Git::Commands::Base
+        arguments do
+          literal 'update-ref'
+
+          # Reflog message appended to each update entry
+          value_option :m
+
+          # Overwrite refs themselves rather than following symbolic refs
+          flag_option :no_deref
+
+          # Read instructions from stdin
+          literal '--stdin'
+
+          # Use NUL-delimited input instead of newline-delimited
+          flag_option :z
+
+          # Allow individual updates to fail without aborting the batch
+          flag_option :batch_updates
+
+          execution_option :timeout
+
+          # Instructions written to stdin, not argv.
+          # Using skip_cli: true because these values are fed via stdin —
+          # git never sees them as CLI arguments so Ruby must enforce
+          # the constraint below.
+          operand :instructions, repeatable: true, skip_cli: true, required: true
+        end
+
+        # @overload call(*instructions, **options)
+        #
+        #   Execute `git update-ref --stdin` with instructions fed via stdin
+        #
+        #   @param instructions [Array<String>] one or more instruction lines
+        #     written to stdin of the `git update-ref` process
+        #
+        #     Each element is written as a separate line (or NUL-terminated
+        #     record when `z: true`). The instruction format is documented in
+        #     the
+        #     {https://git-scm.com/docs/git-update-ref#_stdin_mode git-update-ref}
+        #     man page.
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [String] :m (nil) a reflog message for each
+        #     update
+        #
+        #   @option options [Boolean, nil] :no_deref (nil) overwrite refs
+        #     themselves rather than following symbolic refs
+        #
+        #   @option options [Boolean, nil] :z (nil) use NUL-delimited input
+        #     instead of newline-delimited
+        #
+        #   @option options [Boolean, nil] :batch_updates (nil) allow individual updates to fail
+        #
+        #     When set, each instruction is applied independently; failed instructions are
+        #     reported but do not abort the remaining updates. System-level failures (I/O,
+        #     memory) still abort all updates.
+        #
+        #   @option options [Numeric] :timeout (nil) abort the command after this many seconds
+        #
+        #   @return [Git::CommandLineResult] the result of calling
+        #     `git update-ref --stdin`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [ArgumentError] if no instructions are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        def call(*, **)
+          bound = args_definition.bind(*, **)
+          validate_version!
+          with_stdin(build_stdin(bound)) do |reader|
+            result = @execution_context.command_capturing(
+              *bound, in: reader, **bound.execution_options, raise_on_failure: false
+            )
+            validate_exit_status!(result)
+            result
+          end
+        end
+
+        private
+
+        def build_stdin(bound)
+          delimiter = bound.z? ? "\0" : "\n"
+          Array(bound.instructions).map { |i| "#{i}#{delimiter}" }.join
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module UpdateRef
+      # Deletes a ref via `git update-ref -d`
+      #
+      # Removes the named ref after optionally verifying it still contains
+      # `<oldvalue>`. Follows symbolic refs by default unless `no_deref: true`
+      # is given.
+      #
+      # @example Delete a branch ref
+      #   cmd = Git::Commands::UpdateRef::Delete.new(execution_context)
+      #   cmd.call('refs/heads/old-branch')
+      #
+      # @example Delete with old-value verification
+      #   cmd = Git::Commands::UpdateRef::Delete.new(execution_context)
+      #   cmd.call('refs/heads/old-branch', 'expected-sha')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-update-ref/2.53.0
+      #
+      # @see Git::Commands::UpdateRef
+      #
+      # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+      #
+      # @api private
+      #
+      class Delete < Git::Commands::Base
+        arguments do
+          literal 'update-ref'
+
+          # Reflog message appended to the delete entry
+          value_option :m
+
+          # Overwrite the ref itself rather than following symbolic refs
+          flag_option :no_deref
+
+          # Delete the named ref
+          literal '-d'
+
+          execution_option :timeout
+
+          end_of_options
+
+          # The ref to delete (e.g. `refs/heads/old-branch`)
+          operand :ref, required: true
+
+          # Optional expected current value — the delete is rejected if
+          # the ref does not currently point to this object
+          operand :oldvalue
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(ref, oldvalue = nil, **options)
+        #
+        #     Execute the `git update-ref -d` command
+        #
+        #     @param ref [String] the ref to delete
+        #       (e.g. `refs/heads/old-branch`)
+        #
+        #     @param oldvalue [String, nil] (nil) expected current value of
+        #       the ref
+        #
+        #       When provided, the delete is rejected unless the ref
+        #       currently points to this object.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :m (nil) a reflog message for
+        #       the deletion
+        #
+        #     @option options [Boolean, nil] :no_deref (nil) overwrite the ref
+        #       itself rather than following symbolic refs
+        #
+        #     @option options [Numeric] :timeout (nil) abort the command after this many
+        #       seconds
+        #
+        #     @return [Git::CommandLineResult] the result of calling
+        #       `git update-ref -d`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @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/update_ref/update.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module UpdateRef
+      # Updates a ref to point to a new object via `git update-ref`
+      #
+      # Stores `<newvalue>` in `<ref>`, optionally verifying that the current
+      # value matches `<oldvalue>` before performing the update. Follows
+      # symbolic refs by default unless `no_deref: true` is given.
+      #
+      # @example Update a branch ref
+      #   cmd = Git::Commands::UpdateRef::Update.new(execution_context)
+      #   cmd.call('refs/heads/main', 'abc1234')
+      #
+      # @example Update with old-value verification
+      #   cmd = Git::Commands::UpdateRef::Update.new(execution_context)
+      #   cmd.call('refs/heads/main', 'newsha', 'oldsha')
+      #
+      # @example Update with a reflog message
+      #   cmd = Git::Commands::UpdateRef::Update.new(execution_context)
+      #   cmd.call('refs/heads/main', 'abc1234', m: 'reset to upstream')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-update-ref/2.53.0
+      #
+      # @see Git::Commands::UpdateRef
+      #
+      # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+      #
+      # @api private
+      #
+      class Update < Git::Commands::Base
+        arguments do
+          literal 'update-ref'
+
+          # Reflog message appended to the update entry
+          value_option :m
+
+          # Overwrite the ref itself rather than following symbolic refs
+          flag_option :no_deref
+
+          # Create a reflog for the ref even if one would not ordinarily
+          # be created
+          flag_option :create_reflog
+
+          execution_option :timeout
+
+          end_of_options
+
+          # The ref to update (e.g. `refs/heads/main`)
+          operand :ref, required: true
+
+          # The new object name to store in the ref
+          operand :newvalue, required: true
+
+          # Optional expected current value — the update is rejected if
+          # the ref does not currently point to this object
+          operand :oldvalue
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(ref, newvalue, oldvalue = nil, **options)
+        #
+        #     Execute the `git update-ref` command
+        #
+        #     @param ref [String] the ref to update (e.g. `refs/heads/main`)
+        #
+        #     @param newvalue [String] the new object name to store
+        #
+        #     @param oldvalue [String, nil] (nil) expected current value of
+        #       the ref
+        #
+        #       When provided, the update is rejected unless the ref
+        #       currently points to this object. Use 40 `"0"` characters
+        #       or an empty string to assert the ref does not yet exist.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :m (nil) a reflog message for
+        #       the update
+        #
+        #     @option options [Boolean, nil] :no_deref (nil) overwrite the ref
+        #       itself rather than following symbolic refs
+        #
+        #     @option options [Boolean, nil] :create_reflog (nil) create a reflog
+        #       even if one would not ordinarily be created
+        #
+        #     @option options [Numeric] :timeout (nil) abort the command after this many
+        #       seconds
+        #
+        #     @return [Git::CommandLineResult] the result of calling
+        #       `git update-ref`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [ArgumentError] if the ref or newvalue operand is
+        #       missing
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/update_ref.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'update_ref/batch'
+require_relative 'update_ref/delete'
+require_relative 'update_ref/update'
+
+module Git
+  module Commands
+    # Commands for safely updating ref values via `git update-ref`
+    #
+    # This module contains command classes split by invocation mode:
+    #
+    # - {UpdateRef::Update} — set a ref to a new value (the default mode);
+    #   also supports verifying the old value before updating
+    # - {UpdateRef::Delete} — delete a ref (`-d` flag); optionally verifies
+    #   the current value before deleting
+    # - {UpdateRef::Batch} — read update/create/delete/verify instructions
+    #   from stdin (`--stdin`); all modifications are applied atomically
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+    #
+    # @example Update a branch ref to a new commit SHA
+    #   cmd = Git::Commands::UpdateRef::Update.new(lib)
+    #   cmd.call('refs/heads/main', 'abc1234')
+    #
+    # @example Delete a ref
+    #   cmd = Git::Commands::UpdateRef::Delete.new(lib)
+    #   cmd.call('refs/heads/old-branch')
+    #
+    # @example Atomically update multiple refs via stdin
+    #   cmd = Git::Commands::UpdateRef::Batch.new(execution_context)
+    #   cmd.call(
+    #     'update refs/heads/main newsha oldsha',
+    #     'delete refs/heads/old'
+    #   )
+    #
+    module UpdateRef
+    end
+  end
+end

data/lib/git/commands/version.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Wrapper for the `git version` command
+    #
+    # Prints the git suite version.
+    #
+    # @example Basic usage
+    #   version = Git::Commands::Version.new(execution_context)
+    #   result = version.call
+    #   result.stdout #=> "git version 2.42.0"
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-version/2.53.0
+    #
+    # @see Git::Commands
+    #
+    # @see https://git-scm.com/docs/git-version git-version documentation
+    #
+    # @api private
+    #
+    class Version < Git::Commands::Base
+      # Skip version validation for this command since this command is used to
+      # determine the version.
+      #
+      skip_version_validation
+
+      arguments do
+        literal 'version'
+        flag_option :build_options
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(**options)
+      #
+      #     Execute the `git version` command.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :build_options (nil) include build options in the output
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git version`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+    end
+  end
+end