git 1.19.1 → 5.5.0

data/lib/git/commands/cat_file/raw.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module CatFile
+      # Queries a single git object by name passed as a CLI argument
+      #
+      # Runs `git cat-file` in non-batch mode. Exactly one mode flag or a `<type>`
+      # operand must be supplied:
+      #
+      # - **`-e`** — exit 0 if the object exists and is valid, exit 1 otherwise;
+      #   no output is written to stdout
+      # - **`-t`** — print the object type (`blob`, `tree`, `commit`, or `tag`)
+      # - **`-s`** — print the object size in bytes
+      # - **`-p`** — pretty-print the object content (format varies by type)
+      # - **`<type>`** — print the raw content after validating the object is of
+      #   the given type (or trivially dereferenceable to it)
+      #
+      # For queries across multiple objects, use {CatFile::Batch}.
+      # For filter-processed content, use {CatFile::Filtered}.
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-cat-file/2.53.0
+      #
+      # @see Git::Commands::CatFile
+      #
+      # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
+      #
+      # @api private
+      #
+      class Raw < Base
+        arguments do
+          literal 'cat-file'
+
+          # Exit 0 if object exists and is valid; exit 1 otherwise (no output)
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--e
+          flag_option :e
+
+          # Pretty-print the object content based on its type
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--p
+          flag_option :p
+
+          # Print the object type (`blob`, `tree`, `commit`, or `tag`)
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--t
+          flag_option :t
+
+          # Print the object size in bytes
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--s
+          flag_option :s
+
+          # Allow -t and -s to query broken or corrupt objects of unknown type.
+          # Deprecated and removed in v6.0.0 (see issue 1709); passing it emits a
+          # deprecation warning. Git 2.28-2.49 honors it with -t and -s and rejects
+          # it in other modes; git 2.50+ accepts and ignores it everywhere (the
+          # unknown-type feature was removed).
+          # See https://git-scm.com/docs/git-cat-file/2.49.0#Documentation/git-cat-file.txt---allow-unknown-type
+          flag_option :allow_unknown_type
+
+          # Map committer/author identities through the mailmap before reporting size
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---use-mailmap
+          flag_option :use_mailmap, negatable: true
+
+          # Stream stdout to this IO object instead of buffering in memory.
+          # When provided, {#call} dispatches to the streaming execution path.
+          execution_option :out
+
+          # Abort the command after this many seconds.
+          execution_option :timeout
+
+          end_of_options
+
+          # Expected object type — one of `commit`, `tree`, `blob`, or `tag`.
+          # Git also accepts a type that the object is trivially dereferenceable to
+          # (e.g. `tree` against a commit ref, `blob` against a tag that points to one).
+          operand :type
+
+          # Object name: SHA, ref, `HEAD`, treeish path reference, etc.
+          operand :object, required: true
+        end
+
+        # Execute `git cat-file` for a single object.
+        #
+        # Exactly one mode must be selected: pass one of `e: true`, `p: true`,
+        # `t: true`, `s: true`, or a positional `type` argument.
+        #
+        # @overload call(object, e: true, **options)
+        #   Check whether an object exists
+        #
+        #   @param object [String] object name (SHA, ref, `HEAD`, treeish path, etc.)
+        #
+        #   @param e [Boolean] enable existence-check mode
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
+        #
+        #     Exit status 0 means the object exists; exit status 1 means it does not
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a status other than 0 or 1
+        #
+        # @overload call(object, t: true, **options)
+        #   Print the object type
+        #
+        #   @param object [String] object name
+        #
+        #   @param t [Boolean] enable type-query mode
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
+        #     unknown type on git 2.28-2.49
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning. Git 2.50 removed the unknown-type feature and accepts this
+        #     flag as a no-op.
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
+        #
+        #     Stdout contains the object type string
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if the object does not exist
+        #
+        # @overload call(object, s: true, **options)
+        #   Print the object size in bytes
+        #
+        #   @param object [String] object name
+        #
+        #   @param s [Boolean] enable size-query mode
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
+        #     unknown type on git 2.28-2.49
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning. Git 2.50 removed the unknown-type feature and accepts this
+        #     flag as a no-op.
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
+        #
+        #     Stdout contains the object size as a decimal string
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if the object does not exist
+        #
+        # @overload call(object, p: true, **options)
+        #   Pretty-print the object content
+        #
+        #   @param object [String] object name
+        #
+        #   @param p [Boolean] enable pretty-print mode
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
+        #
+        #     Stdout contains the formatted object content
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if the object does not exist
+        #
+        # @overload call(type, object, **options)
+        #   Print the raw content, validating the object is of the given type
+        #
+        #   @param type [String] expected object type — `commit`, `tree`, `blob`, or `tag`
+        #
+        #   @param object [String] object name
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
+        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
+        #     on git 2.50 and later
+        #
+        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
+        #     warning.
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
+        #
+        #     Stdout contains the raw object content
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if the object does not exist or is not of the
+        #     given type
+        #
+        #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
+        #
+        def call(*, **)
+          warn_allow_unknown_type_deprecated(**)
+          bound = args_definition.bind(*, **)
+          validate_version!(bound.execution_options)
+          result = execute_command(bound)
+
+          # `-e` treats exit 1 as a meaningful result (object not found), but any other
+          # non-zero exit (e.g. 128 for a corrupt object database) is still a failure.
+          # All other modes treat every non-zero exit as a failure.
+          allowed = result.status.success? || (bound.e? && result.status.exitstatus == 1)
+          raise Git::FailedError, result unless allowed
+
+          result
+        end
+
+        private
+
+        # Emit the deprecation warning when the `allow_unknown_type` keyword is passed
+        #
+        # Keys on the keyword being present, whatever its value: `false` and `nil`
+        # suppress the flag but still name a deprecated option.
+        #
+        # @param options [Hash] the keyword arguments passed to {#call}
+        #
+        # @option options [Boolean, nil] :allow_unknown_type the deprecated option;
+        #   any value, including `false` and `nil`, triggers the warning
+        #
+        # @return [void]
+        #
+        def warn_allow_unknown_type_deprecated(**options)
+          return unless options.key?(:allow_unknown_type)
+
+          Git::Deprecation.warn(
+            'The allow_unknown_type option of Git::Commands::CatFile::Raw is deprecated ' \
+            'and will be removed in v6.0.0. Git 2.50 removed the unknown-type feature ' \
+            'and accepts --allow-unknown-type as a no-op.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/cat_file.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'cat_file/batch'
+require_relative 'cat_file/filtered'
+require_relative 'cat_file/raw'
+
+module Git
+  module Commands
+    # Commands for reading git object store content via `git cat-file`
+    #
+    # This module contains command classes split by invocation protocol:
+    #
+    # - {CatFile::Raw} — single object as a CLI argument; raw content, type, size, or
+    #   existence check (`-e`, `-t`, `-s`, `-p`, `<type>`)
+    # - {CatFile::Filtered} — single object as a CLI argument; content after
+    #   `.gitattributes` filter processing (`--textconv`, `--filters`)
+    # - {CatFile::Batch} — objects fed via stdin; all batch streaming modes
+    #   (`--batch`, `--batch-check`, `--batch-command`)
+    #
+    # @example Check whether an object exists
+    #   cmd = Git::Commands::CatFile::Raw.new(lib)
+    #   result = cmd.call('HEAD', e: true)
+    #   result.status.exitstatus  # => 0 (exists) or 1 (not found)
+    #
+    # @example Pretty-print a single object
+    #   cmd = Git::Commands::CatFile::Raw.new(lib)
+    #   result = cmd.call('HEAD', p: true)
+    #   result.stdout
+    #   # => "tree abc1234...\nauthor ...\n\nCommit message\n"
+    #
+    # @example Fetch content after working-tree filters
+    #   cmd = Git::Commands::CatFile::Filtered.new(lib)
+    #   result = cmd.call('HEAD:README.md', filters: true)
+    #   result.stdout
+    #
+    # @example Fetch metadata for several objects via batch
+    #   cmd = Git::Commands::CatFile::Batch.new(lib)
+    #   result = cmd.call('HEAD', 'v1.0', batch_check: true)
+    #   result.stdout
+    #   # => "abc1234... commit 250\nabc5678... tag 143\n"
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
+    #
+    # @api private
+    #
+    module CatFile
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Checkout
+      # Implements the `git checkout` command for switching branches
+      #
+      # This command switches branches by updating the index and working tree
+      # to match the specified branch, and updating HEAD to point to that branch.
+      # It can also create new branches with the `-b` or `-B` options.
+      #
+      # @example Typical usage
+      #   checkout = Git::Commands::Checkout::Branch.new(execution_context)
+      #   checkout.call('main')
+      #   checkout.call(b: 'feature-branch')
+      #   checkout.call('origin/main', b: 'feature-branch', track: true)
+      #   checkout.call('abc123', detach: true)
+      #   checkout.call('main', force: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-checkout/2.53.0
+      #
+      # @see Git::Commands::Checkout
+      #
+      # @see https://git-scm.com/docs/git-checkout git-checkout
+      #
+      # @api private
+      #
+      class Branch < Git::Commands::Base
+        arguments do
+          literal 'checkout'
+          flag_option %i[quiet q]
+          flag_option :progress, negatable: true
+          flag_option %i[force f]
+          value_option :b
+          value_option :B
+          flag_or_value_option %i[track t], negatable: true, inline: true
+          flag_option :guess, negatable: true
+          flag_option :l
+          flag_option %i[detach d]
+          value_option :orphan
+          flag_option %i[merge m]
+          flag_option :ignore_other_worktrees
+          flag_option :overwrite_ignore, negatable: true
+
+          # --recurse-submodules is technically available but has no effect on branch
+          # switching in older git versions. Included for completeness per the man page.
+          flag_option :recurse_submodules, negatable: true
+
+          execution_option :chdir
+
+          operand :branch
+        end
+
+        # @overload call(branch = nil, **options)
+        #
+        #     Execute the git checkout command for branch switching
+        #
+        #     @param branch [String, nil] the branch name, commit SHA, or ref to check
+        #       out; when used with branch creation options (`:b`, `:B`, `:orphan`)
+        #       this becomes the start point
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress feedback messages
+        #
+        #       Alias: `:q`
+        #
+        #     @option options [Boolean, nil] :progress (nil) force progress reporting even
+        #       when not attached to a terminal (`--progress`)
+        #
+        #     @option options [Boolean, nil] :no_progress (nil) disable progress reporting
+        #       even when attached to a terminal (`--no-progress`)
+        #
+        #     @option options [Boolean, nil] :force (nil) proceed even if the index or
+        #       working tree differs from HEAD; discards local changes and untracked
+        #       files that are in the way
+        #
+        #       Alias: `:f`
+        #
+        #     @option options [String] :b (nil) create a new branch with this name and
+        #       switch to it; the positional `branch` argument becomes the start point
+        #
+        #     @option options [String] :B (nil) like `:b`, but reset the branch to the
+        #       start point if it already exists
+        #
+        #     @option options [Boolean, String, nil] :track (nil) set up upstream tracking
+        #       configuration; `true` emits `--track`, `'direct'` emits
+        #       `--track=direct`, `'inherit'` emits `--track=inherit` (`--track`)
+        #
+        #       Alias: `:t`
+        #
+        #     @option options [Boolean, nil] :no_track (nil) do not set up branch tracking
+        #       even if `branch.autoSetupMerge` is configured (`--no-track`)
+        #
+        #     @option options [Boolean, nil] :guess (nil) automatically create and check out
+        #       a local branch from a uniquely matching remote-tracking branch
+        #       (`--guess`)
+        #
+        #     @option options [Boolean, nil] :no_guess (nil) disable automatic remote branch
+        #       matching (`--no-guess`)
+        #
+        #     @option options [Boolean, nil] :l (nil) create the new branch's reflog
+        #
+        #     @option options [Boolean, nil] :detach (nil) detach HEAD at the specified
+        #       commit rather than pointing a branch at it
+        #
+        #       Alias: `:d`
+        #
+        #     @option options [String] :orphan (nil) create a new unborn branch with no
+        #       history; the positional `branch` argument becomes the start point
+        #
+        #     @option options [Boolean, nil] :merge (nil) perform a three-way merge when
+        #       local modifications conflict with the target branch
+        #
+        #       Alias: `:m`
+        #
+        #     @option options [Boolean, nil] :ignore_other_worktrees (nil) check out the
+        #       branch even if it is already in use by another worktree
+        #
+        #     @option options [Boolean, nil] :overwrite_ignore (nil) silently overwrite
+        #       ignored files when switching branches (`--overwrite-ignore`)
+        #
+        #     @option options [Boolean, nil] :no_overwrite_ignore (nil) abort the checkout
+        #       if ignored files would be overwritten (`--no-overwrite-ignore`)
+        #
+        #     @option options [Boolean, nil] :recurse_submodules (nil) update all active
+        #       submodule working trees to match the new branch
+        #       (`--recurse-submodules`)
+        #
+        #     @option options [Boolean, nil] :no_recurse_submodules (nil) do not update
+        #       submodule working trees when switching branches
+        #       (`--no-recurse-submodules`)
+        #
+        #     @option options [String] :chdir (nil) change to this directory before
+        #       running git; not passed to the git CLI
+        #
+        #     @return [Git::CommandLine::Result] the result of calling `git checkout`
+        #
+        #     @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/checkout/files.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Checkout
+      # Implements the `git checkout` command for restoring working tree files
+      #
+      # This command replaces files in the working tree with versions from
+      # the index (when tree_ish is nil) or a specified tree-ish (commit,
+      # branch, tag, etc.).
+      #
+      # @example Restore working tree files
+      #   files = Git::Commands::Checkout::Files.new(execution_context)
+      #   files.call(pathspec: ['lib/foo.rb'])                             # from the index
+      #   files.call('HEAD~1', pathspec: ['lib/foo.rb'])                   # from a specific commit
+      #   files.call('main', pathspec: %w[lib/foo.rb lib/bar.rb])          # from a branch
+      #   files.call(pathspec: ['conflicted.txt'], ours: true)             # resolve conflict (ours)
+      #   files.call('main', pathspec_from_file: 'paths.txt')              # paths from a file
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-checkout/2.53.0
+      #
+      # @see Git::Commands::Checkout
+      #
+      # @see https://git-scm.com/docs/git-checkout git-checkout
+      #
+      # @api private
+      #
+      class Files < Git::Commands::Base
+        arguments do
+          literal 'checkout'
+          flag_option %i[force f]
+          flag_option :ours
+          flag_option :theirs
+          flag_option %i[merge m]
+          value_option :conflict, inline: true
+          flag_option :overlay, negatable: true
+          flag_option :ignore_skip_worktree_bits
+          value_option :pathspec_from_file, inline: true
+          flag_option :pathspec_file_nul
+
+          execution_option :chdir
+
+          operand :tree_ish
+          end_of_options
+          value_option :pathspec, as_operand: true, repeatable: true
+        end
+
+        # @overload call(tree_ish = nil, **options)
+        #
+        #     Execute the git checkout command for restoring files
+        #
+        #     @param tree_ish [String, nil] The commit, branch, or tree to restore
+        #       files from
+        #
+        #       When `nil`, files are restored from the index
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :force (nil) ignore unmerged entries
+        #
+        #       Alias: `:f`
+        #
+        #     @option options [Boolean, nil] :ours (nil) for unmerged paths, check out
+        #       stage #2 (our version)
+        #
+        #     @option options [Boolean, nil] :theirs (nil) for unmerged paths, check out
+        #       stage #3 (their version)
+        #
+        #     @option options [Boolean, nil] :merge (nil) recreate the conflicted merge in
+        #       the specified paths; cannot be used when checking out from a tree-ish
+        #
+        #       Alias: `:m`
+        #
+        #     @option options [String] :conflict (nil) conflict marker style; valid
+        #       values are `'merge'`, `'diff3'`, and `'zdiff3'`
+        #
+        #     @option options [Boolean, nil] :overlay (nil) never remove files from the
+        #       index or working tree that are not present in the tree-ish (`--overlay`)
+        #
+        #     @option options [Boolean, nil] :no_overlay (nil) remove files not present
+        #       in the tree-ish from the index and working tree (`--no-overlay`)
+        #
+        #     @option options [Boolean, nil] :ignore_skip_worktree_bits (nil) in sparse
+        #       checkout mode, ignore sparse patterns and update all files matched by
+        #       pathspec
+        #
+        #     @option options [String] :pathspec_from_file (nil) read pathspec from
+        #       this file; pass `'-'` to read from stdin
+        #
+        #     @option options [Boolean, nil] :pathspec_file_nul (nil) with
+        #       `:pathspec_from_file`, separate pathspec elements with NUL instead of
+        #       newline
+        #
+        #     @option options [Array<String>, String] :pathspec (nil) the files or
+        #       directories to restore
+        #
+        #     @option options [String] :chdir (nil) change to this directory before
+        #       running git; not passed to the git CLI
+        #
+        #     @return [Git::CommandLine::Result] the result of calling `git checkout`
+        #
+        #     @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/checkout.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'checkout/branch'
+require_relative 'checkout/files'
+
+module Git
+  module Commands
+    # Commands for switching branches and restoring files via `git checkout`
+    #
+    # This module contains command classes split by checkout mode:
+    #
+    # - {Checkout::Branch} — switch branches or create and switch to a new branch
+    # - {Checkout::Files} — restore working tree files from a given tree-ish
+    #
+    # @example Switch to an existing branch
+    #   cmd = Git::Commands::Checkout::Branch.new(lib)
+    #   cmd.call('main')
+    #
+    # @example Create and switch to a new branch
+    #   cmd = Git::Commands::Checkout::Branch.new(lib)
+    #   cmd.call('main', b: 'feature/new-feature')
+    #
+    # @example Restore a file from the index (discard uncommitted changes)
+    #   cmd = Git::Commands::Checkout::Files.new(lib)
+    #   cmd.call(pathspec: ['lib/my_file.rb'])
+    #
+    # @example Restore a file from a specific branch
+    #   cmd = Git::Commands::Checkout::Files.new(lib)
+    #   cmd.call('main', pathspec: ['lib/my_file.rb'])
+    #
+    # @see https://git-scm.com/docs/git-checkout git-checkout documentation
+    #
+    # @api private
+    #
+    module Checkout
+    end
+  end
+end