git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/merge_base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git merge-base` command to find common ancestors
+    #
+    # Finds as good common ancestors as possible for use in a three-way merge.
+    # Given two or more commits, it outputs a common ancestor reachable from
+    # all of them through the parent relationship.
+    #
+    # @example Find merge bases of two branches
+    #   merge_base = Git::Commands::MergeBase.new(execution_context)
+    #   merge_base.call('main', 'feature')
+    #   merge_base.call('main', 'feature', all: true)
+    #   merge_base.call('main', 'b1', 'b2', octopus: true)
+    #   merge_base.call('main', 'feature', fork_point: true)
+    #
+    # @note `arguments` block audited against
+    #   https://git-scm.com/docs/git-merge-base/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-merge-base git-merge-base
+    #
+    # @api private
+    #
+    class MergeBase < Git::Commands::Base
+      arguments do
+        literal 'merge-base'
+
+        # Operation modes
+        flag_option :octopus
+        flag_option :independent
+        flag_option :is_ancestor
+        flag_option :fork_point
+
+        # Options
+        flag_option %i[all a]
+
+        end_of_options
+        operand :commit, repeatable: true, required: true
+      end
+
+      # git merge-base --fork-point returns exit code 1 when no fork point is
+      # found; --is-ancestor returns exit code 1 when the first commit is not an
+      # ancestor (both are valid non-error exits)
+      allow_exit_status 0..1
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*commit, **options)
+      #
+      #     Execute the `git merge-base` command
+      #
+      #     @param commit [Array<String>] two or more commit SHAs, branch names,
+      #       or refs to find common ancestor(s) of
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :octopus (nil) compute best common
+      #       ancestor for an n-way merge (intersection of all merge bases)
+      #
+      #     @option options [Boolean, nil] :independent (nil) list commits not
+      #       reachable from any other; useful for finding minimal merge points
+      #
+      #     @option options [Boolean, nil] :is_ancestor (nil) check if the first
+      #       commit is an ancestor of the second; exits 0 if true, 1 if not
+      #
+      #     @option options [Boolean, nil] :fork_point (nil) find the fork point
+      #       where a branch diverged from another, consulting the reflog
+      #
+      #     @option options [Boolean, nil] :all (nil) output all merge bases instead
+      #       of just one when multiple equally good bases exist
+      #
+      #       Alias: :a
+      #
+      #     @return [Git::CommandLineResult] the result of calling
+      #       `git merge-base`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits outside the allowed range
+      #       (exit code > 1)
+    end
+  end
+end

data/lib/git/commands/mv.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements `git mv` to move or rename a file, a directory, or a symlink
+    #
+    # The index is updated after successful completion, but the change must still
+    # be committed.
+    #
+    # @example Move a single file
+    #   mv = Git::Commands::Mv.new(execution_context)
+    #   mv.call('old_name.rb', 'new_name.rb')
+    #
+    # @example Move multiple files to a directory
+    #   mv = Git::Commands::Mv.new(execution_context)
+    #   mv.call('file1.rb', 'file2.rb', 'destination_dir/')
+    #
+    # @example Force overwrite if destination exists
+    #   mv = Git::Commands::Mv.new(execution_context)
+    #   mv.call('source.rb', 'dest.rb', force: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-mv/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-mv git-mv
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Mv < Git::Commands::Base
+      arguments do
+        literal 'mv'
+        flag_option %i[verbose v]
+        flag_option %i[force f]
+        flag_option %i[dry_run n]
+        flag_option :k
+        end_of_options
+        operand :source, repeatable: true, required: true
+        operand :destination, required: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*source, destination, **options)
+      #
+      #     Execute the git mv command
+      #
+      #     @param source [Array<String>] one or more source file(s) or directories to move
+      #
+      #     @param destination [String] the destination file or directory
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :verbose (nil) report the names of files as they are moved
+      #
+      #       Alias: `:v`
+      #
+      #     @option options [Boolean, nil] :force (nil) force renaming or moving even if the destination exists
+      #
+      #       Alias: `:f`
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) do nothing; only show what would happen
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [Boolean, nil] :k (nil) skip move or rename actions which would lead to an error
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git mv`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+    end
+  end
+end

