git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/cat_file.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'cat_file/batch'
+require_relative 'cat_file/filtered'
+require_relative 'cat_file/raw'
+
+module Git
+  module Commands
+    # Commands for reading git object store content via `git cat-file`
+    #
+    # This module contains command classes split by invocation protocol:
+    #
+    # - {CatFile::Raw} — single object as a CLI argument; raw content, type, size, or
+    #   existence check (`-e`, `-t`, `-s`, `-p`, `<type>`)
+    # - {CatFile::Filtered} — single object as a CLI argument; content after
+    #   `.gitattributes` filter processing (`--textconv`, `--filters`)
+    # - {CatFile::Batch} — objects fed via stdin; all batch streaming modes
+    #   (`--batch`, `--batch-check`, `--batch-command`)
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
+    #
+    # @example Check whether an object exists
+    #   cmd = Git::Commands::CatFile::Raw.new(lib)
+    #   result = cmd.call('HEAD', e: true)
+    #   result.status.exitstatus  # => 0 (exists) or 1 (not found)
+    #
+    # @example Pretty-print a single object
+    #   cmd = Git::Commands::CatFile::Raw.new(lib)
+    #   result = cmd.call('HEAD', p: true)
+    #   result.stdout
+    #   # => "tree abc1234...\nauthor ...\n\nCommit message\n"
+    #
+    # @example Fetch content after working-tree filters
+    #   cmd = Git::Commands::CatFile::Filtered.new(lib)
+    #   result = cmd.call('HEAD:README.md', filters: true)
+    #   result.stdout
+    #
+    # @example Fetch metadata for several objects via batch
+    #   cmd = Git::Commands::CatFile::Batch.new(lib)
+    #   result = cmd.call('HEAD', 'v1.0', batch_check: true)
+    #   result.stdout
+    #   # => "abc1234... commit 250\nabc5678... tag 143\n"
+    #
+    module CatFile
+    end
+  end
+end

