git 1.19.1 → 5.5.0

data/lib/git/commands/show_ref/exclude_existing.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module ShowRef
+      # Stdin filter mode for `git show-ref --exclude-existing`
+      #
+      # Reads ref names from the positional arguments, passes them to git's stdin,
+      # and outputs only those refs that do NOT already exist in the local repository.
+      # Useful for determining which remote refs would be new if fetched.
+      #
+      # Pass `exclude_existing: 'refs/heads/'` to limit filtering to refs matching
+      # the given prefix pattern. By default (no pattern), all refs are evaluated.
+      #
+      # For standard ref listing, use {Git::Commands::ShowRef::List}.
+      # For strict per-ref verification, use {Git::Commands::ShowRef::Verify}.
+      # For a boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.
+      #
+      # @example Filter refs that do not exist locally
+      #   cmd = Git::Commands::ShowRef::ExcludeExisting.new(execution_context)
+      #   result = cmd.call('refs/heads/main', 'refs/heads/feature')
+      #   result.stdout  # => "abc1234 refs/heads/feature\n"
+      #
+      # @example Limit filtering to a prefix pattern
+      #   cmd = Git::Commands::ShowRef::ExcludeExisting.new(execution_context)
+      #   result = cmd.call('refs/heads/main', exclude_existing: 'refs/heads/')
+      #   # refs/heads/main already exists locally, so git echoes nothing
+      #   result.stdout  # => ""
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
+      #
+      # @see Git::Commands::ShowRef
+      #
+      # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
+      #
+      # @api private
+      #
+      class ExcludeExisting < Git::Commands::Base
+        arguments do
+          literal 'show-ref'
+
+          # Mode selector: pass `true` (default) to test all refs, or a pattern
+          # string to restrict testing to refs whose names start with the pattern.
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---exclude-existingltpatterngt
+          flag_or_value_option :exclude_existing, inline: true
+
+          execution_option :timeout
+
+          # Ref names to pass to stdin, one per line. Never emitted in git argv.
+          operand :ref, repeatable: true, skip_cli: true
+        end
+
+        # @overload call(*ref, exclude_existing: true, **options)
+        #
+        #   Execute `git show-ref --exclude-existing` to filter ref names against the
+        #   local repository
+        #
+        #   Each ref is passed to git's stdin. Git writes back only
+        #   the refs that do not already exist locally.
+        #
+        #   @param ref [Array<String>] ref names to test
+        #
+        #   @param exclude_existing [true, String] filter mode selector
+        #
+        #     Pass `true` (default) to test all refs, or a non-empty pattern string to
+        #     restrict testing to refs whose names start with the pattern
+        #     (e.g. `'refs/heads/'`). Passing `false` or `nil` raises `ArgumentError`.
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
+        #
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git show-ref --exclude-existing`
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def call(*, exclude_existing: true, **)
+          unless exclude_existing == true || (exclude_existing.is_a?(String) && !exclude_existing.empty?)
+            raise ArgumentError,
+                  ":exclude_existing must be true or a non-empty String, got #{exclude_existing.inspect}"
+          end
+
+          bound = args_definition.bind(*, exclude_existing: exclude_existing, **)
+          validate_version!(bound.execution_options)
+          stdin = Array(bound.ref).map { |r| "#{r}\n" }.join
+          with_stdin(stdin) { |reader| run_filter(bound, reader) }
+        end
+
+        private
+
+        # Run the bound show-ref command, supplying ref names to git via stdin
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound argument list
+        #
+        # @param reader [IO] readable IO connected to git's stdin
+        #
+        # @return [Git::CommandLine::Result] the result of calling
+        #   `git show-ref --exclude-existing`
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def run_filter(bound, reader)
+          result = @execution_context.command_capturing(
+            *bound,
+            in: reader,
+            **bound.execution_options,
+            raise_on_failure: false
+          )
+          validate_exit_status!(result)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/show_ref/exists.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module ShowRef
+      # Checks whether a single ref exists via `git show-ref --exists`
+      #
+      # Returns without raising for three exit-status outcomes:
+      #
+      # - **exit 0** — the ref exists in the local repository
+      # - **exit 2** — the ref does not exist (a normal result for an existence check)
+      # - **exit 1** — a lookup error occurred (e.g. malformed ref name)
+      #
+      # Callers inspect `result.status.exitstatus` to distinguish the three states.
+      # Unlike {ShowRef::Verify}, this mode never prints any output.
+      #
+      # For standard ref listing, use {ShowRef::List}.
+      # For strict per-ref verification with output, use {ShowRef::Verify}.
+      # For stdin-based filtering, use {ShowRef::ExcludeExisting}.
+      #
+      # @example Check whether a branch exists
+      #   cmd = Git::Commands::ShowRef::Exists.new(execution_context)
+      #   result = cmd.call('refs/heads/main')
+      #   result.status.exitstatus  # => 0 (exists) or 2 (not found)
+      #
+      # @note Requires git 2.43 or later
+      #
+      #   Earlier versions do not recognise the `--exists` flag and will exit
+      #   non-zero with an "unknown option" error.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
+      #
+      # @see Git::Commands::ShowRef
+      #
+      # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
+      #
+      # @api private
+      #
+      class Exists < Git::Commands::Base
+        arguments do
+          literal 'show-ref'
+          literal '--exists'
+          execution_option :timeout
+          operand :ref, required: true
+        end
+
+        # Exit status 0 = ref found; 2 = ref not found (expected); 1 = lookup error.
+        # All three are valid results — callers check exitstatus to distinguish them.
+        allow_exit_status 0..2
+
+        # @overload call(ref, **options)
+        #
+        #   Execute `git show-ref --exists` to check whether a ref exists
+        #
+        #   @param ref [String] the fully-qualified ref name to check
+        #     (e.g. `"refs/heads/main"`)
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
+        #
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git show-ref --exists`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
+        #
+        # @api public
+        #
+        def call(*, **)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module ShowRef
+      # Standard ref listing command via `git show-ref`
+      #
+      # Lists refs stored in the local repository together with their associated
+      # commit IDs. When no filters are given, all refs are listed. Filters can
+      # narrow output to heads, tags, or refs matching a given pattern.
+      #
+      # An exit status of 1 is not an error — it indicates that no matching refs
+      # were found. Exit status 0 means at least one match was found.
+      #
+      # For strict per-ref verification, use {Git::Commands::ShowRef::Verify}.
+      # For stdin-based filtering, use {Git::Commands::ShowRef::ExcludeExisting}.
+      # For a simple boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.
+      #
+      # @example List all refs
+      #   cmd = Git::Commands::ShowRef::List.new(execution_context)
+      #   result = cmd.call
+      #   result.stdout  # => "abc1234 refs/heads/main\n..."
+      #
+      # @example List only tags
+      #   cmd = Git::Commands::ShowRef::List.new(execution_context)
+      #   result = cmd.call(tags: true)
+      #
+      # @example List with abbreviated SHA hashes
+      #   cmd = Git::Commands::ShowRef::List.new(execution_context)
+      #   result = cmd.call(hash: 7)
+      #
+      # @example Match a pattern
+      #   cmd = Git::Commands::ShowRef::List.new(execution_context)
+      #   result = cmd.call('v1.0', 'v2.0', tags: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
+      #
+      # @see Git::Commands::ShowRef
+      #
+      # @see https://git-scm.com/docs/git-show-ref
+      #
+      # @api private
+      #
+      class List < Git::Commands::Base
+        arguments do
+          literal 'show-ref'
+
+          # Include the HEAD ref even if it would normally be filtered out
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---head
+          flag_option :head
+
+          # Dereference annotated tags; outputs an additional line per tag with
+          # the de-referenced object SHA followed by `^{}`
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
+          flag_option %i[dereference d]
+
+          # Show only the SHA part of the ref, optionally abbreviated to <n> hex digits;
+          # pass `true` for full-length SHA, or an integer for the abbreviation length
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
+          flag_or_value_option %i[hash s], inline: true
+
+          # Abbreviate the object names to at least <n> hex digits; pass `true` to
+          # use the default abbreviation length, or an integer for an explicit length
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
+          flag_or_value_option :abbrev, inline: true
+
+          # Limit to refs under refs/heads/ only (preferred over :heads on git >= 2.46)
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
+          flag_option :branches
+
+          # Limit to refs under refs/heads/ only (deprecated synonym for :branches in git >= 2.46)
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
+          flag_option :heads
+
+          # Limit to refs under refs/tags/ only
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---tags
+          flag_option :tags
+
+          execution_option :timeout
+
+          end_of_options
+
+          # Optional glob patterns; only refs whose names contain a match are shown.
+          # Patterns are matched against the full ref name (without the leading `refs/`
+          # prefix on older git versions; full path on newer ones).
+          operand :pattern, repeatable: true
+        end
+
+        # Exit status 1 means no refs matched; that is a normal (non-error) outcome
+        allow_exit_status 0..1
+
+        # @overload call(*pattern, **options)
+        #
+        #   Execute `git show-ref` to list matching refs
+        #
+        #   @param pattern [Array<String>] zero or more patterns to filter refs
+        #
+        #     When empty, all refs are listed.
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :head (nil) show the HEAD ref even when filtered
+        #
+        #   @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
+        #     emitting an extra line per tag whose SHA points to the tagged object
+        #
+        #     Alias: `:d`
+        #
+        #   @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part of each ref
+        #
+        #     Pass `true` for full-length SHAs or an integer for the abbreviation length
+        #     (e.g. `hash: 7`).
+        #
+        #     Alias: `:s`
+        #
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
+        #
+        #     Pass `true` for the default length or an integer for a specific length.
+        #
+        #   @option options [Boolean, nil] :branches (nil) limit output to local branches (refs/heads/)
+        #
+        #     Prefer `:branches` over `:heads` on git >= 2.46; `:heads` emits the deprecated
+        #     `--heads` flag.
+        #
+        #   @option options [Boolean, nil] :heads (nil) limit output to refs under refs/heads/
+        #
+        #     Deprecated at the git level in git 2.46. Use `:branches` instead.
+        #
+        #   @option options [Boolean, nil] :tags (nil) limit output to refs under refs/tags/
+        #
+        #   @option options [Numeric] :timeout (nil) abort the command after this many seconds
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git show-ref`
+        #
+        #   @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/show_ref/verify.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module ShowRef
+      # Strict per-ref verification command via `git show-ref --verify`
+      #
+      # Verifies that refs exist by their full canonical name (e.g.
+      # `refs/heads/main`, `refs/tags/v1.0`). Unlike {ShowRef::List}, partial
+      # name matching is not performed. Every named ref must start with `refs/`
+      # (or be `HEAD`); anything else will cause git to exit non-zero.
+      #
+      # When a ref cannot be resolved, git exits 1 and this class raises
+      # {Git::FailedError}. This strict behaviour makes the class suitable for
+      # validating that refs are fully qualified.
+      #
+      # For pattern-based listing, use {ShowRef::List}.
+      # For stdin-based filtering, use {ShowRef::ExcludeExisting}.
+      # For a silent boolean check (git >= 2.43), use {ShowRef::Exists}.
+      #
+      # @example Verify a single ref
+      #   cmd = Git::Commands::ShowRef::Verify.new(execution_context)
+      #   result = cmd.call('refs/heads/main')
+      #   result.stdout  # => "abc1234 refs/heads/main\n"
+      #
+      # @example Verify with hash-only output
+      #   cmd = Git::Commands::ShowRef::Verify.new(execution_context)
+      #   result = cmd.call('refs/heads/main', hash: true)
+      #   result.stdout  # => "abc1234\n"
+      #
+      # @example Silent existence check
+      #   cmd = Git::Commands::ShowRef::Verify.new(execution_context)
+      #   cmd.call('refs/heads/main', quiet: true)  # raises FailedError if not found
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
+      #
+      # @see Git::Commands::ShowRef
+      #
+      # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
+      #
+      # @api private
+      #
+      class Verify < Git::Commands::Base
+        arguments do
+          literal 'show-ref'
+          literal '--verify'
+
+          # Suppress output; useful when you only care whether the ref exists
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---quiet
+          flag_option %i[quiet q]
+
+          # Dereference annotated tags; emit an extra line per tag with SHA^{}
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
+          flag_option %i[dereference d]
+
+          # Show only the SHA; pass `true` for full-length or an integer for abbreviated length
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
+          flag_or_value_option %i[hash s], inline: true
+
+          # Abbreviate object names; pass `true` for default or integer for explicit length
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
+          flag_or_value_option :abbrev, inline: true
+
+          execution_option :timeout
+
+          end_of_options
+
+          # One or more fully-qualified ref names to verify (e.g. `refs/heads/main`)
+          operand :ref, repeatable: true, required: true
+        end
+
+        # @overload call(*ref, **options)
+        #
+        #   Execute `git show-ref --verify` to verify refs by their full name
+        #
+        #   @param ref [Array<String>] one or more fully-qualified ref names
+        #
+        #     Each name must begin with `refs/` (or be `HEAD`). At least one is required.
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :quiet (nil) suppress all output
+        #
+        #     Useful when you only care whether the ref exists.
+        #
+        #     Alias: `:q`
+        #
+        #   @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
+        #     emitting an extra `^{}` line per tag
+        #
+        #     Alias: `:d`
+        #
+        #   @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part
+        #
+        #     Pass `true` for full-length SHAs or an integer for abbreviation length.
+        #
+        #     Alias: `:s`
+        #
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
+        #
+        #     Pass `true` for the default length or an integer for a specific length.
+        #
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git show-ref --verify`
+        #
+        #   @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/show_ref.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'show_ref/exclude_existing'
+require_relative 'show_ref/exists'
+require_relative 'show_ref/list'
+require_relative 'show_ref/verify'
+
+module Git
+  module Commands
+    # Commands for querying git refs via `git show-ref`
+    #
+    # This module contains command classes split by invocation mode:
+    #
+    # - {ShowRef::List} — standard ref listing with optional pattern filtering
+    #   (`git show-ref [options] [<pattern>...]`)
+    # - {ShowRef::Verify} — strict per-ref verification by full refname
+    #   (`git show-ref --verify [options] [<ref>...]`)
+    # - {ShowRef::ExcludeExisting} — stdin-based filter for ref names, excluding
+    #   refs that already exist in the repository
+    #   (`git show-ref --exclude-existing[=<pattern>]`)
+    # - {ShowRef::Exists} — boolean existence check without output (git >= 2.43)
+    #   (`git show-ref --exists <ref>`)
+    #
+    # @example List all refs matching a pattern
+    #   cmd = Git::Commands::ShowRef::List.new(execution_context)
+    #   result = cmd.call('refs/tags/', tags: true)
+    #   result.stdout
+    #   # => "abc1234 refs/tags/v1.0\ndef5678 refs/tags/v2.0\n"
+    #
+    # @example Verify a specific ref
+    #   cmd = Git::Commands::ShowRef::Verify.new(execution_context)
+    #   result = cmd.call('refs/heads/main')
+    #   result.stdout  # => "abc1234 refs/heads/main\n"
+    #
+    # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
+    #
+    # @api private
+    #
+    module ShowRef
+    end
+  end
+end