data/lib/git/commands/name_rev.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git name-rev` command
+    #
+    # Finds symbolic names suitable for human digestion for revisions given
+    # in any format parsable by `git rev-parse`.
+    #
+    # @example Find the symbolic name for a commit
+    #   name_rev = Git::Commands::NameRev.new(execution_context)
+    #   result = name_rev.call('abc123')
+    #
+    # @example Use only tags for naming
+    #   name_rev = Git::Commands::NameRev.new(execution_context)
+    #   result = name_rev.call('abc123', tags: true)
+    #
+    # @example List all commits reachable from all refs
+    #   name_rev = Git::Commands::NameRev.new(execution_context)
+    #   result = name_rev.call(all: true)
+    #
+    # @example Filter refs by pattern
+    #   name_rev = Git::Commands::NameRev.new(execution_context)
+    #   result = name_rev.call('abc123', refs: ['heads/*', 'tags/*'])
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-name-rev/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-name-rev git-name-rev
+    #
+    # @api private
+    #
+    class NameRev < Git::Commands::Base
+      arguments do
+        literal 'name-rev'
+
+        # Ref filtering
+        flag_option :tags
+        value_option :refs, inline: true, repeatable: true
+        flag_option :no_refs
+        value_option :exclude, inline: true, repeatable: true
+        flag_option :no_exclude
+
+        # Output control
+        flag_option :all
+        flag_option :annotate_stdin
+        flag_option :name_only
+        flag_option :no_undefined
+        flag_option :always
+
+        end_of_options
+
+        operand :commit_ish, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*commit_ish, **options)
+      #
+      #     Execute the `git name-rev` command
+      #
+      #     @param commit_ish [Array<String>] zero or more commit-ish objects
+      #       to find symbolic names for
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :tags (nil) use only tags to name
+      #       the commits, not branch names
+      #
+      #     @option options [String, Array<String>] :refs (nil) only use refs
+      #       whose names match the given shell pattern
+      #
+      #       When given multiple times, uses refs whose names match any of the
+      #       given shell patterns. Maps to `--refs=<pattern>`.
+      #
+      #     @option options [Boolean, nil] :no_refs (nil) clear all previously given
+      #       `--refs` patterns
+      #
+      #     @option options [String, Array<String>] :exclude (nil) do not use
+      #       any ref whose name matches the given shell pattern
+      #
+      #       When given multiple times, a ref is excluded when it matches any
+      #       of the given patterns. Maps to `--exclude=<pattern>`.
+      #
+      #     @option options [Boolean, nil] :no_exclude (nil) clear all previously
+      #       given `--exclude` patterns
+      #
+      #     @option options [Boolean, nil] :all (nil) list all commits reachable
+      #       from all refs
+      #
+      #     @option options [Boolean, nil] :annotate_stdin (nil) transform stdin by
+      #       substituting all 40-character SHA-1 hexes with their symbolic
+      #       names. Maps to `--annotate-stdin`.
+      #
+      #     @option options [Boolean, nil] :name_only (nil) print only the symbolic
+      #       name, not the SHA-1
+      #
+      #     @option options [Boolean, nil] :no_undefined (nil) die with non-zero
+      #       exit code when a reference is undefined, instead of printing
+      #       `undefined`
+      #
+      #     @option options [Boolean, nil] :always (nil) show uniquely abbreviated
+      #       commit object as fallback
+      #
+      #     @return [Git::CommandLineResult] the result of calling
+      #       `git name-rev`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero status
+    end
+  end
+end

data/lib/git/commands/pull.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git pull` command
+    #
+    # Incorporates changes from a remote repository into the current branch.
+    # In its default mode, `git pull` is shorthand for `git fetch` followed
+    # by `git merge FETCH_HEAD`.
+    #
+    # @example Pull from the default remote
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call
+    #
+    # @example Pull from a named remote
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call('origin')
+    #
+    # @example Pull a specific branch from a remote
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call('origin', 'main')
+    #
+    # @example Pull with rebase instead of merge
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call('origin', rebase: true)
+    #
+    # @example Pull with allow-unrelated-histories
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call('origin', 'feature', allow_unrelated_histories: true)
+    #
+    # @example Pull and suppress the merge-commit editor
+    #   pull = Git::Commands::Pull.new(execution_context)
+    #   pull.call('origin', no_edit: true)
+    #
+    # @note `arguments` block audited against
+    #   https://git-scm.com/docs/git-pull/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-pull git-pull
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Pull < Git::Commands::Base
+      arguments do
+        literal 'pull'
+
+        # General options
+        flag_option %i[quiet q]
+        flag_option %i[verbose v]
+        flag_or_value_option :recurse_submodules,
+                             negatable: true, inline: true
+
+        # Merge options
+        flag_option :commit, negatable: true
+        flag_option %i[edit e], negatable: true
+        value_option :cleanup, inline: true
+        flag_option :ff_only
+        flag_option :ff, negatable: true
+        flag_or_value_option %i[gpg_sign S], negatable: true, inline: true
+        flag_or_value_option :log, negatable: true, inline: true
+        flag_option :signoff, negatable: true
+        flag_option :stat
+        flag_option %i[no_stat n]
+        flag_option :compact_summary
+        flag_option :squash, negatable: true
+        flag_option :verify, negatable: true
+        value_option %i[strategy s], inline: true
+        value_option %i[strategy_option X], inline: true, repeatable: true
+        flag_option :verify_signatures, negatable: true
+        flag_option :summary, negatable: true
+        flag_option :autostash, negatable: true
+        flag_option :allow_unrelated_histories
+        flag_or_value_option %i[rebase r], negatable: true, inline: true
+
+        # Fetch options
+        flag_option :all, negatable: true
+        flag_option %i[append a]
+        flag_option :atomic
+        value_option :depth, inline: true
+        value_option :deepen, inline: true
+        value_option :shallow_since, inline: true
+        value_option :shallow_exclude, inline: true, repeatable: true
+        flag_option :unshallow
+        flag_option :update_shallow
+        value_option :negotiation_tip, inline: true, repeatable: true
+        flag_option :negotiate_only
+        flag_option :dry_run
+        flag_option :porcelain
+        flag_option %i[force f]
+        flag_option %i[keep k]
+        flag_option :prefetch
+        flag_option %i[prune p]
+        flag_option %i[tags t], negatable: true
+        value_option :refmap, inline: true, repeatable: true
+        value_option %i[jobs j], inline: true
+        flag_option :set_upstream
+        value_option :upload_pack
+        flag_option :progress, negatable: true
+        value_option %i[server_option o], inline: true, repeatable: true
+        flag_option :show_forced_updates, negatable: true
+        flag_option %i[ipv4 4]
+        flag_option %i[ipv6 6]
+
+        # Execution options (not emitted as CLI flags)
+        execution_option :timeout
+
+        end_of_options
+        operand :repository
+        operand :refspec, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   Execute the `git pull` command
+      #
+      #   @overload call(repository = nil, *refspecs, **options)
+      #
+      #     @param repository [String, nil] The remote name or URL to pull from
+      #
+      #       When nil, git uses the default remote for the current branch.
+      #
+      #     @param refspecs [Array<String>] Zero or more refspecs specifying which refs to fetch
+      #       and merge
+      #
+      #       Each may be a branch name or refspec pattern.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress all output
+      #
+      #       Alias: :q
+      #
+      #     @option options [Boolean, nil] :verbose (nil) enable verbose output during fetch and merge
+      #
+      #       Alias: :v
+      #
+      #     @option options [Boolean, String, nil] :recurse_submodules (nil) control submodule
+      #       commit fetching (`--recurse-submodules`)
+      #
+      #       Pass a string such as `'yes'`, `'on-demand'`, or `'no'` for
+      #       `--recurse-submodules=<value>`.
+      #
+      #     @option options [Boolean, nil] :no_recurse_submodules (nil) disable submodule
+      #       commit fetching (`--no-recurse-submodules`)
+      #
+      #     @option options [Boolean, nil] :commit (nil) perform the merge and commit the result
+      #       (`--commit`)
+      #
+      #     @option options [Boolean, nil] :no_commit (nil) merge but do not commit the result
+      #       (`--no-commit`)
+      #
+      #     @option options [Boolean, nil] :edit (nil) open an editor for the merge commit message
+      #       (`--edit`)
+      #
+      #       Alias: :e
+      #
+      #     @option options [Boolean, nil] :no_edit (nil) do not open an editor for the merge commit
+      #       message (`--no-edit`)
+      #
+      #     @option options [String] :cleanup (nil) merge-message cleanup mode
+      #
+      #       Determines how the merge message is cleaned up before committing.
+      #       For example, `'strip'`, `'whitespace'`, `'verbatim'`, `'scissors'`, `'default'`.
+      #
+      #     @option options [Boolean, nil] :ff_only (nil) require fast-forward merge or up-to-date HEAD
+      #
+      #       Refuses to merge unless the current HEAD is already up to date or the
+      #       merge can be resolved as a fast-forward.
+      #
+      #     @option options [Boolean, nil] :ff (nil) allow fast-forward merge (`--ff`)
+      #
+      #     @option options [Boolean, nil] :no_ff (nil) disable fast-forward merge, always creating a
+      #       merge commit (`--no-ff`)
+      #
+      #     @option options [Boolean, String, nil] :gpg_sign (nil) GPG-sign the resulting merge commit
+      #       (`--gpg-sign`)
+      #
+      #       Pass a key-ID string to select the signing key. Alias: :S
+      #
+      #     @option options [Boolean, nil] :no_gpg_sign (nil) countermand commit.gpgSign configuration
+      #       (`--no-gpg-sign`)
+      #
+      #     @option options [Boolean, Integer, nil] :log (nil) include one-line descriptions from
+      #       the actual commits being merged in log message (`--log`)
+      #
+      #       Pass an integer for `--log=<n>`.
+      #
+      #     @option options [Boolean, nil] :no_log (nil) disable inclusion of one-line descriptions
+      #       from merged commits (`--no-log`)
+      #
+      #     @option options [Boolean, nil] :signoff (nil) add a `Signed-off-by` trailer to the
+      #       resulting merge commit message (`--signoff`)
+      #
+      #     @option options [Boolean, nil] :no_signoff (nil) remove a `Signed-off-by` trailer from
+      #       the merge commit message (`--no-signoff`)
+      #
+      #     @option options [Boolean, nil] :stat (nil) show a diffstat at the end of the merge
+      #
+      #     @option options [Boolean, nil] :no_stat (nil) do not show a diffstat at the end of the merge
+      #
+      #       Alias: :n
+      #
+      #     @option options [Boolean, nil] :compact_summary (nil) show a compact summary after the merge
+      #
+      #     @option options [Boolean, nil] :squash (nil) squash pulled commits into a single commit
+      #       (`--squash`)
+      #
+      #     @option options [Boolean, nil] :no_squash (nil) override `--squash` option (`--no-squash`)
+      #
+      #     @option options [Boolean, nil] :verify (nil) run pre-merge and commit-msg hooks
+      #       (`--verify`)
+      #
+      #     @option options [Boolean, nil] :no_verify (nil) bypass pre-merge and commit-msg hooks
+      #       (`--no-verify`)
+      #
+      #     @option options [String] :strategy (nil) use the given merge strategy
+      #
+      #       For example, `'ort'`, `'recursive'`, `'resolve'`, `'octopus'`, `'ours'`, `'subtree'`.
+      #       Alias: :s
+      #
+      #     @option options [String, Array<String>] :strategy_option (nil) pass option(s) to
+      #       the merge strategy
+      #
+      #       Can be a single value or array. For example, `'ours'`, `'theirs'`, `'patience'`.
+      #       Alias: :X
+      #
+      #     @option options [Boolean, nil] :verify_signatures (nil) verify that the tip commit of
+      #       the side branch being merged is signed with a valid key (`--verify-signatures`)
+      #
+      #     @option options [Boolean, nil] :no_verify_signatures (nil) do not verify the signature of
+      #       the side branch tip commit (`--no-verify-signatures`)
+      #
+      #     @option options [Boolean, nil] :summary (nil) show a summary after the merge (`--summary`)
+      #
+      #     @option options [Boolean, nil] :no_summary (nil) do not show a summary after the merge
+      #       (`--no-summary`)
+      #
+      #     @option options [Boolean, nil] :autostash (nil) automatically create a temporary stash entry
+      #       before the operation begins (`--autostash`)
+      #
+      #     @option options [Boolean, nil] :no_autostash (nil) disable automatic stashing before the
+      #       operation (`--no-autostash`)
+      #
+      #     @option options [Boolean, nil] :allow_unrelated_histories (nil) allow pulling from a
+      #       repository that shares no common history with the current repository
+      #
+      #     @option options [Boolean, String, nil] :rebase (nil) rebase the current branch on
+      #       top of the upstream branch after fetching (`--rebase`)
+      #
+      #       Pass a string such as `'merges'` or `'interactive'` for `--rebase=<value>`.
+      #       Alias: :r
+      #
+      #     @option options [Boolean, nil] :no_rebase (nil) override earlier `--rebase` option
+      #       (`--no-rebase`)
+      #
+      #     @option options [Boolean, nil] :all (nil) fetch all remotes (`--all`)
+      #
+      #     @option options [Boolean, nil] :no_all (nil) do not fetch all remotes (`--no-all`)
+      #
+      #     @option options [Boolean, nil] :append (nil) append ref names and object names fetched to
+      #       the existing contents of `.git/FETCH_HEAD`
+      #
+      #       Alias: :a
+      #
+      #     @option options [Boolean, nil] :atomic (nil) use an atomic transaction to update local refs
+      #
+      #     @option options [String] :depth (nil) limit fetching to the given number of commits
+      #
+      #       Fetches only the specified number of commits from the tip of each
+      #       remote branch history.
+      #
+      #     @option options [String] :deepen (nil) deepen or shorten history of a shallow repository
+      #
+      #     @option options [String] :shallow_since (nil) deepen or shorten history to include all
+      #       reachable commits after the given date
+      #
+      #     @option options [String, Array<String>] :shallow_exclude (nil) exclude commits reachable
+      #       from the specified remote branch or tag
+      #
+      #       Repeatable.
+      #
+      #     @option options [Boolean, nil] :unshallow (nil) convert a shallow repository to a complete one
+      #
+      #       If the source is shallow, fetches as much as possible.
+      #
+      #     @option options [Boolean, nil] :update_shallow (nil) accept refs that update `.git/shallow`
+      #
+      #     @option options [String, Array<String>] :negotiation_tip (nil) report only commits
+      #       reachable from the given tips during negotiation
+      #
+      #       Repeatable.
+      #
+      #     @option options [Boolean, nil] :negotiate_only (nil) do not fetch; only print ancestries
+      #       between the local repository and the remote
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) show what would be done without making changes
+      #
+      #     @option options [Boolean, nil] :porcelain (nil) give the output in a stable, easy-to-parse
+      #       format for scripts
+      #
+      #     @option options [Boolean, nil] :force (nil) override the check for a non-fast-forward update
+      #
+      #       Alias: :f
+      #
+      #     @option options [Boolean, nil] :keep (nil) keep the downloaded pack
+      #
+      #       Alias: :k
+      #
+      #     @option options [Boolean, nil] :prefetch (nil) modify the configured refspec to place
+      #       all refs into the `refs/prefetch/` namespace
+      #
+      #     @option options [Boolean, nil] :prune (nil) remove remote-tracking references that no longer
+      #       exist on the remote before fetching
+      #
+      #       Alias: :p
+      #
+      #     @option options [Boolean, nil] :tags (nil) fetch all tags from the remote (`--tags`)
+      #
+      #       Alias: :t
+      #
+      #     @option options [Boolean, nil] :no_tags (nil) disable automatic tag following
+      #       (`--no-tags`)
+      #
+      #     @option options [String, Array<String>] :refmap (nil) override fetch refspecs for
+      #       remote-tracking branch mapping
+      #
+      #       Repeatable.
+      #
+      #     @option options [String] :jobs (nil) number of submodules fetched in parallel
+      #
+      #       Alias: :j
+      #
+      #     @option options [Boolean, nil] :set_upstream (nil) add upstream (tracking) reference for
+      #       the current branch
+      #
+      #     @option options [String] :upload_pack (nil) path to `git-upload-pack` on the remote
+      #
+      #     @option options [Boolean, nil] :progress (nil) force progress status display (`--progress`)
+      #
+      #     @option options [Boolean, nil] :no_progress (nil) suppress progress status display
+      #       (`--no-progress`)
+      #
+      #     @option options [String, Array<String>] :server_option (nil) transmit the given
+      #       string to the server when communicating using protocol version 2
+      #
+      #       Repeatable. Alias: :o
+      #
+      #     @option options [Boolean, nil] :show_forced_updates (nil) check whether a local branch is
+      #       force-updated during fetch (`--show-forced-updates`)
+      #
+      #     @option options [Boolean, nil] :no_show_forced_updates (nil) disable checking for force
+      #       updates (`--no-show-forced-updates`)
+      #
+      #     @option options [Boolean, nil] :ipv4 (nil) use IPv4 addresses only, ignoring IPv6 addresses
+      #
+      #       Alias: :'4'
+      #
+      #     @option options [Boolean, nil] :ipv6 (nil) use IPv6 addresses only, ignoring IPv4 addresses
+      #
+      #       Alias: :'6'
+      #
+      #     @option options [Numeric, nil] :timeout (nil) timeout in seconds for the command
+      #
+      #       If nil, uses the global timeout from {Git::Config}.
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git pull`
+      #
+      #     @raise [ArgumentError] if argument validation fails (e.g., unsupported options
+      #       are provided or option values are invalid)
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+    end
+  end
+end