data/lib/git/commands/checkout/branch.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Checkout
+      # Implements the `git checkout` command for switching branches
+      #
+      # This command switches branches by updating the index and working tree
+      # to match the specified branch, and updating HEAD to point to that branch.
+      # It can also create new branches with the `-b` or `-B` options.
+      #
+      # @example Typical usage
+      #   checkout = Git::Commands::Checkout::Branch.new(execution_context)
+      #   checkout.call('main')
+      #   checkout.call(b: 'feature-branch')
+      #   checkout.call('origin/main', b: 'feature-branch', track: true)
+      #   checkout.call('abc123', detach: true)
+      #   checkout.call('main', force: true)
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-checkout/2.53.0
+      #
+      # @see Git::Commands::Checkout
+      #
+      # @see https://git-scm.com/docs/git-checkout git-checkout
+      #
+      # @api private
+      #
+      class Branch < Git::Commands::Base
+        arguments do
+          literal 'checkout'
+          flag_option %i[quiet q]
+          flag_option :progress, negatable: true
+          flag_option %i[force f]
+          value_option :b
+          value_option :B
+          flag_or_value_option %i[track t], negatable: true, inline: true
+          flag_option :guess, negatable: true
+          flag_option :l
+          flag_option %i[detach d]
+          value_option :orphan
+          flag_option %i[merge m]
+          flag_option :ignore_other_worktrees
+          flag_option :overwrite_ignore, negatable: true
+
+          # --recurse-submodules is technically available but has no effect on branch
+          # switching in older git versions. Included for completeness per the man page.
+          flag_option :recurse_submodules, negatable: true
+
+          execution_option :chdir
+
+          operand :branch
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(branch = nil, **options)
+        #
+        #     Execute the git checkout command for branch switching
+        #
+        #     @param branch [String, nil] the branch name, commit SHA, or ref to check
+        #       out; when used with branch creation options (`:b`, `:B`, `:orphan`)
+        #       this becomes the start point
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress feedback messages
+        #
+        #       Alias: `:q`
+        #
+        #     @option options [Boolean, nil] :progress (nil) force progress reporting even
+        #       when not attached to a terminal (`--progress`)
+        #
+        #     @option options [Boolean, nil] :no_progress (nil) disable progress reporting
+        #       even when attached to a terminal (`--no-progress`)
+        #
+        #     @option options [Boolean, nil] :force (nil) proceed even if the index or
+        #       working tree differs from HEAD; discards local changes and untracked
+        #       files that are in the way
+        #
+        #       Alias: `:f`
+        #
+        #     @option options [String] :b (nil) create a new branch with this name and
+        #       switch to it; the positional `branch` argument becomes the start point
+        #
+        #     @option options [String] :B (nil) like `:b`, but reset the branch to the
+        #       start point if it already exists
+        #
+        #     @option options [Boolean, String, nil] :track (nil) set up upstream tracking
+        #       configuration; `true` emits `--track`, `'direct'` emits
+        #       `--track=direct`, `'inherit'` emits `--track=inherit` (`--track`)
+        #
+        #       Alias: `:t`
+        #
+        #     @option options [Boolean, nil] :no_track (nil) do not set up branch tracking
+        #       even if `branch.autoSetupMerge` is configured (`--no-track`)
+        #
+        #     @option options [Boolean, nil] :guess (nil) automatically create and check out
+        #       a local branch from a uniquely matching remote-tracking branch
+        #       (`--guess`)
+        #
+        #     @option options [Boolean, nil] :no_guess (nil) disable automatic remote branch
+        #       matching (`--no-guess`)
+        #
+        #     @option options [Boolean, nil] :l (nil) create the new branch's reflog
+        #
+        #     @option options [Boolean, nil] :detach (nil) detach HEAD at the specified
+        #       commit rather than pointing a branch at it
+        #
+        #       Alias: `:d`
+        #
+        #     @option options [String] :orphan (nil) create a new unborn branch with no
+        #       history; the positional `branch` argument becomes the start point
+        #
+        #     @option options [Boolean, nil] :merge (nil) perform a three-way merge when
+        #       local modifications conflict with the target branch
+        #
+        #       Alias: `:m`
+        #
+        #     @option options [Boolean, nil] :ignore_other_worktrees (nil) check out the
+        #       branch even if it is already in use by another worktree
+        #
+        #     @option options [Boolean, nil] :overwrite_ignore (nil) silently overwrite
+        #       ignored files when switching branches (`--overwrite-ignore`)
+        #
+        #     @option options [Boolean, nil] :no_overwrite_ignore (nil) abort the checkout
+        #       if ignored files would be overwritten (`--no-overwrite-ignore`)
+        #
+        #     @option options [Boolean, nil] :recurse_submodules (nil) update all active
+        #       submodule working trees to match the new branch
+        #       (`--recurse-submodules`)
+        #
+        #     @option options [Boolean, nil] :no_recurse_submodules (nil) do not update
+        #       submodule working trees when switching branches
+        #       (`--no-recurse-submodules`)
+        #
+        #     @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 checkout`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/checkout/files.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Checkout
+      # Implements the `git checkout` command for restoring working tree files
+      #
+      # This command replaces files in the working tree with versions from
+      # the index (when tree_ish is nil) or a specified tree-ish (commit,
+      # branch, tag, etc.).
+      #
+      # @example Restore working tree files
+      #   files = Git::Commands::Checkout::Files.new(execution_context)
+      #   files.call(pathspec: ['lib/foo.rb'])                             # from the index
+      #   files.call('HEAD~1', pathspec: ['lib/foo.rb'])                   # from a specific commit
+      #   files.call('main', pathspec: %w[lib/foo.rb lib/bar.rb])          # from a branch
+      #   files.call(pathspec: ['conflicted.txt'], ours: true)             # resolve conflict (ours)
+      #   files.call('main', pathspec_from_file: 'paths.txt')              # paths from a file
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-checkout/2.53.0
+      #
+      # @see Git::Commands::Checkout
+      #
+      # @see https://git-scm.com/docs/git-checkout git-checkout
+      #
+      # @api private
+      #
+      class Files < Git::Commands::Base
+        arguments do
+          literal 'checkout'
+          flag_option %i[force f]
+          flag_option :ours
+          flag_option :theirs
+          flag_option %i[merge m]
+          value_option :conflict, inline: true
+          flag_option :overlay, negatable: true
+          flag_option :ignore_skip_worktree_bits
+          value_option :pathspec_from_file, inline: true
+          flag_option :pathspec_file_nul
+
+          execution_option :chdir
+
+          operand :tree_ish
+          end_of_options
+          value_option :pathspec, as_operand: true, repeatable: true
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(tree_ish = nil, **options)
+        #
+        #     Execute the git checkout command for restoring files
+        #
+        #     @param tree_ish [String, nil] The commit, branch, or tree to restore
+        #       files from
+        #
+        #       When `nil`, files are restored from the index
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :force (nil) ignore unmerged entries
+        #
+        #       Alias: `:f`
+        #
+        #     @option options [Boolean, nil] :ours (nil) for unmerged paths, check out
+        #       stage #2 (our version)
+        #
+        #     @option options [Boolean, nil] :theirs (nil) for unmerged paths, check out
+        #       stage #3 (their version)
+        #
+        #     @option options [Boolean, nil] :merge (nil) recreate the conflicted merge in
+        #       the specified paths; cannot be used when checking out from a tree-ish
+        #
+        #       Alias: `:m`
+        #
+        #     @option options [String] :conflict (nil) conflict marker style; valid
+        #       values are `'merge'`, `'diff3'`, and `'zdiff3'`
+        #
+        #     @option options [Boolean, nil] :overlay (nil) never remove files from the
+        #       index or working tree that are not present in the tree-ish (`--overlay`)
+        #
+        #     @option options [Boolean, nil] :no_overlay (nil) remove files not present
+        #       in the tree-ish from the index and working tree (`--no-overlay`)
+        #
+        #     @option options [Boolean, nil] :ignore_skip_worktree_bits (nil) in sparse
+        #       checkout mode, ignore sparse patterns and update all files matched by
+        #       pathspec
+        #
+        #     @option options [String] :pathspec_from_file (nil) read pathspec from
+        #       this file; pass `'-'` to read from stdin
+        #
+        #     @option options [Boolean, nil] :pathspec_file_nul (nil) with
+        #       `:pathspec_from_file`, separate pathspec elements with NUL instead of
+        #       newline
+        #
+        #     @option options [Array<String>, String] :pathspec (nil) the files or
+        #       directories to restore
+        #
+        #     @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 checkout`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
+        #
+      end
+    end
+  end
+end

