git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/clone.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git clone` command
+    #
+    # Clones a repository into a newly created directory.
+    #
+    # @example Typical usage
+    #   clone = Git::Commands::Clone.new(execution_context)
+    #   clone.call('https://github.com/user/repo.git')
+    #   clone.call('https://github.com/user/repo.git', 'local-dir')
+    #   clone.call('https://github.com/user/repo.git', 'local-dir', bare: true)
+    #   clone.call('https://github.com/user/repo.git', 'local-dir', depth: 1)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-clone/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-clone git-clone
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Clone < Git::Commands::Base
+      arguments do
+        literal 'clone'
+        value_option :template, inline: true
+        flag_option %i[local l], negatable: true
+        flag_option %i[shared s]
+        flag_option :no_hardlinks
+        flag_option %i[quiet q]
+        flag_option %i[verbose v]
+        flag_option :progress
+        flag_option %i[no_checkout n]
+        flag_option :bare
+        flag_option :mirror
+        value_option %i[origin o]
+        value_option %i[branch b]
+        value_option :revision, inline: true
+        value_option %i[upload_pack u]
+        value_option :reference, repeatable: true
+        value_option :reference_if_able, repeatable: true
+        flag_option :dissociate
+        value_option :separate_git_dir, inline: true
+        value_option :server_option, inline: true, repeatable: true
+        value_option :depth
+        value_option :shallow_since, inline: true
+        value_option :shallow_exclude, inline: true, repeatable: true
+        flag_option :single_branch, negatable: true
+        flag_option :tags, negatable: true
+        flag_or_value_option :recurse_submodules, inline: true, repeatable: true
+        flag_option :shallow_submodules, negatable: true
+        flag_option :remote_submodules, negatable: true
+        value_option %i[jobs j]
+        flag_option :sparse
+        flag_option :reject_shallow, negatable: true
+        value_option :filter, inline: true
+        flag_option :also_filter_submodules
+        value_option %i[config c], repeatable: true
+        value_option :bundle_uri, inline: true
+        value_option :ref_format, inline: true
+        end_of_options
+        operand :repository, required: true
+        operand :directory
+        execution_option :timeout
+        execution_option :chdir
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(repository, directory = nil, **options)
+      #
+      #     Execute the `git clone` command
+      #
+      #     @param repository [String] the URL or path of the repository to clone
+      #
+      #     @param directory [String, nil] the directory to clone into; git derives the
+      #       name from the repository URL when omitted
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [String] :template (nil) directory from which templates
+      #       will be used
+      #
+      #     @option options [Boolean, nil] :local (nil) bypass the normal Git-aware transport
+      #       for local clones (`--local`)
+      #
+      #       Alias: `:l`
+      #
+      #     @option options [Boolean, nil] :no_local (nil) disable the local optimization
+      #       and use the normal transport (`--no-local`)
+      #
+      #     @option options [Boolean, nil] :shared (nil) set up a shared clone using
+      #       alternates instead of hardlinks
+      #
+      #       Alias: `:s`
+      #
+      #     @option options [Boolean, nil] :no_hardlinks (nil) force file-copy instead of
+      #       hardlinks when cloning from a local filesystem
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress progress output to stderr
+      #
+      #       Alias: `:q`
+      #
+      #     @option options [Boolean, nil] :verbose (nil) run verbosely
+      #
+      #       Alias: `:v`
+      #
+      #     @option options [Boolean, nil] :progress (nil) force progress status even when
+      #       stderr is not a terminal
+      #
+      #     @option options [Boolean, nil] :no_checkout (nil) skip checking out HEAD after
+      #       the clone
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [Boolean, nil] :bare (nil) clone as a bare repository
+      #
+      #     @option options [Boolean, nil] :mirror (nil) set up a mirror clone (implies
+      #       --bare)
+      #
+      #     @option options [String] :origin (nil) name of the remote to use instead of
+      #       "origin"
+      #
+      #       Alias: `:o`
+      #
+      #     @option options [String] :branch (nil) branch to check out after cloning
+      #
+      #       Alias: `:b`
+      #
+      #     @option options [String] :revision (nil) detach HEAD at the given revision
+      #       after cloning; incompatible with :branch and :mirror
+      #
+      #     @option options [String] :upload_pack (nil) path to git-upload-pack on the
+      #       remote (ssh only)
+      #
+      #       Alias: `:u`
+      #
+      #     @option options [String, Array<String>] :reference (nil) borrow objects from
+      #       one or more reference repositories
+      #
+      #     @option options [String, Array<String>] :reference_if_able (nil) like
+      #       :reference but skip with a warning when the reference does not exist
+      #
+      #     @option options [Boolean, nil] :dissociate (nil) stop borrowing from reference
+      #       repositories after the clone is complete
+      #
+      #     @option options [String] :separate_git_dir (nil) place the git directory at
+      #       the given path and create a gitfile symlink in the working tree
+      #
+      #     @option options [String, Array<String>] :server_option (nil) protocol-v2
+      #       server options
+      #
+      #     @option options [Integer, String] :depth (nil) create a shallow clone with
+      #       the specified number of commits
+      #
+      #     @option options [String] :shallow_since (nil) create a shallow clone with
+      #       history after the specified date
+      #
+      #     @option options [String, Array<String>] :shallow_exclude (nil) exclude
+      #       commits reachable from the specified remote branch or tag
+      #
+      #     @option options [Boolean, nil] :single_branch (nil) clone only the history for
+      #       one branch (`--single-branch`)
+      #
+      #     @option options [Boolean, nil] :no_single_branch (nil) clone history for all
+      #       branches (`--no-single-branch`)
+      #
+      #     @option options [Boolean, nil] :tags (nil) include tags in the clone (`--tags`)
+      #
+      #     @option options [Boolean, nil] :no_tags (nil) exclude tags from the clone
+      #       (`--no-tags`)
+      #
+      #     @option options [Boolean, String, Array<String>, nil] :recurse_submodules (nil)
+      #       initialize submodules after cloning; pass true for all submodules or a
+      #       pathspec string/array for a subset
+      #
+      #     @option options [Boolean, nil] :shallow_submodules (nil) clone submodules with
+      #       depth 1 (`--shallow-submodules`)
+      #
+      #     @option options [Boolean, nil] :no_shallow_submodules (nil) clone submodules
+      #       with full history (`--no-shallow-submodules`)
+      #
+      #     @option options [Boolean, nil] :remote_submodules (nil) use submodule
+      #       remote-tracking branch status (`--remote-submodules`)
+      #
+      #     @option options [Boolean, nil] :no_remote_submodules (nil) use the locally
+      #       recorded SHA-1 for submodules (`--no-remote-submodules`)
+      #
+      #     @option options [Integer, String] :jobs (nil) number of submodules fetched
+      #       concurrently
+      #
+      #       Alias: `:j`
+      #
+      #     @option options [Boolean, nil] :sparse (nil) enable sparse checkout with
+      #       top-level files only
+      #
+      #     @option options [Boolean, nil] :reject_shallow (nil) fail if source is shallow
+      #       (`--reject-shallow`)
+      #
+      #     @option options [Boolean, nil] :no_reject_shallow (nil) allow cloning from
+      #       shallow sources (`--no-reject-shallow`)
+      #
+      #     @option options [String] :filter (nil) specify a partial clone filter
+      #       (e.g., 'blob:none', 'tree:0')
+      #
+      #     @option options [Boolean, nil] :also_filter_submodules (nil) apply the partial
+      #       clone filter to submodules; requires :filter and :recurse_submodules
+      #
+      #     @option options [String, Array<String>] :config (nil) set configuration
+      #       variables in the newly-created repository
+      #
+      #       Alias: `:c`
+      #
+      #     @option options [String] :bundle_uri (nil) fetch a bundle from the given URI
+      #       before fetching from the remote
+      #
+      #     @option options [String] :ref_format (nil) specify the ref storage format
+      #       (e.g., 'files', 'reftable')
+      #
+      #     @option options [Numeric, nil] :timeout (nil) the number of seconds to wait
+      #       for the command to complete; if nil, uses the global timeout from
+      #       {Git::Config}; if 0, no timeout is enforced
+      #
+      #     @option options [String, nil] :chdir (nil) the working directory in which to
+      #       run the git clone command
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git clone`
+      #
+      #     @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/commit.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git commit` command
+    #
+    # This command records changes to the repository by creating a new commit
+    # with the staged changes.
+    #
+    # @example Typical usage
+    #   commit = Git::Commands::Commit.new(execution_context)
+    #   commit.call(message: 'Initial commit')
+    #   commit.call(message: 'Add feature', all: true, author: 'Jane <jane@example.com>')
+    #   commit.call(amend: true, no_verify: true)  # emits --no-verify
+    #   commit.call('src/foo.rb', message: 'Update foo')
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-commit/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-commit git-commit
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Commit < Git::Commands::Base
+      arguments do
+        literal 'commit'
+
+        # Stage selection
+        flag_option %i[all a]
+
+        # Message source and editing
+        flag_option %i[edit e], negatable: true
+        flag_option :amend
+        value_option %i[reuse_message C], inline: true
+        value_option :fixup, inline: true
+        value_option :squash, inline: true
+        value_option %i[message m], inline: true, allow_empty: true
+        value_option %i[file F], inline: true
+        value_option %i[template t], inline: true
+
+        # Author / date
+        flag_option :reset_author
+        value_option :author, inline: true
+        value_option :date, inline: true, type: String
+
+        # Message cleanup and trailers
+        value_option :cleanup, inline: true
+        value_option :trailer, repeatable: true
+
+        # Hooks
+        flag_option %i[verify n], negatable: true
+
+        # Behavior
+        flag_option :allow_empty
+        flag_option :allow_empty_message
+        flag_option :no_post_rewrite
+        flag_option %i[include i]
+        flag_option %i[only o]
+
+        # Output / dry-run
+        flag_option :dry_run
+        flag_option :short
+        flag_option :branch
+        flag_option :porcelain
+        flag_option :long
+        flag_option %i[null z]
+        flag_option %i[verbose v], max_times: 2
+        flag_option %i[quiet q]
+        flag_option :status, negatable: true
+
+        # Verbose diff options
+        value_option %i[unified U], inline: true, type: Integer
+        value_option :inter_hunk_context, inline: true, type: Integer
+
+        # Signoff
+        flag_option %i[signoff s], negatable: true
+
+        # GPG signing
+        flag_or_value_option %i[gpg_sign S], negatable: true, inline: true
+
+        # Untracked files
+        flag_or_value_option %i[untracked_files u], inline: true
+
+        # Pathspec from file
+        value_option :pathspec_from_file, inline: true
+        flag_option :pathspec_file_nul
+
+        # Path selection
+        end_of_options
+        operand :pathspec, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*pathspec, **options)
+      #
+      #     Execute the `git commit` command.
+      #
+      #     @param pathspec [Array<String>] zero or more paths to commit
+      #
+      #       When given, only changes to the listed paths are committed, ignoring
+      #       staged changes for other paths.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :all (nil) automatically stage modified and deleted
+      #       files before committing
+      #
+      #       Alias: `:a`
+      #
+      #     @option options [Boolean, nil] :edit (nil) open an editor for the commit message (`--edit`)
+      #
+      #       Alias: `:e`
+      #
+      #     @option options [Boolean, nil] :no_edit (nil) suppress the editor (`--no-edit`)
+      #
+      #     @option options [Boolean, nil] :amend (nil) replace the tip of the current branch
+      #       with a new commit
+      #
+      #     @option options [String] :reuse_message (nil) reuse the log message and
+      #       authorship from the given commit without invoking an editor
+      #
+      #       Alias: `:C`
+      #
+      #     @option options [String] :fixup (nil) create a fixup or amend commit targeting
+      #       the given commit
+      #
+      #       Pass `<commit>` for a plain "fixup!" commit, `amend:<commit>` to also replace
+      #       the log message, or `reword:<commit>` to replace only the log message.
+      #
+      #     @option options [String] :squash (nil) construct a "squash!" commit message for
+      #       use with `git rebase --autosquash`
+      #
+      #     @option options [String] :message (nil) use the given string as the commit message
+      #
+      #       Alias: `:m`
+      #
+      #     @option options [String] :file (nil) read the commit message from the given file;
+      #       use `-` to read from standard input
+      #
+      #       Alias: `:F`
+      #
+      #     @option options [String] :template (nil) start the editor with the contents of
+      #       the given file as the commit message template
+      #
+      #       Alias: `:t`
+      #
+      #     @option options [Boolean, nil] :reset_author (nil) when used with `:reuse_message`
+      #       or `:amend`, declare the committer as the new author
+      #
+      #     @option options [String] :author (nil) override the commit author
+      #
+      #     @option options [String] :date (nil) override the author date
+      #
+      #     @option options [String] :cleanup (nil) how to clean up the commit message before
+      #       committing; one of `strip`, `whitespace`, `verbatim`, `scissors`, or `default`
+      #
+      #     @option options [String, Array<String>] :trailer (nil) add one or more
+      #       `<token>[=<value>]` trailers to the commit message
+      #
+      #     @option options [Boolean, nil] :verify (nil) run pre-commit and commit-msg hooks (`--verify`)
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [Boolean, nil] :no_verify (nil) bypass pre-commit and commit-msg hooks (`--no-verify`)
+      #
+      #     @option options [Boolean, nil] :allow_empty (nil) allow committing with no changes
+      #
+      #     @option options [Boolean, nil] :allow_empty_message (nil) allow committing with an
+      #       empty message
+      #
+      #     @option options [Boolean, nil] :no_post_rewrite (nil) bypass the post-rewrite hook
+      #
+      #     @option options [Boolean, nil] :include (nil) stage the listed paths before
+      #       committing in addition to already-staged contents
+      #
+      #       Alias: `:i`
+      #
+      #     @option options [Boolean, nil] :only (nil) commit only the listed paths from the
+      #       working tree, ignoring staged changes for other paths
+      #
+      #       Alias: `:o`
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) do not create a commit; show what
+      #       would be committed
+      #
+      #     @option options [Boolean, nil] :short (nil) show short-format dry-run output;
+      #       implies `:dry_run`
+      #
+      #     @option options [Boolean, nil] :branch (nil) show branch and tracking info in
+      #       short-format dry-run output
+      #
+      #     @option options [Boolean, nil] :porcelain (nil) show porcelain-format dry-run
+      #       output; implies `:dry_run`
+      #
+      #     @option options [Boolean, nil] :long (nil) show long-format dry-run output;
+      #       implies `:dry_run`
+      #
+      #     @option options [Boolean, nil] :null (nil) terminate dry-run output entries with
+      #       NUL instead of LF
+      #
+      #       Alias: `:z`
+      #
+      #     @option options [Boolean, Integer, nil] :verbose (nil) show unified diff between
+      #       HEAD and what would be committed at the bottom of the commit message template
+      #
+      #       Pass `2` to also show the unified diff between staged and working-tree changes.
+      #
+      #       Alias: `:v`
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress commit summary message
+      #
+      #       Alias: `:q`
+      #
+      #     @option options [Boolean, nil] :status (nil) include `git status` output in the
+      #       commit message template (`--status`)
+      #
+      #     @option options [Boolean, nil] :no_status (nil) omit `git status` output from the
+      #       commit message template (`--no-status`)
+      #
+      #     @option options [Integer] :unified (nil) generate verbose diff with the given
+      #       number of context lines
+      #
+      #       Alias: `:U`
+      #
+      #     @option options [Integer] :inter_hunk_context (nil) show context between diff
+      #       hunks up to the given number of lines (for use with `:verbose`)
+      #
+      #     @option options [Boolean, nil] :signoff (nil) add a `Signed-off-by` trailer to
+      #       the commit message (`--signoff`)
+      #
+      #       Alias: `:s`
+      #
+      #     @option options [Boolean, nil] :no_signoff (nil) suppress the `Signed-off-by` trailer (`--no-signoff`)
+      #
+      #     @option options [Boolean, String, nil] :gpg_sign (nil) GPG-sign the commit (`--gpg-sign`)
+      #
+      #       When `true`, uses the default key. When a `String`, uses the specified key ID.
+      #
+      #       Alias: `:S`
+      #
+      #     @option options [Boolean, nil] :no_gpg_sign (nil) disable GPG signing, overriding
+      #       `commit.gpgSign` config (`--no-gpg-sign`)
+      #
+      #     @option options [Boolean, String, nil] :untracked_files (nil) show untracked files
+      #       in the dry-run status output
+      #
+      #       When `true`, uses git's default mode (`all`). Pass a `String` (`"no"`,
+      #       `"normal"`, or `"all"`) to set the mode explicitly.
+      #
+      #       Alias: `:u`
+      #
+      #     @option options [String] :pathspec_from_file (nil) read pathspec from the given
+      #       file instead of the command line
+      #
+      #     @option options [Boolean, nil] :pathspec_file_nul (nil) pathspec elements in
+      #       `:pathspec_from_file` are NUL-separated instead of newline-separated
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git commit`
+      #
+      #     @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/commit_tree.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git commit-tree` command
+    #
+    # Creates a new commit object based on the provided tree object and emits the
+    # new commit object id on stdout. The log message is provided via `-m` or `-F`
+    # options; multiple instances of either are concatenated as separate paragraphs.
+    #
+    # @example Typical usage
+    #   commit_tree = Git::Commands::CommitTree.new(execution_context)
+    #   commit_tree.call('abc123', m: 'Initial commit')
+    #   commit_tree.call('abc123', p: %w[parent1 parent2], m: 'Merge')
+    #   commit_tree.call('abc123', m: 'Signed', gpg_sign: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-commit-tree/2.53.0
+    #
+    # @see Git::Commands
+    #
+    # @see https://git-scm.com/docs/git-commit-tree git-commit-tree
+    #
+    # @api private
+    #
+    class CommitTree < Git::Commands::Base
+      arguments do
+        literal 'commit-tree'
+
+        # Parent commits — each -p adds a parent object
+        value_option :p, repeatable: true
+
+        # GPG signing — -S[<keyid>] / --gpg-sign[=<keyid>] / --no-gpg-sign
+        flag_or_value_option %i[gpg_sign S], negatable: true, inline: true
+
+        # Commit log message paragraphs
+        value_option :m, repeatable: true, allow_empty: true
+
+        # Read commit log message from file(s)
+        value_option :F, repeatable: true
+
+        end_of_options
+
+        # The tree object to create a commit from
+        operand :tree, required: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(tree, **options)
+      #
+      #     Execute the `git commit-tree` command
+      #
+      #     @param tree [String] an existing tree object SHA
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [String, Array<String>] :p (nil) parent commit
+      #       object id(s)
+      #
+      #       Each value adds a `-p <parent>` flag. A commit may have zero or
+      #       more parents. With exactly one parent it is an ordinary commit;
+      #       with more than one it is a merge commit. Initial (root) commits
+      #       have no parents.
+      #
+      #     @option options [Boolean, String, nil] :gpg_sign (nil) sign the
+      #       commit with 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, Array<String>] :m (nil) a paragraph
+      #       in the commit log message
+      #
+      #       Can be given more than once; each message becomes its own paragraph.
+      #
+      #     @option options [String, Array<String>] :F (nil) read the commit
+      #       log message from the given file
+      #
+      #       Use `"-"` to read from standard input. Can be given more than
+      #       once; each file's content becomes its own paragraph.
+      #
+      #     @return [Git::CommandLineResult] the result of calling
+      #       `git commit-tree`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [ArgumentError] if the tree operand is missing
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit
+      #       status
+      #
+      #     @api public
+    end
+  end
+end

