git 1.19.1 → 5.5.0

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

@@ -0,0 +1,146 @@
+# 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(*pattern, **options)
+        #
+        #   Execute the `git tag --list` command
+        #
+        #   @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', and 'version:refname'.
+        #
+        #   @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) sort and filter tags without
+        #     case sensitivity
+        #
+        #     Alias: :i
+        #
+        #   @option options [Boolean, nil] :omit_empty (nil) skip trailing newlines for
+        #     refs whose formatted output is empty
+        #
+        #   @option options [Boolean, String, nil] :column (nil) display tag listing in
+        #     columns
+        #
+        #     Pass `true` for `--column` or a comma-separated options string 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 do
+        #     not 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::CommandLine::Result] the result of calling `git tag --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/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(*tagname, **options)
+        #
+        #   Execute the `git tag --verify` command to verify tag signatures
+        #
+        #   @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::CommandLine::Result] 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
+        #
+        #   @api public
+        #
+      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`)
+    #
+    # @see https://git-scm.com/docs/git-tag git-tag documentation
+    #
+    # @api private
+    #
+    module Tag
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# 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::CommandLine::Result] 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!(bound.execution_options)
+          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
+
+        # Build stdin payload for `git update-ref --stdin`
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound command arguments
+        #
+        # @return [String] instruction stream with delimiter applied per `z:`
+        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,90 @@
+# 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(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::CommandLine::Result] 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
+        #
+        #   @api public
+        #
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# 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(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::CommandLine::Result] 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
+        #
+        #   @api public
+        #
+      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
+    #
+    # @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'
+    #   )
+    #
+    # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+    #
+    # @api private
+    #
+    module UpdateRef
+    end
+  end
+end

data/lib/git/commands/version.rb

@@ -0,0 +1,60 @@
+# 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
+        execution_option :timeout
+        literal 'version'
+        flag_option :build_options
+      end
+
+      # @overload call(**options)
+      #
+      #   Execute the `git version` command
+      #
+      #   @param options [Hash] command options
+      #
+      #   @option options [Numeric, nil] :timeout (nil) the number of seconds to wait
+      #     for the command to complete; if nil, uses the global timeout from
+      #     {Git::Config}; if 0, no timeout is enforced
+      #
+      #   @option options [Boolean, nil] :build_options (nil) include build options in
+      #     the output
+      #
+      #   @return [Git::CommandLine::Result] 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
+      #
+      # @api public
+      #
+      def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
+    end
+  end
+end