data/lib/git/commands/checkout.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'checkout/branch'
+require_relative 'checkout/files'
+
+module Git
+  module Commands
+    # Commands for switching branches and restoring files via `git checkout`
+    #
+    # This module contains command classes split by checkout mode:
+    #
+    # - {Checkout::Branch} — switch branches or create and switch to a new branch
+    # - {Checkout::Files} — restore working tree files from a given tree-ish
+    #
+    # @api private
+    #
+    # @see https://git-scm.com/docs/git-checkout git-checkout documentation
+    #
+    # @example Switch to an existing branch
+    #   cmd = Git::Commands::Checkout::Branch.new(lib)
+    #   cmd.call('main')
+    #
+    # @example Create and switch to a new branch
+    #   cmd = Git::Commands::Checkout::Branch.new(lib)
+    #   cmd.call('main', b: 'feature/new-feature')
+    #
+    # @example Restore a file from the index (discard uncommitted changes)
+    #   cmd = Git::Commands::Checkout::Files.new(lib)
+    #   cmd.call(pathspec: ['lib/my_file.rb'])
+    #
+    # @example Restore a file from a specific branch
+    #   cmd = Git::Commands::Checkout::Files.new(lib)
+    #   cmd.call('main', pathspec: ['lib/my_file.rb'])
+    #
+    module Checkout
+    end
+  end
+end