data/lib/git/commands/stash/apply.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Apply stashed changes to the working directory
+      #
+      # Applies the changes recorded in a stash to the working tree.
+      # Unlike {Pop}, this does not remove the stash from the stash list.
+      #
+      # @example Apply the latest stash
+      #   Git::Commands::Stash::Apply.new(execution_context).call
+      #
+      # @example Apply a specific stash
+      #   Git::Commands::Stash::Apply.new(execution_context).call('stash@\\{2}')
+      #
+      # @example Apply and restore index state
+      #   Git::Commands::Stash::Apply.new(execution_context).call(index: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      class Apply < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'apply'
+          flag_option :index
+          flag_option %i[quiet q]
+          operand :stash
+        end
+
+        # @overload call(**options)
+        #
+        #   Apply the latest stash
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :index (nil) restore the index state as well
+        #
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #     Alias: :q
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        # @overload call(stash, **options)
+        #
+        #   Apply a specific stash
+        #
+        #   @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :index (nil) restore the index state as well
+        #
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #
+        #     Alias: :q
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        # @return [Git::CommandLine::Result] the result of calling `git stash apply`
+        #
+        # @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/stash/branch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Stash
+      # Create a branch from a stash entry
+      #
+      # Creates a new branch starting from the commit at which the stash was
+      # originally created, applies the stashed changes, and then drops the stash
+      # if the changes are applied successfully.
+      #
+      # This is useful if the branch on which you ran `git stash push` has changed
+      # enough that `git stash apply` fails due to conflicts. The new branch will
+      # be created at the commit that was HEAD when the stash was created, so
+      # applying the stash should succeed.
+      #
+      # @example Create branch from latest stash
+      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch')
+      #
+      # @example Create branch from specific stash
+      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch', 'stash@{2}')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
+      class Branch < Git::Commands::Base
+        arguments do
+          literal 'stash'
+          literal 'branch'
+          operand :branchname, required: true
+          operand :stash
+        end
+
+        # @!method call(*)
+        #
+        #   Create a branch from a stash entry
+        #
+        #   @overload call(branchname)
+        #
+        #     Create a branch from the latest stash
+        #
+        #     @param branchname [String] the name of the branch to create (required)
+        #
+        #   @overload call(branchname, stash)
+        #
+        #     Create a branch from a specific stash
+        #
+        #     @param branchname [String] the name of the branch to create (required)
+        #
+        #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git stash branch`
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+      end
+    end
+  end
+end