git 4.3.2 → 5.0.0.beta.1

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am` to apply a series of patches from a mailbox
+      #
+      # Splits mail messages in a mailbox into commit log messages, authorship
+      # information, and patches, and applies them to the current branch.
+      #
+      # @example Apply patches from a mailbox file
+      #   am = Git::Commands::Am::Apply.new(execution_context)
+      #   am.call('patches.mbox', chdir: repo.workdir)
+      #
+      # @example Apply patches with sign-off
+      #   am.call('patches.mbox', signoff: true, chdir: repo.workdir)
+      #
+      # @example Apply with 3-way merge fallback
+      #   am.call('patches.mbox', three_way: true, chdir: repo.workdir)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class Apply < Git::Commands::Base
+        arguments do
+          literal 'am'
+
+          # Commit message / mailinfo options
+          flag_option %i[signoff s]
+          flag_option %i[keep k]
+          flag_option :keep_non_patch
+          flag_option :keep_cr, negatable: true
+          flag_option %i[scissors c], negatable: true
+          value_option :quoted_cr
+          value_option :empty
+          flag_option %i[message_id m], negatable: true
+
+          # Output
+          flag_option %i[quiet q]
+
+          # Encoding
+          flag_option %i[utf8 u], negatable: true
+
+          # Application strategy
+          flag_option :three_way, as: '--3way', negatable: true
+          flag_option :rerere_autoupdate, negatable: true
+
+          # Whitespace and patch application options (passed to git-apply)
+          flag_option :ignore_space_change
+          flag_option :ignore_whitespace
+          value_option :whitespace
+          value_option :C, inline: true
+          value_option :p, inline: true
+          value_option :directory
+          value_option :exclude, repeatable: true
+          value_option :include, repeatable: true
+          flag_option :reject
+
+          # Patch format
+          value_option :patch_format
+
+          # Interactive mode
+          flag_option %i[interactive i]
+
+          # Hook verification
+          flag_option :verify, negatable: true
+
+          # Date handling
+          flag_option :committer_date_is_author_date
+          flag_option :ignore_date
+
+          # GPG signing
+          flag_or_value_option %i[gpg_sign S], inline: true, negatable: true
+
+          # Execution
+          execution_option :chdir
+
+          end_of_options
+          operand :mbox, repeatable: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(*mbox, **options)
+        #
+        #     Apply patches from one or more mailbox files to the current branch.
+        #
+        #     @param mbox [Array<String>] zero or more mailbox file paths or Maildir
+        #       directories
+        #
+        #       If omitted, reads from standard input.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :signoff (nil) add Signed-off-by trailer
+        #
+        #       Alias: `:s`
+        #
+        #     @option options [Boolean, nil] :keep (nil) pass -k flag to git-mailinfo,
+        #       preserving the Subject line intact
+        #
+        #       Alias: `:k`
+        #
+        #     @option options [Boolean, nil] :keep_non_patch (nil) pass -b flag to
+        #       git-mailinfo
+        #
+        #     @option options [Boolean, nil] :keep_cr (nil) retain CR at end of lines (`--keep-cr`)
+        #
+        #     @option options [Boolean, nil] :no_keep_cr (nil) strip CR at end of lines (`--no-keep-cr`)
+        #
+        #     @option options [Boolean, nil] :scissors (nil) remove everything in the
+        #       body before a scissors line (`--scissors`)
+        #
+        #       Alias: `:c`
+        #
+        #     @option options [Boolean, nil] :no_scissors (nil) disable scissors mode (`--no-scissors`)
+        #
+        #     @option options [String] :quoted_cr (nil) how to handle CR in quoted
+        #       text passed to git-mailinfo
+        #
+        #       Valid actions: `'nowarn'`, `'warn'`, `'error'`.
+        #
+        #     @option options [String] :empty (nil) how to handle an e-mail message
+        #       lacking a patch
+        #
+        #       Valid values: `'stop'` (fail, default), `'drop'` (skip the message),
+        #       `'keep'` (create an empty commit).
+        #
+        #     @option options [Boolean, nil] :message_id (nil) pass -m flag to
+        #       git-mailinfo, adding the Message-ID header to the commit message (`--message-id`)
+        #
+        #       Alias: `:m`
+        #
+        #     @option options [Boolean, nil] :no_message_id (nil) do not add the Message-ID header (`--no-message-id`)
+        #
+        #     @option options [Boolean, nil] :quiet (nil) be quiet; only print error
+        #       messages
+        #
+        #       Alias: `:q`
+        #
+        #     @option options [Boolean, nil] :utf8 (nil) re-code the commit log message
+        #       in UTF-8 (`--utf8`)
+        #
+        #       Alias: `:u`
+        #
+        #     @option options [Boolean, nil] :no_utf8 (nil) do not re-code the commit log message (`--no-utf8`)
+        #
+        #     @option options [Boolean, nil] :three_way (nil) attempt 3-way merge when
+        #       context does not match (`--3way`)
+        #
+        #     @option options [Boolean, nil] :no_three_way (nil) disable 3-way merge fallback (`--no-3way`)
+        #
+        #     @option options [Boolean, nil] :rerere_autoupdate (nil) allow rerere to
+        #       update the index with auto-resolved conflicts (`--rerere-autoupdate`)
+        #
+        #     @option options [Boolean, nil] :no_rerere_autoupdate (nil) prevent rerere from
+        #       auto-updating the index (`--no-rerere-autoupdate`)
+        #
+        #     @option options [Boolean, nil] :ignore_space_change (nil) ignore whitespace
+        #       changes when applying (passed to git-apply)
+        #
+        #     @option options [Boolean, nil] :ignore_whitespace (nil) ignore whitespace
+        #       when applying (passed to git-apply)
+        #
+        #     @option options [String] :whitespace (nil) whitespace error handling
+        #       (e.g., `'nowarn'`, `'warn'`, `'fix'`, `'error'`)
+        #
+        #       Passed to git-apply.
+        #
+        #     @option options [Integer] :C (nil) ensure at least `<n>` lines of
+        #       surrounding context match when applying (`-C<n>`)
+        #
+        #       Passed to git-apply.
+        #
+        #     @option options [Integer] :p (nil) strip `<n>` leading path components
+        #       from file names (`-p<n>`)
+        #
+        #       Passed to git-apply.
+        #
+        #     @option options [String] :directory (nil) prepend `<dir>` to all
+        #       filenames
+        #
+        #       Passed to git-apply.
+        #
+        #     @option options [Array<String>] :exclude (nil) skip files matching the
+        #       given path pattern
+        #
+        #       May be repeated. Passed to git-apply.
+        #
+        #     @option options [Array<String>] :include (nil) apply only to files
+        #       matching the given path pattern
+        #
+        #       May be repeated. Passed to git-apply.
+        #
+        #     @option options [Boolean, nil] :reject (nil) leave rejected hunks in
+        #       `*.rej` files instead of aborting
+        #
+        #       Passed to git-apply.
+        #
+        #     @option options [String] :patch_format (nil) override patch format
+        #       detection
+        #
+        #       Valid formats: `'mbox'`, `'mboxrd'`, `'stgit'`, `'stgit-series'`,
+        #       `'hg'`.
+        #
+        #     @option options [Boolean, nil] :interactive (nil) run interactively,
+        #       prompting before each patch is applied
+        #
+        #       Alias: `:i`
+        #
+        #     @option options [Boolean, nil] :verify (nil) run pre-applypatch and
+        #       applypatch-msg hooks (`--verify`)
+        #
+        #       Hooks are run by default when this option is omitted.
+        #
+        #     @option options [Boolean, nil] :no_verify (nil) bypass pre-applypatch and
+        #       applypatch-msg hooks (`--no-verify`)
+        #
+        #     @option options [Boolean, nil] :committer_date_is_author_date (nil) use the
+        #       author date as the committer date
+        #
+        #     @option options [Boolean, nil] :ignore_date (nil) use the committer date as
+        #       the author date
+        #
+        #     @option options [Boolean, String, nil] :gpg_sign (nil) sign commits using
+        #       GPG (`--gpg-sign`)
+        #
+        #       Pass a key-ID string to select the signing key; pass `true` to use
+        #       the committer identity. Alias: `:S`
+        #
+        #     @option options [Boolean, nil] :no_gpg_sign (nil) countermand commit.gpgSign
+        #       configuration (`--no-gpg-sign`)
+        #
+        #     @option options [String] :chdir (nil) change to this directory before
+        #       running git
+        #
+        #       Not passed to the git CLI.
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/am/continue.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am --continue` to resume after resolving conflicts
+      #
+      # After the user has resolved a conflict in the working tree and updated
+      # the index, this command continues applying the remaining patches.
+      #
+      # @example Resume an am session after resolving conflicts
+      #   continue_cmd = Git::Commands::Am::Continue.new(execution_context)
+      #   continue_cmd.call
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see Git::Commands::Am
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class Continue < Git::Commands::Base
+        arguments do
+          literal 'am'
+          literal '--continue'
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call()
+        #
+        #     Resume applying patches after conflicts have been resolved
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am --continue`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/am/quit.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am --quit` to abort the in-progress am session
+      #
+      # Aborts the in-progress patch application but keeps the current HEAD
+      # position (does not restore the branch to its pre-am state).
+      #
+      # @example Quit an am session without restoring HEAD
+      #   quit_cmd = Git::Commands::Am::Quit.new(execution_context)
+      #   quit_cmd.call
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see Git::Commands::Am
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class Quit < Git::Commands::Base
+        arguments do
+          literal 'am'
+          literal '--quit'
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call()
+        #
+        #     Abort the am session but keep the current HEAD position
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am --quit`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/am/retry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am --retry` to retry the most-recently-failed patch
+      #
+      # Tries to apply the last conflicting patch again. Generally only useful
+      # when retrying with extra options (e.g. `--3way`), or in scripts where
+      # stdin is not a tty and the implicit retry heuristic does not trigger.
+      #
+      # @example Retry the current patch
+      #   retry_cmd = Git::Commands::Am::Retry.new(execution_context)
+      #   retry_cmd.call
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see Git::Commands::Am
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class Retry < Git::Commands::Base
+        arguments do
+          literal 'am'
+          literal '--retry'
+        end
+
+        # git am --retry was introduced in git 2.46.0
+        requires_git_version '2.46.0'
+
+        # @!method call(*, **)
+        #
+        #   @overload call()
+        #
+        #     Retry applying the most-recently-failed patch
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am --retry`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/am/show_current_patch.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements the `git am --show-current-patch` command
+      #
+      # Shows the message currently being applied when `git am` has stopped due to
+      # conflicts.
+      #
+      # @example Show the current patch
+      #   show_cmd = Git::Commands::Am::ShowCurrentPatch.new(execution_context)
+      #   show_cmd.call
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see Git::Commands::Am
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class ShowCurrentPatch < Git::Commands::Base
+        arguments do
+          literal 'am'
+          flag_or_value_option :show_current_patch, inline: true
+        end
+
+        # @overload call(*, show_current_patch: true, **options)
+        #
+        #   Execute the `git am --show-current-patch` command
+        #
+        #   @param show_current_patch [true, String] patch format selector
+        #
+        #     Pass `true` (default) to emit `--show-current-patch` (git defaults to
+        #     `raw` format); pass `'diff'` to emit `--show-current-patch=diff` (diff
+        #     portion only) or `'raw'` for `--show-current-patch=raw` (full raw email).
+        #     Passing `false` or `nil` raises `ArgumentError`.
+        #
+        #   @param options [Hash] command options
+        #
+        #   @return [Git::CommandLineResult] the result of calling
+        #     `git am --show-current-patch`
+        #
+        #   @raise [ArgumentError] if `show_current_patch` is `false` or `nil`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def call(*, show_current_patch: true, **)
+          unless show_current_patch
+            raise ArgumentError,
+                  ":show_current_patch must be true or a non-empty String, got #{show_current_patch.inspect}"
+          end
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/git/commands/am/skip.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am --skip` to skip the current patch
+      #
+      # Skips the current patch and continues applying remaining patches.
+      #
+      # @example Skip a conflicting patch
+      #   skip_cmd = Git::Commands::Am::Skip.new(execution_context)
+      #   skip_cmd.call
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-am/2.53.0
+      #
+      # @see Git::Commands::Am
+      #
+      # @see https://git-scm.com/docs/git-am git-am
+      #
+      # @api private
+      #
+      class Skip < Git::Commands::Base
+        arguments do
+          literal 'am'
+          literal '--skip'
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call()
+        #
+        #     Skip the current patch and continue with remaining patches
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am --skip`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

data/lib/git/commands/am.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'am/apply'
+require_relative 'am/abort'
+require_relative 'am/continue'
+require_relative 'am/quit'
+require_relative 'am/retry'
+require_relative 'am/show_current_patch'
+require_relative 'am/skip'
+
+module Git
+  module Commands
+    # Commands for applying patches from a mailbox via `git am`
+    #
+    # This module contains command classes for patch application and session
+    # management:
+    #
+    # - {Am::Apply} — apply a series of patches from a mailbox
+    # - {Am::Abort} — abort the current patch application (`--abort`)
+    # - {Am::Continue} — resume after resolving conflicts (`--continue`)
+    # - {Am::Quit} — drop the current patch session (`--quit`)
+    # - {Am::Retry} — retry the current patch
+    # - {Am::ShowCurrentPatch} — show the patch being applied (`--show-current-patch`)
+    # - {Am::Skip} — skip the current patch (`--skip`)
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-am git-am documentation
+    #
+    module Am
+    end
+  end
+end