git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/push.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git push` command
+    #
+    # Updates remote refs using local refs, while sending objects necessary to
+    # complete the given refs.
+    #
+    # @example Push to the default remote
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call
+    #
+    # @example Push to a named remote
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call('origin')
+    #
+    # @example Push a specific branch to a remote
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call('origin', 'main')
+    #
+    # @example Force push to a remote branch
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call('origin', 'main', force: true)
+    #
+    # @example Push with a server-side option
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call('origin', push_option: 'ci.skip')
+    #
+    # @example Push all tags to a remote
+    #   push = Git::Commands::Push.new(execution_context)
+    #   push.call('origin', tags: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-push/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-push git-push
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Push < Git::Commands::Base
+      arguments do
+        literal 'push'
+
+        # Push scope (SYNOPSIS order: [--all | --branches | --mirror | --tags])
+        flag_option %i[all branches]
+        flag_option :mirror
+        flag_option :tags
+        flag_option :follow_tags, negatable: true
+        flag_option :atomic, negatable: true
+
+        # Transfer options
+        flag_option %i[dry_run n]
+        flag_option :porcelain
+        value_option %i[receive_pack exec], inline: true
+        value_option :repo, inline: true
+
+        # Safety
+        flag_option %i[force f]
+        flag_option %i[delete d]
+        flag_option :prune
+
+        # Output verbosity
+        flag_option %i[quiet q]
+        flag_option %i[verbose v]
+
+        # Tracking
+        flag_option %i[set_upstream u]
+
+        # Push options (server-side)
+        value_option %i[push_option o], repeatable: true, inline: true
+
+        # GPG signing
+        flag_or_value_option :signed,
+                             negatable: true, inline: true
+
+        # Force safety
+        flag_or_value_option :force_with_lease,
+                             negatable: true, inline: true
+        flag_option :force_if_includes, negatable: true
+
+        # Hooks
+        flag_option :verify, negatable: true
+
+        # Submodules
+        flag_or_value_option :recurse_submodules,
+                             negatable: true, inline: true, type: String
+
+        # Transfer
+        flag_option :thin, negatable: true
+        flag_option :progress
+
+        # Protocol and connectivity
+        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 push` command
+      #
+      #   @overload call(repository = nil, *refspecs, **options)
+      #
+      #     @param repository [String, nil] The remote name or URL to push to
+      #
+      #       When nil, git uses the default remote configured for the current branch.
+      #
+      #     @param refspecs [Array<String>] Zero or more refspecs specifying which refs to push
+      #
+      #       Each may be a branch name or a full refspec pattern such as
+      #       `refs/heads/main:refs/heads/main`. When no refspecs are given, git uses
+      #       the push configuration for the current branch.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :all (nil) push all branches
+      #
+      #       Alias: :branches
+      #
+      #     @option options [Boolean, nil] :mirror (nil) push all refs under `refs/` to the remote
+      #
+      #     @option options [Boolean, nil] :tags (nil) push all refs under `refs/tags/`
+      #
+      #     @option options [Boolean, nil] :follow_tags (nil) push reachable annotated tags (`--follow-tags`)
+      #
+      #     @option options [Boolean, nil] :no_follow_tags (nil) do not push reachable annotated tags
+      #       (`--no-follow-tags`)
+      #
+      #     @option options [Boolean, nil] :atomic (nil) use an atomic transaction to update remote refs (`--atomic`)
+      #
+      #     @option options [Boolean, nil] :no_atomic (nil) disable atomic transaction for remote updates
+      #       (`--no-atomic`)
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) do not send updates, only report what would be pushed
+      #
+      #       Alias: :n
+      #
+      #     @option options [Boolean, nil] :porcelain (nil) produce machine-readable output
+      #
+      #     @option options [String] :receive_pack (nil) path to the git-receive-pack program on the remote end
+      #
+      #       Alias: :exec
+      #
+      #     @option options [String] :repo (nil) use this repository instead of the
+      #       positional repository argument
+      #
+      #       Equivalent to the positional `<repository>` argument. If both are given, the
+      #       positional argument takes precedence.
+      #
+      #     @option options [Boolean, nil] :force (nil) force updates, overriding the fast-forward check
+      #
+      #       Alias: :f
+      #
+      #     @option options [Boolean, nil] :delete (nil) delete all listed refs from the remote repository
+      #
+      #       Alias: :d
+      #
+      #     @option options [Boolean, nil] :prune (nil) remove remote branches that have no local counterpart
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress all output
+      #
+      #       Alias: :q
+      #
+      #     @option options [Boolean, nil] :verbose (nil) run verbosely
+      #
+      #       Alias: :v
+      #
+      #     @option options [Boolean, nil] :set_upstream (nil) set upstream tracking for each successfully pushed branch
+      #
+      #       Alias: :u
+      #
+      #     @option options [String, Array<String>] :push_option (nil) transmit one or more server-side options
+      #
+      #       Repeatable. Each occurrence emits a separate `--push-option=<value>` flag.
+      #
+      #       Alias: :o
+      #
+      #     @option options [Boolean, String, nil] :signed (nil) GPG-sign the push certificate (`--signed`)
+      #
+      #       When a String (`'true'`, `'false'`, `'if-asked'`), emits `--signed=<value>`.
+      #
+      #     @option options [Boolean, nil] :no_signed (nil) disable GPG signing of the push certificate (`--no-signed`)
+      #
+      #     @option options [Boolean, String, nil] :force_with_lease (nil) refuse force pushes unless the
+      #       remote ref matches the expected value (`--force-with-lease`)
+      #
+      #       When a String (e.g. `'main:abc123'`), emits `--force-with-lease=<string>`.
+      #
+      #     @option options [Boolean, nil] :no_force_with_lease (nil) disable force-with-lease (`--no-force-with-lease`)
+      #
+      #     @option options [Boolean, nil] :force_if_includes (nil) force pushes only if commits being
+      #       pushed are already in the remote-tracking branch (`--force-if-includes`)
+      #
+      #     @option options [Boolean, nil] :no_force_if_includes (nil) disable force-if-includes
+      #       (`--no-force-if-includes`)
+      #
+      #     @option options [Boolean, nil] :verify (nil) run the pre-push hook (`--verify`)
+      #
+      #     @option options [Boolean, nil] :no_verify (nil) bypass the pre-push hook (`--no-verify`)
+      #
+      #     @option options [String] :recurse_submodules (nil) control whether submodule
+      #       commits are pushed
+      #
+      #       Pass a String (`'check'`, `'on-demand'`, `'only'`, `'no'`) to emit
+      #       `--recurse-submodules=<value>`. Note: passing `true` is not valid; git requires
+      #       an explicit value for this option.
+      #
+      #     @option options [Boolean, nil] :no_recurse_submodules (nil) disable submodule push
+      #       (`--no-recurse-submodules`)
+      #
+      #     @option options [Boolean, nil] :thin (nil) send a "thin" pack to reduce network traffic (`--thin`)
+      #
+      #     @option options [Boolean, nil] :no_thin (nil) send a full pack instead of a thin pack (`--no-thin`)
+      #
+      #     @option options [Boolean, nil] :progress (nil) force progress reporting even when stderr is not a terminal
+      #
+      #     @option options [Boolean, nil] :ipv4 (nil) use IPv4 addresses only
+      #
+      #       Alias: :"4"
+      #
+      #     @option options [Boolean, nil] :ipv6 (nil) use IPv6 addresses only
+      #
+      #       Alias: :"6"
+      #
+      #     @option options [Integer] :timeout (nil) maximum seconds to wait for the command to complete
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git push`
+      #
+      #     @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/read_tree.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git read-tree` command
+    #
+    # Reads tree information into the index. Optionally performs a merge
+    # (single-tree, two-way fast-forward, or three-way) with the `-m` flag,
+    # and updates the working tree files with `-u`.
+    #
+    # @example Read a single tree into the index
+    #   read_tree = Git::Commands::ReadTree.new(execution_context)
+    #   result = read_tree.call('HEAD')
+    #
+    # @example Read a tree under a prefix directory
+    #   read_tree = Git::Commands::ReadTree.new(execution_context)
+    #   result = read_tree.call('HEAD', prefix: 'subdir/')
+    #
+    # @example Perform a three-way merge
+    #   read_tree = Git::Commands::ReadTree.new(execution_context)
+    #   result = read_tree.call('base', 'ours', 'theirs', m: true, u: true)
+    #
+    # @example Empty the index
+    #   read_tree = Git::Commands::ReadTree.new(execution_context)
+    #   result = read_tree.call(empty: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-read-tree/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-read-tree git-read-tree
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class ReadTree < Git::Commands::Base
+      arguments do
+        literal 'read-tree'
+
+        # Merge mode
+        flag_option :m
+        flag_option :trivial
+        flag_option :aggressive
+        flag_option :reset
+        value_option :prefix, inline: true
+
+        # Working tree update
+        flag_option :u
+        flag_option :i
+
+        # Dry run and progress
+        flag_option %i[dry_run n]
+        flag_option :v
+
+        # Filtering and output
+        value_option :index_output, inline: true
+        flag_option :recurse_submodules, negatable: true
+        flag_option :no_sparse_checkout
+        flag_option :empty
+
+        # Feedback control
+        flag_option %i[quiet q]
+
+        end_of_options
+
+        operand :tree_ish, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*tree_ish, **options)
+      #
+      #     Execute the `git read-tree` command
+      #
+      #     @param tree_ish [Array<String>] zero or more tree-ish objects to
+      #       read into the index
+      #
+      #       Pass one tree-ish for a simple read or single-tree merge, two
+      #       for a fast-forward (two-way) merge, or three for a three-way
+      #       merge. Omit when using the `:empty` option.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :m (nil) perform a merge, not just a
+      #       read
+      #
+      #     @option options [Boolean, nil] :trivial (nil) restrict three-way merge
+      #       to happen only if there is no file-level merging required
+      #
+      #     @option options [Boolean, nil] :aggressive (nil) resolve a few more
+      #       three-way merge cases internally beyond the trivial defaults
+      #
+      #     @option options [Boolean, nil] :reset (nil) same as `-m`, except that
+      #       unmerged entries are discarded instead of failing
+      #
+      #     @option options [String] :prefix (nil) keep the current index
+      #       contents, and read the named tree-ish under the directory at
+      #       the given prefix
+      #
+      #       Maps to `--prefix=<prefix>`.
+      #
+      #     @option options [Boolean, nil] :u (nil) after a successful merge,
+      #       update the files in the work tree with the result
+      #
+      #     @option options [Boolean, nil] :i (nil) disable the check with the
+      #       working tree, meant for creating a merge of trees not directly
+      #       related to the current working tree status
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) check if the command
+      #       would error out, without updating the index or files for real
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [Boolean, nil] :v (nil) show the progress of checking
+      #       files out
+      #
+      #     @option options [String] :index_output (nil) write the resulting
+      #       index in the named file instead of `$GIT_INDEX_FILE`
+      #
+      #       Maps to `--index-output=<file>`.
+      #
+      #     @option options [Boolean, nil] :recurse_submodules (nil) update the
+      #       content of all active submodules according to the commit
+      #       recorded in the superproject (`--recurse-submodules`)
+      #
+      #     @option options [Boolean, nil] :no_recurse_submodules (nil) disable
+      #       recursive submodule update (`--no-recurse-submodules`)
+      #
+      #     @option options [Boolean, nil] :no_sparse_checkout (nil) disable
+      #       sparse checkout support even if `core.sparseCheckout` is true
+      #
+      #     @option options [Boolean, nil] :empty (nil) empty the index instead of
+      #       reading tree object(s)
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress feedback messages
+      #
+      #       Alias: `:q`
+      #
+      #     @return [Git::CommandLineResult] the result of calling
+      #       `git read-tree`
+      #
+      #     @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/remote/add.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Remote
+      # `git remote add` command
+      #
+      # Adds a new remote to the repository, associating a name with a URL and
+      # configuring how tracking branches and tags are handled.
+      #
+      # @example Add a remote with a name and URL
+      #   add = Git::Commands::Remote::Add.new(execution_context)
+      #   add.call('origin', 'https://example.com/repo.git')
+      #
+      # @example Add a remote and immediately fetch
+      #   add = Git::Commands::Remote::Add.new(execution_context)
+      #   add.call('upstream', 'https://example.com/upstream.git', fetch: true)
+      #
+      # @example Track a specific branch and disable tag import
+      #   add = Git::Commands::Remote::Add.new(execution_context)
+      #   add.call('origin', 'https://example.com/repo.git', track: 'main', no_tags: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-remote/2.53.0
+      #
+      # @see Git::Commands::Remote
+      #
+      # @see https://git-scm.com/docs/git-remote git-remote
+      #
+      # @api private
+      #
+      class Add < Git::Commands::Base
+        arguments do
+          literal 'remote'
+          literal 'add'
+          value_option %i[track t], repeatable: true
+          value_option %i[master m]
+          flag_option %i[fetch f]
+          flag_option :tags, negatable: true
+          value_option :mirror, inline: true
+
+          end_of_options
+
+          operand :name, required: true
+          operand :url, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, url, **options)
+        #
+        #     Execute the `git remote add` command
+        #
+        #     @param name [String] the remote name to create
+        #
+        #     @param url [String] the remote URL to configure
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [String, Array<String>] :track (nil) track only the given branch(es) during fetch
+        #
+        #       Accepts a single branch name or an array; each value causes a separate `--track` flag.
+        #
+        #       Alias: :t
+        #
+        #     @option options [String] :master (nil) set the remote HEAD symbolic ref to the given branch
+        #
+        #       Alias: :m
+        #
+        #     @option options [Boolean, nil] :fetch (nil) fetch the remote immediately after adding it
+        #
+        #       Alias: :f
+        #
+        #     @option options [Boolean, nil] :tags (nil) import all tags from the remote (`--tags`)
+        #
+        #     @option options [Boolean, nil] :no_tags (nil) disable importing tags from the remote (`--no-tags`)
+        #
+        #     @option options [String] :mirror (nil) set mirror mode
+        #
+        #       Common values are `'fetch'` and `'push'`.
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git remote add`
+        #
+        #     @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/remote/get_url.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Remote
+      # `git remote get-url` command
+      #
+      # Retrieves the fetch or push URL configured for the named remote.
+      #
+      # @example Retrieve the fetch URL for a remote
+      #   get_url = Git::Commands::Remote::GetUrl.new(execution_context)
+      #   get_url.call('origin')
+      #
+      # @example Retrieve the push URL for a remote
+      #   get_url = Git::Commands::Remote::GetUrl.new(execution_context)
+      #   get_url.call('origin', push: true)
+      #
+      # @example Retrieve all configured URLs for a remote
+      #   get_url = Git::Commands::Remote::GetUrl.new(execution_context)
+      #   get_url.call('origin', all: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-remote/2.53.0
+      #
+      # @see Git::Commands::Remote
+      #
+      # @see https://git-scm.com/docs/git-remote git-remote
+      #
+      # @api private
+      #
+      class GetUrl < Git::Commands::Base
+        arguments do
+          literal 'remote'
+          literal 'get-url'
+          flag_option :push
+          flag_option :all
+
+          end_of_options
+
+          operand :name, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, **options)
+        #
+        #     Execute the `git remote get-url` command
+        #
+        #     @param name [String] the remote name to query
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :push (nil) query push URLs instead of fetch URLs
+        #
+        #     @option options [Boolean, nil] :all (nil) return all configured URLs instead of only the first one
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git remote get-url`
+        #
+        #     @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/remote/list.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Remote
+      # `git remote` command (list remotes)
+      #
+      # Lists all configured remote connections.
+      #
+      # @example List all remotes
+      #   list = Git::Commands::Remote::List.new(execution_context)
+      #   list.call
+      #
+      # @example List remotes with URLs
+      #   list = Git::Commands::Remote::List.new(execution_context)
+      #   list.call(verbose: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-remote/2.53.0
+      #
+      # @see Git::Commands::Remote
+      #
+      # @see https://git-scm.com/docs/git-remote git-remote
+      #
+      # @api private
+      #
+      class List < Git::Commands::Base
+        arguments do
+          literal 'remote'
+          flag_option %i[verbose v]
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(**options)
+        #
+        #     Execute the `git remote` command
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :verbose (nil) show remote URLs alongside remote names
+        #
+        #       Alias: :v
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git remote`
+        #
+        #     @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/remote/prune.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Remote
+      # `git remote prune` command
+      #
+      # Deletes stale remote-tracking refs that no longer exist on the named remote.
+      #
+      # @example Dry-run to preview which refs would be pruned
+      #   prune = Git::Commands::Remote::Prune.new(execution_context)
+      #   prune.call('origin', dry_run: true)
+      #
+      # @example Prune stale tracking refs for a remote
+      #   prune = Git::Commands::Remote::Prune.new(execution_context)
+      #   prune.call('origin')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-remote/2.53.0
+      #
+      # @see Git::Commands::Remote
+      #
+      # @see https://git-scm.com/docs/git-remote git-remote
+      #
+      # @api private
+      #
+      class Prune < Git::Commands::Base
+        arguments do
+          literal 'remote'
+          literal 'prune'
+          flag_option %i[dry_run n]
+
+          end_of_options
+
+          operand :name, repeatable: true, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(*name, **options)
+        #
+        #     Prune stale remote-tracking refs for one or more remotes
+        #
+        #     @param name [Array<String>] one or more remote names to prune
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :dry_run (nil) report what would be pruned without deleting refs
+        #
+        #       Alias: :n
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git remote prune`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end