data/lib/git/commands/checkout_index.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git checkout-index` command
+    #
+    # This command copies all files listed in the index to the working directory
+    # (not overwriting existing files). It is typically used to populate a new
+    # working directory from the current index, optionally scoped to a specific
+    # path or prefix.
+    #
+    # @example Typical usage
+    #   checkout_index = Git::Commands::CheckoutIndex.new(execution_context)
+    #   checkout_index.call(all: true)
+    #   checkout_index.call(all: true, force: true)
+    #   checkout_index.call('path/to/file.txt')
+    #   checkout_index.call(all: true, prefix: 'output/')
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-checkout-index/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-checkout-index git-checkout-index
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class CheckoutIndex < Git::Commands::Base
+      arguments do
+        literal 'checkout-index'
+        flag_option %i[index u]
+        flag_option %i[quiet q]
+        flag_option %i[all a]
+        flag_option %i[force f]
+        flag_option %i[no_create n]
+        value_option :prefix, inline: true
+        value_option :stage, inline: true
+        flag_option :temp
+        flag_option :ignore_skip_worktree_bits
+        end_of_options
+        operand :file, required: false, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*file, **options)
+      #
+      #     Execute the `git checkout-index` command
+      #
+      #     @param file [Array<String>] zero or more file paths to check out
+      #
+      #       When empty, no files are checked out individually (use `:all` to check
+      #       out everything).
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :index (nil) update stat information for the
+      #       checked out entries in the index file
+      #
+      #       Alias: `:u`
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress messages when files
+      #       exist or are not in the index
+      #
+      #       Alias: `:q`
+      #
+      #     @option options [Boolean, nil] :all (nil) check out all files in the index
+      #
+      #       Alias: `:a`
+      #
+      #     @option options [Boolean, nil] :force (nil) force overwrite of existing files
+      #
+      #       Alias: `:f`
+      #
+      #     @option options [Boolean, nil] :no_create (nil) don't checkout new files,
+      #       only refresh files already checked out
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [String] :prefix (nil) write file content under the given
+      #       directory prefix instead of the working directory root
+      #
+      #     @option options [String] :stage (nil) check out from the named stage
+      #
+      #       Pass `'1'`, `'2'`, or `'3'` for a specific stage number, or `'all'` to
+      #       check out all stages (automatically implies `--temp`).
+      #
+      #     @option options [Boolean, nil] :temp (nil) write file content to temporary
+      #       files near the target location instead of checking them out
+      #
+      #     @option options [Boolean, nil] :ignore_skip_worktree_bits (nil) check out
+      #       all files, including those with the skip-worktree bit set
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git checkout-index`
+      #
+      #     @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/clean.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Remove untracked files from the working tree
+    #
+    # Cleans the working tree by recursively removing files that are not under
+    # version control. Only files unknown to Git are removed by default; with
+    # `:x` also removes ignored files; with `:X` removes only ignored files.
+    #
+    # @example Typical usage
+    #   clean = Git::Commands::Clean.new(execution_context)
+    #   clean.call(force: true)
+    #   clean.call(force: true, d: true)
+    #   clean.call(force: 2)
+    #   clean.call(dry_run: true)
+    #   clean.call(force: true, exclude: '*.log')
+    #   clean.call(force: true, X: true)
+    #   clean.call(force: true, pathspec: ['tmp/', 'build/'])
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-clean/2.53.0
+    #
+    # @see Git::Commands
+    #
+    # @see https://git-scm.com/docs/git-clean git-clean
+    #
+    # @api private
+    #
+    class Clean < Git::Commands::Base
+      arguments do
+        literal 'clean'
+        flag_option :d
+        flag_option %i[force f], max_times: 2
+        flag_option %i[dry_run n]
+        flag_option %i[quiet q]
+        value_option %i[exclude e], inline: true, repeatable: true
+        flag_option :x
+        flag_option :X
+        execution_option :chdir
+        end_of_options
+        value_option :pathspec, as_operand: true, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(**options)
+      #
+      #     Execute the git clean command
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :d (nil) recurse into untracked directories
+      #
+      #     @option options [Boolean, Integer, nil] :force (nil) force the removal of untracked files
+      #
+      #       When `clean.requireForce` is not set to `false`, git-clean will refuse to
+      #       delete files or directories unless this option is given.
+      #
+      #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit `--force --force`,
+      #       which also removes untracked nested git repositories (directories with a
+      #       `.git` subdirectory).
+      #
+      #       Alias: `:f`
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) don't actually remove anything, just
+      #       show what would be done
+      #
+      #       Alias: `:n`
+      #
+      #     @option options [Boolean, nil] :quiet (nil) be quiet, only report errors
+      #
+      #       Alias: `:q`
+      #
+      #     @option options [String, Array<String>] :exclude (nil) use the given exclude
+      #       pattern in addition to the standard ignore rules
+      #
+      #       May be specified multiple times. Alias: `:e`
+      #
+      #     @option options [Boolean, nil] :x (nil) don't use the standard ignore rules
+      #
+      #     @option options [Boolean, nil] :X (nil) remove only files ignored by Git
+      #
+      #     @option options [String, Array<String>] :pathspec (nil) limit cleaning to files
+      #       matching the given pathspec(s)
+      #
+      #     @option options [String, nil] :chdir (nil) change to this directory before
+      #       running git; not passed to the git CLI
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git clean`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #   @api public
+    end
+  end
+end