git 4.3.2 → 5.0.0.beta.1

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

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module CatFile
+      # Queries one or more git objects via the batch stdin streaming protocol
+      #
+      # Accepts object names (or commands) written to stdin. Three output modes are
+      # available, selected by passing exactly one of `batch:`, `batch_check:`, or
+      # `batch_command:` as a keyword argument:
+      #
+      # - **`batch: true`** (`--batch`) — for each named object, write a header line
+      #   `<sha> <type> <size>` followed by the raw content bytes and a newline
+      #   separator; missing objects are reported inline as `<name> missing`
+      # - **`batch_check: true`** (`--batch-check`) — for each named object, write
+      #   one metadata line `<sha> <type> <size>`; missing objects as `<name> missing`
+      # - **`batch_command: true`** (`--batch-command`) — enter command-dispatch mode;
+      #   stdin carries named verbs (`contents <object>`, `info <object>`, `flush`),
+      #   allowing content and metadata requests to be interleaved in a single process
+      #
+      # All three modes accept a format string instead of `true` to customise the
+      # per-object output line (e.g. `batch: "%(objectname) %(objecttype) %(objectsize)"`)
+      #
+      # When `batch_all_objects: true` is given instead of object names, git enumerates
+      # the entire object database itself and stdin is not read (incompatible with
+      # `batch_command:`).
+      #
+      # Missing objects never cause a non-zero exit — they are reported inline.
+      #
+      # For single-object queries, use {CatFile::Raw}.
+      # For filter-processed content, use {CatFile::Filtered}.
+      #
+      # @see Git::Commands::CatFile
+      #
+      # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-cat-file/2.53.0
+      #
+      # @api private
+      #
+      class Batch < Base
+        arguments do
+          literal 'cat-file'
+
+          # Full content mode: header + raw bytes + newline separator per object;
+          # accepts a format string to customise the per-object output header
+          # (e.g. `"%(objectname) %(objecttype) %(objectsize)"`)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch
+          flag_or_value_option :batch, inline: true
+
+          # Metadata-only mode: one `<sha> <type> <size>` line per object;
+          # accepts a format string to customise the per-object output line
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-check
+          flag_or_value_option :batch_check, inline: true
+
+          # Command-dispatch mode: stdin carries `contents`/`info`/`flush` verbs;
+          # accepts a format string to customise the output of `info` and `contents` commands
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-command
+          flag_or_value_option :batch_command, inline: true
+
+          # Enumerate all objects in the repository without reading stdin.
+          # Incompatible with `batch_command:`.
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-all-objects
+          flag_option :batch_all_objects
+
+          # Use normal stdio buffering; enables explicit `flush` semantics when used
+          # with `batch_command:` and improves throughput with `batch_check:`
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---buffer
+          flag_option :buffer
+
+          # Follow symlinks inside the repository when traversing tree objects
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---follow-symlinks
+          flag_option :follow_symlinks
+
+          # Allow `--batch-all-objects` to output objects in an arbitrary, potentially
+          # faster order
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---unordered
+          flag_option :unordered
+
+          # Apply textconv filters to blob content (combine with `batch_command:`)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
+          flag_option :textconv
+
+          # Apply the full working-tree filter pipeline (combine with `batch_command:`)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
+          flag_option :filters
+
+          # Map committer/author identities through mailmap for all batch modes
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---use-mailmap
+          flag_option :use_mailmap, negatable: true
+
+          # Omit objects matching the filter spec from the output (batched modes only)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filterltfilter-specgt
+          value_option :filter, inline: true
+
+          # Use NUL-delimited input/output instead of newline-delimited
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--Z
+          flag_option :Z
+
+          # Stream stdout to this IO object instead of buffering in memory.
+          # When provided, {#call} dispatches to the streaming execution path.
+          execution_option :out
+
+          # Object names (or batch-command lines) are 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 cross-argument
+          # constraints below.
+          operand :object, repeatable: true, skip_cli: true
+
+          conflicts :object, :batch_all_objects
+          requires_one_of :object, :batch_all_objects
+        end
+
+        # Execute `git cat-file` in batch stdin-streaming mode.
+        #
+        # Exactly one of `batch:`, `batch_check:`, or `batch_command:` must be selected.
+        # Pass `batch_all_objects: true` instead of object names to enumerate the entire
+        # object database without reading stdin.
+        #
+        # @overload call(*objects, batch: true, **options)
+        #   Stream one or more named objects; return header + content per object
+        #
+        #   @param objects [Array<String>] object names written to stdin
+        #
+        #   @param batch [Boolean, String] enable `--batch` mode; pass a format string
+        #     to customise the per-object output header
+        #     (e.g. `"%(objectname) %(objecttype) %(objectsize)"`)
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :buffer (nil) use normal stdio buffering for better throughput
+        #
+        #   @option options [Boolean, nil] :follow_symlinks (nil) follow symlinks in trees
+        #
+        #   @option options [Boolean, nil] :unordered (nil) output in arbitrary order
+        #
+        #   @option options [Boolean, nil] :textconv (nil) apply textconv filters
+        #
+        #   @option options [Boolean, nil] :filters (nil) apply full working-tree filters
+        #
+        #   @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`)
+        #
+        #   @option options [String] :filter (nil) omit objects matching the given filter spec
+        #
+        #   @option options [Boolean, nil] :Z (nil) use NUL-delimited I/O
+        #
+        #   @option options [#write, nil] :out (nil) stream stdout to this IO object
+        #     instead of buffering in memory; when given, `result.stdout` will be `''`
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #     Stdout contains the batch output stream (or `''` when `out:` is given)
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits non-zero (catastrophic failure only;
+        #     missing objects are reported inline)
+        #
+        # @overload call(*objects, batch_check: true, **options)
+        #   Stream one or more named objects; return one metadata line per object
+        #
+        #   @param objects [Array<String>] object names written to stdin
+        #
+        #   @param batch_check [Boolean, String] enable `--batch-check` mode; pass a
+        #     format string to customise the per-object output line
+        #     (e.g. `"%(objectname) %(objecttype) %(objectsize)"`)
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :buffer (nil) use normal stdio buffering for better
+        #     throughput when processing large numbers of objects
+        #
+        #   @option options [Boolean, nil] :follow_symlinks (nil) follow symlinks in trees
+        #
+        #   @option options [Boolean, nil] :unordered (nil) output in arbitrary order
+        #
+        #   @option options [Boolean, nil] :textconv (nil) apply textconv filters
+        #
+        #   @option options [Boolean, nil] :filters (nil) apply full working-tree filters
+        #
+        #   @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`)
+        #
+        #   @option options [String] :filter (nil) omit objects matching the given filter spec
+        #
+        #   @option options [Boolean, nil] :Z (nil) use NUL-delimited I/O
+        #
+        #   @option options [#write, nil] :out (nil) stream stdout to this IO object
+        #     instead of buffering in memory; when given, `result.stdout` will be `''`
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #     Stdout contains one metadata line per object (or `''` when `out:` is given)
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits non-zero (catastrophic failure only;
+        #     missing objects are reported inline)
+        #
+        # @overload call(*objects, batch_command: true, **options)
+        #   Dispatch mixed `contents`/`info`/`flush` commands via stdin
+        #
+        #   Each element of `objects` is written verbatim as a stdin line — the caller
+        #   is responsible for prefixing lines with the appropriate verb
+        #   (`contents <object>`, `info <object>`, or `flush`).
+        #
+        #   @param objects [Array<String>] pre-formatted command lines to write to stdin
+        #
+        #   @param batch_command [Boolean, String] enable `--batch-command` mode; pass
+        #     a format string to customise the output of `info` and `contents` commands
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :buffer (nil) use normal stdio buffering for better throughput
+        #
+        #   @option options [Boolean, nil] :textconv (nil) apply textconv filters
+        #
+        #   @option options [Boolean, nil] :filters (nil) apply full working-tree filters
+        #
+        #   @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`)
+        #
+        #   @option options [String] :filter (nil) omit objects matching the given filter spec
+        #
+        #   @option options [Boolean, nil] :Z (nil) use NUL-delimited I/O
+        #
+        #   @option options [#write, nil] :out (nil) stream stdout to this IO object
+        #     instead of buffering in memory; when given, `result.stdout` will be `''`
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #     Stdout contains the interleaved command output (or `''` when `out:` is given)
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits non-zero
+        #
+        # @overload call(batch_all_objects: true, batch: true, **options)
+        #   Enumerate all objects in the repository with full content
+        #
+        #   @param batch_all_objects [Boolean] enumerate all objects; stdin is not read
+        #
+        #   @param batch [Boolean, String] enable `--batch` mode; pass a format string
+        #     to customise the per-object output header
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :buffer (nil) use normal stdio buffering for better throughput
+        #
+        #   @option options [Boolean, nil] :unordered (nil) output in arbitrary order
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap for
+        #     commit and tag objects (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @option options [String] :filter (nil) omit objects matching the given filter spec
+        #
+        #   @option options [Boolean, nil] :Z (nil) use NUL-delimited I/O
+        #
+        #   @option options [#write, nil] :out (nil) stream stdout to this IO object
+        #     instead of buffering in memory; when given, `result.stdout` will be `''`
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #     Stdout contains the full batch output (or `''` when `out:` is given)
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits non-zero
+        #
+        # @overload call(batch_all_objects: true, batch_check: true, **options)
+        #   Enumerate all objects in the repository with metadata only
+        #
+        #   @param batch_all_objects [Boolean] enumerate all objects; stdin is not read
+        #
+        #   @param batch_check [Boolean, String] enable `--batch-check` mode; pass a
+        #     format string to customise the per-object output line
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :buffer (nil) use normal stdio buffering for better
+        #     throughput when processing large numbers of objects
+        #
+        #   @option options [Boolean, nil] :unordered (nil) output in arbitrary order
+        #
+        #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap for
+        #     commit and tag objects (`--use-mailmap`)
+        #
+        #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
+        #
+        #   @option options [String] :filter (nil) omit objects matching the given filter spec
+        #
+        #   @option options [Boolean, nil] :Z (nil) use NUL-delimited I/O
+        #
+        #   @option options [#write, nil] :out (nil) stream stdout to this IO object
+        #     instead of buffering in memory; when given, `result.stdout` will be `''`
+        #
+        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #     Stdout contains one metadata line per object (or `''` when `out:` is given)
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits non-zero
+        def call(*objects, **)
+          bound = args_definition.bind(*objects, **)
+          validate_version!
+          # `-Z` puts git into NUL I/O mode: input objects must be NUL-terminated.
+          # Without `-Z`, the standard newline delimiter is used.
+          delimiter = bound.Z? ? "\0" : "\n"
+          stdin = Array(bound.object).map { |o| "#{o}#{delimiter}" }.join
+          with_stdin(stdin) { |reader| run_batch(bound, reader) }
+        end
+
+        private
+
+        # Run the bound command with stdin connected to the reader end of the pipe
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound argument list
+        #
+        # @param reader [IO] read end of the stdin pipe
+        #
+        # @return [Git::CommandLineResult]
+        #
+        def run_batch(bound, reader)
+          result = if bound.execution_options.key?(:out)
+                     run_batch_streaming(bound, reader)
+                   else
+                     run_batch_capturing(bound, reader)
+                   end
+          validate_exit_status!(result)
+          result
+        end
+
+        def run_batch_streaming(bound, reader)
+          @execution_context.command_streaming(
+            *bound,
+            in: reader,
+            **bound.execution_options,
+            raise_on_failure: false
+          )
+        end
+
+        def run_batch_capturing(bound, reader)
+          @execution_context.command_capturing(
+            *bound,
+            in: reader,
+            **bound.execution_options,
+            normalize: false,
+            chomp: false,
+            raise_on_failure: false
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module CatFile
+      # Retrieves a single git object after applying working-tree filter processing
+      #
+      # Runs `git cat-file` with `--textconv` or `--filters`. Both modes require the
+      # caller to identify the object by revision **and** path so that git can look up
+      # the applicable `.gitattributes` rules:
+      #
+      # - **`--textconv`** — apply only the textconv filter (binary-to-text conversion
+      #   defined by `diff.<driver>.textconv` in `.gitattributes`); intended for
+      #   human-readable display
+      # - **`--filters`** — apply the full working-tree pipeline: smudge filter, EOL
+      #   conversion, and textconv; returns the content exactly as `git checkout`
+      #   would write it to disk
+      #
+      # The object can be identified as a combined `<rev>:<path>` string passed as the
+      # `rev` operand, or as a bare `<rev>` with `--path=<path>` supplied separately.
+      #
+      # For unfiltered object access, use {CatFile::Raw}.
+      # For batch queries across multiple objects, use {CatFile::Batch}.
+      #
+      # @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 Filtered < Base
+        arguments do
+          literal 'cat-file'
+
+          # Apply only the textconv filter (binary-to-text conversion)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
+          flag_option :textconv
+
+          # Apply the full working-tree filter pipeline (smudge, EOL, textconv)
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
+          flag_option :filters
+
+          # Specify the path separately when the rev is passed as a bare revision.
+          # When used, the `rev` operand must be a plain revision (not `<rev>:<path>`).
+          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---pathltpathgt
+          value_option :path, inline: true
+
+          end_of_options
+
+          # Revision identifying the object — either a combined `<rev>:<path>` string
+          # (e.g. `HEAD:README.md`) or a bare revision when `--path` is also given
+          operand :rev, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   Execute `git cat-file --textconv` or `git cat-file --filters`.
+        #
+        #   @overload call(rev, textconv: true, **options)
+        #     Apply the textconv filter to a single object
+        #
+        #     @param rev [String] combined `<rev>:<path>` identifier (e.g. `HEAD:README.md`),
+        #       or a bare revision when `path:` is also given
+        #
+        #     @param textconv [Boolean] enable textconv mode
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :path (nil) Path to the blob when `rev` is a bare revision
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #       Stdout contains the textconv-processed content
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if the object does not exist or the path is missing
+        #
+        #   @overload call(rev, filters: true, **options)
+        #     Apply the full working-tree filter pipeline to a single object
+        #
+        #     @param rev [String] combined `<rev>:<path>` identifier (e.g. `HEAD:README.md`),
+        #       or a bare revision when `path:` is also given
+        #
+        #     @param filters [Boolean] enable full filter pipeline mode
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String] :path (nil) Path to the blob when `rev` is a bare revision
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #
+        #       Stdout contains the filter-processed content
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if the object does not exist or the path is missing
+      end
+    end
+  end
+end

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

@@ -0,0 +1,210 @@
+# 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}.
+      #
+      # @see Git::Commands::CatFile
+      #
+      # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-cat-file/2.53.0
+      #
+      # @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;
+          # rejected by git in any other mode — enforced by constraint below
+          # @see https://git-scm.com/docs/git-cat-file#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
+
+          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
+
+          requires_one_of :t, :s, when: :allow_unknown_type
+        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] :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::CommandLineResult] 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
+        #
+        #   @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::CommandLineResult] 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
+        #
+        #   @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::CommandLineResult] 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] :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::CommandLineResult] 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] :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::CommandLineResult] 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
+        def call(*, **)
+          bound = args_definition.bind(*, **)
+          validate_version!
+          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
+      end
+    end
+  end
+end