git 4.4.1 → 5.0.0.beta.1

data/lib/git/command_line_result.rb

@@ -1,92 +1,8 @@
 # frozen_string_literal: true
 
-module Git
-  # The result of running a git command
-  #
-  # This object stores the Git command executed and its status, stdout, and stderr.
-  #
-  # @api public
-  #
-  class CommandLineResult
-    # Create a CommandLineResult object
-    #
-    # @example
-    #   `true`
-    #   git_cmd = %w[git version]
-    #   status = $?
-    #   stdout = "git version 2.39.1\n"
-    #   stderr = ""
-    #   result = Git::CommandLineResult.new(git_cmd, status, stdout, stderr)
-    #
-    # @param git_cmd [Array<String>] the git command that was executed
-    # @param status [ProcessExecuter::ResultWithCapture] the status of the process
-    # @param stdout [String] the processed stdout of the process
-    # @param stderr [String] the processed stderr of the process
-    #
-    def initialize(git_cmd, status, stdout, stderr)
-      @git_cmd = git_cmd
-      @status = status
-      @stdout = stdout
-      @stderr = stderr
-
-      # ProcessExecuter::ResultWithCapture changed the timeout? method to timed_out?
-      # in version 4.x. This is a compatibility layer to maintain the old method name
-      # for backward compatibility.
-      #
-      status.define_singleton_method(:timeout?) { timed_out? }
-    end
-
-    # @attribute [r] git_cmd
-    #
-    # The git command that was executed
-    #
-    # @example
-    #  git_cmd = %w[git version]
-    #  result = Git::CommandLineResult.new(git_cmd, $?, "", "")
-    #  result.git_cmd #=> ["git", "version"]
-    #
-    # @return [Array<String>]
-    #
-    attr_reader :git_cmd
+require 'git/command_line/result'
 
-    # @attribute [r] status
-    #
-    # The status of the process
-    #
-    # @example
-    #   `true`
-    #   status = $?
-    #   result = Git::CommandLineResult.new(status, "", "")
-    #   result.status #=> #<Process::Status: pid 87859 exit 0>
-    #
-    # @return [Process::Status]
-    #
-    attr_reader :status
-
-    # @attribute [r] stdout
-    #
-    # The output of the process
-    #
-    # @example
-    #   stdout = "git version 2.39.1\n"
-    #   result = Git::CommandLineResult.new($?, stdout, "")
-    #   result.stdout #=> "git version 2.39.1\n"
-    #
-    # @return [String]
-    #
-    attr_reader :stdout
-
-    # @attribute [r] stderr
-    #
-    # The error output of the process
-    #
-    # @example
-    #   stderr = "Tag not found\n"
-    #   result = Git::CommandLineResult.new($?, "", stderr)
-    #   result.stderr #=> "Tag not found\n"
-    #
-    # @return [String]
-    #
-    attr_reader :stderr
-  end
+module Git
+  # Backward-compatible alias for {Git::CommandLine::Result}
+  CommandLineResult = Git::CommandLine::Result
 end

data/lib/git/commands/add.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git add` command
+    #
+    # This command updates the index using the current content found in the working tree,
+    # to prepare the content staged for the next commit.
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-add/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-add git-add
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    # @example Basic usage
+    #   add = Git::Commands::Add.new(execution_context)
+    #   add.call('path/to/file')
+    #   add.call('file1.rb', 'file2.rb')
+    #   add.call(all: true)
+    #
+    class Add < Git::Commands::Base
+      arguments do
+        literal 'add'
+        flag_option %i[verbose v]
+        flag_option %i[dry_run n]
+        flag_option %i[force f]
+        flag_option %i[all A], negatable: true
+        flag_option :ignore_removal, negatable: true
+        flag_option %i[update u]
+        flag_option :sparse
+        flag_option %i[intent_to_add N]
+        flag_option :refresh
+        flag_option :ignore_errors
+        flag_option :ignore_missing
+        flag_option :renormalize
+        flag_option :no_warn_embedded_repo
+        value_option :chmod, inline: true
+        value_option :pathspec_from_file, inline: true
+        flag_option :pathspec_file_nul
+        end_of_options
+        operand :pathspec, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*pathspec, **options)
+      #
+      #     Execute the `git add` command
+      #
+      #     @param pathspec [Array<String>] files to be added to the repository
+      #       (relative to the worktree root)
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :verbose (nil) be verbose
+      #
+      #       Alias: :v
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) don't actually add files; show what would be added
+      #
+      #       Alias: :n
+      #
+      #     @option options [Boolean, nil] :force (nil) allow adding otherwise ignored files
+      #
+      #       Alias: :f
+      #
+      #     @option options [Boolean, nil] :all (nil) add, modify, and remove index entries to
+      #       match the worktree (--all)
+      #
+      #       Alias: :A
+      #
+      #     @option options [Boolean, nil] :no_all (nil) add and modify index entries without staging
+      #       removals (--no-all)
+      #
+      #     @option options [Boolean, nil] :ignore_removal (nil) add and modify files; ignore removals
+      #       (--ignore-removal)
+      #
+      #     @option options [Boolean, nil] :no_ignore_removal (nil) include file removals (--no-ignore-removal)
+      #
+      #     @option options [Boolean, nil] :update (nil) update tracked files only; does not add new files
+      #
+      #       Alias: :u
+      #
+      #     @option options [Boolean, nil] :sparse (nil) allow updating index entries outside the
+      #       sparse-checkout cone
+      #
+      #     @option options [Boolean, nil] :intent_to_add (nil) record that the path will be added later,
+      #       placing an empty entry in the index
+      #
+      #       Alias: :N
+      #
+      #     @option options [Boolean, nil] :refresh (nil) refresh stat() information in the index without
+      #       adding files
+      #
+      #     @option options [Boolean, nil] :ignore_errors (nil) continue adding other files if some files
+      #       cannot be added due to indexing errors
+      #
+      #     @option options [Boolean, nil] :ignore_missing (nil) check whether any given files would be
+      #       ignored
+      #
+      #     @option options [Boolean, nil] :renormalize (nil) apply the "clean" process freshly to all tracked
+      #       files to forcibly re-add them with correct line endings
+      #
+      #     @option options [Boolean, nil] :no_warn_embedded_repo (nil) suppress warning when adding an
+      #       embedded repository without using `git submodule add`
+      #
+      #     @option options [String] :chmod (nil) override the executable bit of added files in the index
+      #
+      #       Value must be `'+x'` or `'-x'`
+      #
+      #     @option options [String] :pathspec_from_file (nil) read pathspec from the given file
+      #       (use `'-'` for stdin)
+      #
+      #     @option options [Boolean, nil] :pathspec_file_nul (nil) separate pathspec elements with NUL
+      #       when reading from a file
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git add`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #     @api public
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Am
+      # Implements `git am --abort` to abort an in-progress am session
+      #
+      # Aborts the in-progress patch application and restores the branch to
+      # the state it was in before the `git am` session started.
+      #
+      # @example Abort an am session
+      #   abort_cmd = Git::Commands::Am::Abort.new(execution_context)
+      #   abort_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 Abort < Git::Commands::Base
+        arguments do
+          literal 'am'
+          literal '--abort'
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call()
+        #
+        #     Abort the in-progress am session and restore the branch
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git am --abort`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end

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