data/lib/git/commands/config_option_syntax/add.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module ConfigOptionSyntax
+      # Append a value to a multi-valued config key
+      #
+      # Wraps `git config --add` to add a new line to a config key without
+      # altering existing values.
+      #
+      # @example Add a value to a multi-valued key
+      #   cmd = Git::Commands::ConfigOptionSyntax::Add.new(lib)
+      #   cmd.call('remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-config/2.53.0
+      #
+      # @see Git::Commands::ConfigOptionSyntax
+      #
+      # @see https://git-scm.com/docs/git-config git-config documentation
+      #
+      # @api private
+      #
+      class Add < Git::Commands::Base
+        arguments do
+          literal 'config'
+          literal '--add'
+
+          # File-scope options
+          flag_option :global
+          flag_option :system
+          flag_option :local
+          flag_option :worktree
+          value_option %i[file f]
+          value_option :blob
+
+          # Type constraint
+          value_option :type, inline: true
+
+          # Operands
+          end_of_options
+          operand :name, required: true
+          operand :value, required: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(name, value, **options)
+        #
+        #     Execute the `git config --add` command
+        #
+        #     @param name [String] the config key name
+        #
+        #     @param value [String] the value to append
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :global (nil) write to global config (`~/.gitconfig`)
+        #
+        #     @option options [Boolean, nil] :system (nil) write to system config
+        #
+        #     @option options [Boolean, nil] :local (nil) write to repository config (`.git/config`)
+        #
+        #     @option options [Boolean, nil] :worktree (nil) write to worktree config
+        #
+        #     @option options [String] :file (nil) write to the specified file
+        #
+        #       Alias: :f
+        #
+        #     @option options [String] :blob (nil) read from the specified blob
+        #
+        #     @option options [String] :type (nil) ensure the value conforms to the given type
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git config --add`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      end
+    end
+  end
+end