git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/fetch.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git fetch` command
+    #
+    # Downloads objects and refs from another repository. Fetches branches
+    # and/or tags from one or more other repositories, along with the objects
+    # necessary to complete their histories.
+    #
+    # @example Typical usage
+    #   fetch = Git::Commands::Fetch.new(execution_context)
+    #   fetch.call
+    #   fetch.call('origin')
+    #   fetch.call('origin', 'refs/heads/main')
+    #   fetch.call(all: true, prune: true)
+    #   fetch.call('origin', merge: true)
+    #
+    # @note `arguments` block audited against
+    #   https://git-scm.com/docs/git-fetch/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-fetch git-fetch
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Fetch < Git::Commands::Base
+      arguments do
+        literal 'fetch'
+
+        # Remote scope
+        flag_option :all, negatable: true
+        flag_option %i[append a]
+        flag_option :atomic
+
+        # Shallow clone controls
+        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
+
+        # Negotiation
+        value_option :negotiation_tip, inline: true, repeatable: true
+        flag_option :negotiate_only
+
+        # Output and dry-run
+        flag_option :dry_run
+        flag_option :porcelain
+        flag_option :write_fetch_head, negatable: true
+
+        # Safety and update control
+        flag_option %i[force f]
+        flag_option %i[keep k]
+        flag_option :multiple
+
+        # Maintenance
+        flag_option :auto_maintenance, negatable: true
+        flag_option :auto_gc, negatable: true
+        flag_option :write_commit_graph, negatable: true
+
+        # Prefetching
+        flag_option :prefetch
+
+        # Pruning
+        flag_option %i[prune p]
+        flag_option %i[prune_tags P]
+
+        # Refetching and refmapping
+        flag_option :refetch
+        value_option :refmap, inline: true, repeatable: true
+
+        # Tag handling
+        flag_option %i[tags t], negatable: true
+
+        # Submodules
+        flag_or_value_option :recurse_submodules,
+                             inline: true, negatable: true
+
+        # Parallelism
+        value_option %i[jobs j], inline: true
+
+        # Tracking and internal plumbing
+        flag_option :set_upstream
+        value_option :submodule_prefix, inline: true
+        value_option :recurse_submodules_default, inline: true
+        flag_option %i[update_head_ok u]
+        value_option :upload_pack
+
+        # Output verbosity
+        flag_option %i[quiet q]
+        flag_option %i[verbose v]
+        flag_option :progress
+
+        # Protocol and connectivity
+        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]
+
+        # Stdin
+        flag_option :stdin
+
+        # Execution-only options (not emitted as CLI flags)
+        execution_option :timeout
+        execution_option :merge
+
+        end_of_options
+        operand :repository
+        operand :refspec, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(repository = nil, *refspec, **options)
+      #
+      #     Execute the `git fetch` command
+      #
+      #     @param repository [String, nil] (nil) the remote name or URL to fetch from
+      #
+      #       When nil, git uses the default remote configured for the current branch.
+      #
+      #     @param refspec [Array<String>] one or more refspecs to fetch
+      #
+      #       Each may be a branch name, a refspec pattern such as
+      #       `+refs/heads/*:refs/remotes/origin/*`, or a commit SHA.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @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 of fetched refs 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 specified
+      #       number of commits from the tip of each remote branch history
+      #
+      #     @option options [String] :deepen (nil) deepen or shorten history by
+      #       the specified number of commits from the current shallow boundary
+      #
+      #     @option options [String] :shallow_since (nil) deepen or shorten the
+      #       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, or fetch as much as possible from
+      #       a shallow source
+      #
+      #     @option options [Boolean, nil] :update_shallow (nil) accept refs that
+      #       would normally require updating `.git/shallow`
+      #
+      #     @option options [String, Array<String>] :negotiation_tip (nil) only
+      #       report commits reachable from the given tips when negotiating
+      #
+      #       Repeatable. The argument may be a ref, a glob on ref names, or an
+      #       abbreviated SHA-1.
+      #
+      #     @option options [Boolean, nil] :negotiate_only (nil) do not fetch
+      #       anything from the server; print ancestors of `--negotiation-tip`
+      #       arguments that we have in common
+      #
+      #     @option options [Boolean, nil] :dry_run (nil) show what would be done
+      #       without making changes
+      #
+      #     @option options [Boolean, nil] :porcelain (nil) print the output to
+      #       standard output in an easy-to-parse format for scripts
+      #
+      #     @option options [Boolean, nil] :write_fetch_head (nil) write the fetched
+      #       remote refs to `.git/FETCH_HEAD` (`--write-fetch-head`)
+      #
+      #     @option options [Boolean, nil] :no_write_fetch_head (nil) do not write
+      #       fetched remote refs to `.git/FETCH_HEAD` (`--no-write-fetch-head`)
+      #
+      #     @option options [Boolean, nil] :force (nil) override the fast-forward
+      #       check when using explicit refspecs
+      #
+      #       Alias: :f
+      #
+      #     @option options [Boolean, nil] :keep (nil) keep the downloaded pack
+      #
+      #       Alias: :k
+      #
+      #     @option options [Boolean, nil] :multiple (nil) allow several repository
+      #       and group arguments to be specified
+      #
+      #       When using this option, pass additional repository or group names
+      #       as extra positional arguments; they are bound to the `:refspec`
+      #       slot in the DSL but are passed through to git correctly.
+      #
+      #     @option options [Boolean, nil] :auto_maintenance (nil) run automatic
+      #       repository maintenance after fetching (`--auto-maintenance`)
+      #
+      #     @option options [Boolean, nil] :no_auto_maintenance (nil) do not run
+      #       automatic repository maintenance after fetching
+      #       (`--no-auto-maintenance`)
+      #
+      #     @option options [Boolean, nil] :auto_gc (nil) run automatic garbage
+      #       collection after fetching — deprecated alias for `:auto_maintenance`
+      #       (`--auto-gc`)
+      #
+      #     @option options [Boolean, nil] :no_auto_gc (nil) do not run automatic
+      #       garbage collection after fetching (`--no-auto-gc`)
+      #
+      #     @option options [Boolean, nil] :write_commit_graph (nil) write a
+      #       commit-graph after fetching (`--write-commit-graph`)
+      #
+      #     @option options [Boolean, nil] :no_write_commit_graph (nil) do not write
+      #       a commit-graph after fetching (`--no-write-commit-graph`)
+      #
+      #     @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) before fetching, remove any
+      #       remote-tracking references that no longer exist on the remote
+      #
+      #       Alias: :p
+      #
+      #     @option options [Boolean, nil] :prune_tags (nil) before fetching, remove
+      #       any local tags that no longer exist on the remote (requires
+      #       `--prune`)
+      #
+      #       Alias: :P
+      #
+      #     @option options [Boolean, nil] :refetch (nil) fetch all objects as a
+      #       fresh clone would, bypassing negotiation
+      #
+      #     @option options [String, Array<String>] :refmap (nil) use the
+      #       specified refspec to map refs to remote-tracking branches instead
+      #       of the configured `remote.*.fetch` values
+      #
+      #       Repeatable.
+      #
+      #     @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 [Boolean, String, nil] :recurse_submodules (nil) control
+      #       whether new commits of submodules should be fetched
+      #
+      #       When `true`, uses `--recurse-submodules`. When a string (e.g.
+      #       `'yes'`, `'on-demand'`, `'no'`), passes that value.
+      #
+      #     @option options [Boolean, nil] :no_recurse_submodules (nil) do not
+      #       recurse into submodules (`--no-recurse-submodules`)
+      #
+      #     @option options [String] :jobs (nil) number of submodules or parallel
+      #       fetches
+      #
+      #       Alias: :j
+      #
+      #     @option options [Boolean, nil] :set_upstream (nil) add upstream tracking
+      #       reference if the remote is fetched successfully
+      #
+      #     @option options [String] :submodule_prefix (nil) prepend the given
+      #       path to informative messages such as "Fetching submodule foo"
+      #
+      #       Used internally when recursing over submodules.
+      #
+      #     @option options [String] :recurse_submodules_default (nil) provide a
+      #       non-negative default value for `--recurse-submodules`
+      #
+      #       Used internally.
+      #
+      #     @option options [Boolean, nil] :update_head_ok (nil) allow updating the
+      #       HEAD that corresponds to the current branch
+      #
+      #       Used internally by `git pull`.
+      #
+      #       Alias: :u
+      #
+      #     @option options [String] :upload_pack (nil) specify a non-default
+      #       path for `git-upload-pack` on the remote side
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress all output
+      #
+      #       Alias: :q
+      #
+      #     @option options [Boolean, nil] :verbose (nil) be verbose
+      #
+      #       Alias: :v
+      #
+      #     @option options [Boolean, nil] :progress (nil) force progress status on
+      #       standard error even when the stream is not attached to a terminal
+      #
+      #     @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 for
+      #       force-updated branches during fetch (`--show-forced-updates`)
+      #
+      #     @option options [Boolean, nil] :no_show_forced_updates (nil) do not
+      #       check for force-updated branches during fetch
+      #       (`--no-show-forced-updates`)
+      #
+      #     @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 [Boolean, nil] :stdin (nil) read refspecs from stdin in
+      #       addition to those provided as arguments
+      #
+      #     @option options [Numeric, nil] :timeout (nil) maximum seconds to wait
+      #       for the command to complete
+      #
+      #       If nil, uses the global timeout from {Git::Config}.
+      #
+      #     @option options [Boolean, nil] :merge (nil) merge stderr into stdout in
+      #       the returned result
+      #
+      #       Pass `true` to capture git fetch output (which is written to stderr
+      #       by default).
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git fetch`
+      #
+      #     @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/fsck.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git fsck` command
+    #
+    # Verifies the connectivity and validity of objects in the database.
+    # It checks the integrity of the repository, reporting any dangling, missing, or
+    # unreachable objects.
+    #
+    # @example Typical usage
+    #   fsck = Git::Commands::Fsck.new(execution_context)
+    #   fsck.call
+    #   fsck.call('abc1234', 'def5678')
+    #   fsck.call(unreachable: true, strict: true)
+    #   fsck.call(no_dangling: true)
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-fsck/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-fsck git-fsck
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Fsck < Git::Commands::Base
+      arguments do
+        literal 'fsck'
+        flag_option :progress, negatable: true
+
+        # Ref reporting
+        flag_option :tags
+        flag_option :root
+        flag_option :unreachable
+        flag_option :cache
+        flag_option :no_reflogs
+
+        # Checking scope
+        flag_option :full, negatable: true
+        flag_option :strict
+        flag_option :verbose
+        flag_option :lost_found
+
+        # Output control
+        flag_option :dangling, negatable: true
+        flag_option :connectivity_only
+        flag_option :name_objects, negatable: true
+        flag_option :references, negatable: true
+
+        operand :object, repeatable: true
+      end
+
+      # git fsck uses exit codes 0-7 as bit flags for findings
+      allow_exit_status 0..7
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*object, **options)
+      #
+      #     Execute the `git fsck` command
+      #
+      #     @param object [Array<String>] zero or more object identifiers to check
+      #
+      #       When none are given, git fsck defaults to using the index file and
+      #       all references as heads.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :tags (nil) report tags
+      #
+      #     @option options [Boolean, nil] :root (nil) report root nodes
+      #
+      #     @option options [Boolean, nil] :unreachable (nil) print out objects that
+      #       exist but are not reachable from any of the reference nodes
+      #
+      #     @option options [Boolean, nil] :cache (nil) consider any object recorded
+      #       in the index also as a head node for reachability
+      #
+      #     @option options [Boolean, nil] :no_reflogs (nil) do not consider commits
+      #       referenced only by reflogs to be reachable
+      #
+      #     @option options [Boolean, nil] :full (nil) check not just objects in
+      #       `GIT_OBJECT_DIRECTORY` but also those in alternate object pools and
+      #       packed archives (`--full`)
+      #
+      #     @option options [Boolean, nil] :no_full (nil) skip checking alternate object
+      #       pools and packed archives (`--no-full`)
+      #
+      #     @option options [Boolean, nil] :strict (nil) enable more strict checking,
+      #       catching files with `g+w` bits set
+      #
+      #     @option options [Boolean, nil] :verbose (nil) be chatty
+      #
+      #     @option options [Boolean, nil] :lost_found (nil) write dangling objects
+      #       into `.git/lost-found/commit/` or `.git/lost-found/other/`
+      #
+      #     @option options [Boolean, nil] :dangling (nil) print dangling objects (`--dangling`)
+      #
+      #     @option options [Boolean, nil] :no_dangling (nil) suppress dangling object
+      #       reporting (`--no-dangling`)
+      #
+      #     @option options [Boolean, nil] :progress (nil) show progress status on
+      #       standard error (`--progress`)
+      #
+      #     @option options [Boolean, nil] :no_progress (nil) suppress progress output
+      #       when attached to a terminal (`--no-progress`)
+      #
+      #     @option options [Boolean, nil] :connectivity_only (nil) check only the
+      #       connectivity of reachable objects; faster but does not validate
+      #       blob content
+      #
+      #     @option options [Boolean, nil] :name_objects (nil) show the name of each
+      #       reachable object alongside its identifier (`--name-objects`)
+      #
+      #     @option options [Boolean, nil] :no_name_objects (nil) suppress object name
+      #       display (`--no-name-objects`)
+      #
+      #     @option options [Boolean, nil] :references (nil) check reference database
+      #       consistency via `git refs verify` (`--references`)
+      #
+      #     @option options [Boolean, nil] :no_references (nil) skip reference checking
+      #       (`--no-references`)
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git fsck`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits outside the allowed range
+      #       (exit code > 7)
+      #
+      #     @api public
+    end
+  end
+end

data/lib/git/commands/gc.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git gc` command
+    #
+    # Runs a number of housekeeping tasks within the current repository, such as
+    # compressing file revisions (to reduce disk space and increase performance),
+    # removing unreachable objects, packing refs, pruning reflog, rerere metadata
+    # or stale working trees.
+    #
+    # @example Typical usage
+    #   gc = Git::Commands::Gc.new(execution_context)
+    #   gc.call
+    #   gc.call(auto: true)
+    #   gc.call(aggressive: true, prune: 'now')
+    #
+    # @note `arguments` block audited against
+    #   https://git-scm.com/docs/git-gc/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-gc git-gc
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class Gc < Git::Commands::Base
+      arguments do
+        literal 'gc'
+
+        # Optimization
+        flag_option :aggressive
+        flag_option :auto
+
+        # Background
+        flag_option :detach, negatable: true
+
+        # Cruft packs
+        flag_option :cruft, negatable: true
+        value_option :max_cruft_size, inline: true
+        value_option :expire_to, inline: true
+
+        # Pruning
+        flag_or_value_option :prune, negatable: true, inline: true
+
+        # Output control
+        flag_option :quiet
+
+        # Safety / override
+        flag_option :force
+        flag_option :keep_largest_pack
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(**options)
+      #
+      #     Execute the `git gc` command
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :aggressive (nil) be more thorough at the
+      #       expense of increased runtime
+      #
+      #       When `true`, git gc runs more aggressively to optimize the repository.
+      #       The effects are mostly persistent.
+      #
+      #     @option options [Boolean, nil] :auto (nil) check whether housekeeping is
+      #       required before performing any work
+      #
+      #       When `true`, git gc checks whether housekeeping is needed; if not, it
+      #       exits without doing anything.
+      #
+      #     @option options [Boolean, nil] :detach (nil) run in the background if the
+      #       system supports it (`--detach`)
+      #
+      #       Overrides the `gc.autoDetach` configuration.
+      #
+      #     @option options [Boolean, nil] :no_detach (nil) run in the foreground
+      #       (`--no-detach`)
+      #
+      #       Overrides the `gc.autoDetach` configuration.
+      #
+      #     @option options [Boolean, nil] :cruft (nil) pack unreachable objects into a
+      #       cruft pack instead of storing them as loose objects (`--cruft`)
+      #
+      #     @option options [Boolean, nil] :no_cruft (nil) do not create a cruft pack;
+      #       store unreachable objects as loose objects (`--no-cruft`)
+      #
+      #     @option options [String] :max_cruft_size (nil) limit the size of new
+      #       cruft packs to at most `<n>` bytes when packing unreachable objects
+      #
+      #       Overrides any value specified via `gc.maxCruftSize` configuration.
+      #       Maps to `--max-cruft-size=<n>`.
+      #
+      #     @option options [String] :expire_to (nil) write a cruft pack containing
+      #       pruned objects (if any) to the given directory
+      #
+      #       Only has an effect when used together with `:cruft`. Maps to
+      #       `--expire-to=<dir>`.
+      #
+      #     @option options [Boolean, String, nil] :prune (nil) prune loose objects
+      #       older than the given date (`--prune`, `--prune=<date>`)
+      #
+      #       When `true`, passes `--prune` (uses git's default expiry of 2 weeks
+      #       ago). When a String, passes `--prune=<date>`.
+      #
+      #     @option options [Boolean, nil] :no_prune (nil) do not prune any loose
+      #       objects (`--no-prune`)
+      #
+      #     @option options [Boolean, nil] :quiet (nil) suppress all progress reports
+      #
+      #     @option options [Boolean, nil] :force (nil) force running gc even if
+      #       another gc instance may be running on this repository
+      #
+      #     @option options [Boolean, nil] :keep_largest_pack (nil) repack all packs
+      #       except the largest non-cruft pack and those marked with a `.keep` file
+      #
+      #       When `true`, `gc.bigPackThreshold` is ignored.
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git gc`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      #     @api public
+    end
+  end
+end