git 4.3.2 → 5.0.0.beta.1

data/lib/git/commands/ls_files.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git ls-files` command.
+    #
+    # This command shows information about files in the index and the working tree.
+    # It is used to list tracked, untracked, ignored, and staged files.
+    #
+    # @example List staged files with stage info
+    #   ls_files = Git::Commands::LsFiles.new(execution_context)
+    #   ls_files.call('.', stage: true)
+    #
+    # @example List untracked files not ignored
+    #   ls_files = Git::Commands::LsFiles.new(execution_context)
+    #   ls_files.call(others: true, exclude_standard: true)
+    #
+    # @example List ignored files
+    #   ls_files = Git::Commands::LsFiles.new(execution_context)
+    #   ls_files.call(others: true, ignored: true, exclude_standard: true)
+    #
+    # @example List untracked files in a specific directory
+    #   ls_files = Git::Commands::LsFiles.new(execution_context)
+    #   ls_files.call(others: true, exclude_standard: true, chdir: '/path/to/workdir')
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-ls-files/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-ls-files git-ls-files documentation
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    class LsFiles < Git::Commands::Base
+      arguments do
+        literal 'ls-files'
+        flag_option :z
+        flag_option :t
+        flag_option :v
+        flag_option :f
+        flag_option %i[cached c]
+        flag_option %i[deleted d]
+        flag_option %i[others o]
+        flag_option %i[ignored i]
+        flag_option %i[stage s]
+        flag_option %i[unmerged u]
+        flag_option %i[killed k]
+        flag_option %i[modified m]
+        flag_option :resolve_undo
+        flag_option :directory
+        flag_option :no_empty_directory
+        flag_option :eol
+        flag_option :deduplicate
+        value_option %i[exclude x], inline: true
+        value_option %i[exclude_from X], inline: true
+        value_option :exclude_per_directory, inline: true
+        flag_option :exclude_standard
+        flag_option :error_unmatch
+        value_option :with_tree, inline: true
+        flag_option :full_name
+        flag_option :recurse_submodules
+        flag_or_value_option :abbrev, inline: true
+        flag_option :debug
+        flag_option :sparse
+        value_option :format, inline: true
+
+        end_of_options
+
+        operand :file, repeatable: true
+
+        execution_option :chdir
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(*file, **options)
+      #
+      #     Execute the `git ls-files` command.
+      #
+      #     @param file [Array<String>] paths to limit file listing
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :z (nil) use NUL line termination and do not quote filenames
+      #
+      #     @option options [Boolean, nil] :t (nil) show status tags together with filenames
+      #
+      #     @option options [Boolean, nil] :v (nil) similar to `-t` but use lowercase letters for files
+      #       that are marked as assume unchanged
+      #
+      #     @option options [Boolean, nil] :f (nil) similar to `-t` but use lowercase letters for files
+      #       that are marked as fsmonitor valid
+      #
+      #     @option options [Boolean, nil] :cached (nil) show all files cached in the index
+      #
+      #       Alias: :c
+      #
+      #     @option options [Boolean, nil] :deleted (nil) show files with an unstaged deletion
+      #
+      #       Alias: :d
+      #
+      #     @option options [Boolean, nil] :others (nil) show other (i.e. untracked) files in the output
+      #
+      #       Alias: :o
+      #
+      #     @option options [Boolean, nil] :ignored (nil) show only ignored files in the output
+      #
+      #       Must be used with either `:cached` or `:others`. When used with `:cached`, shows only
+      #       cached files matching an exclude pattern. When used with `:others`, shows only
+      #       untracked files matched by an exclude pattern.
+      #
+      #       Alias: :i
+      #
+      #     @option options [Boolean, nil] :stage (nil) show object name, mode bits, and stage number
+      #
+      #       Alias: :s
+      #
+      #     @option options [Boolean, nil] :unmerged (nil) show information about unmerged files
+      #
+      #       Alias: :u
+      #
+      #     @option options [Boolean, nil] :killed (nil) show untracked files that need to be removed
+      #       due to file/directory conflicts for tracked files
+      #
+      #       Alias: :k
+      #
+      #     @option options [Boolean, nil] :modified (nil) show files with an unstaged modification
+      #
+      #       Alias: :m
+      #
+      #     @option options [Boolean, nil] :resolve_undo (nil) show files having resolve-undo information
+      #
+      #     @option options [Boolean, nil] :directory (nil) show just the directory name (with trailing
+      #       slash) when a whole directory is classified as "other"
+      #
+      #     @option options [Boolean, nil] :no_empty_directory (nil) do not list empty directories
+      #
+      #     @option options [Boolean, nil] :eol (nil) show EOL and encoding attributes of files
+      #
+      #     @option options [Boolean, nil] :deduplicate (nil) suppress duplicate filenames when showing
+      #       only filenames
+      #
+      #     @option options [String] :exclude (nil) skip untracked files matching the given pattern
+      #
+      #       Alias: :x
+      #
+      #     @option options [String] :exclude_from (nil) read exclude patterns from the given file
+      #
+      #       Alias: :X
+      #
+      #     @option options [String] :exclude_per_directory (nil) read additional exclude patterns
+      #       from the named file in each directory
+      #
+      #     @option options [Boolean, nil] :exclude_standard (nil) add the standard git exclusions
+      #
+      #     @option options [Boolean, nil] :error_unmatch (nil) treat unmatched files as an error
+      #
+      #     @option options [String] :with_tree (nil) pretend paths removed since the named
+      #       tree-ish are still present when using `--error-unmatch`
+      #
+      #     @option options [Boolean, nil] :full_name (nil) force paths to be output relative to the
+      #       project top-level directory
+      #
+      #     @option options [Boolean, nil] :recurse_submodules (nil) recursively calls ls-files on each
+      #       active submodule in the repository
+      #
+      #     @option options [Boolean, Integer, String, nil] :abbrev (nil) show only a partial prefix of the
+      #       object name; pass `true` for the default number of hex digits, or an Integer or String
+      #       for a specific prefix length (e.g., `abbrev: 10` or `abbrev: "10"`)
+      #
+      #     @option options [Boolean, nil] :debug (nil) after each filename, output raw index information
+      #       (ctime data, mtime data, dev, ino, uid, gid, size, flags, flagsx)
+      #
+      #     @option options [Boolean, nil] :sparse (nil) if the index is sparse, show the sparse directory
+      #       entries rather than expanding to the contained files
+      #
+      #     @option options [String] :format (nil) a string that interpolates %(fieldname) from
+      #       the index entry for each file
+      #
+      #     @option options [String] :chdir (nil) run the command from the specified directory
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git ls-files`
+      #
+      #     @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/ls_remote.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git ls-remote` command
+    #
+    # Lists references available in a remote repository along with the
+    # associated commit IDs. Can be used to detect changes in a remote
+    # repository without cloning or fetching.
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-ls-remote/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-ls-remote git-ls-remote documentation
+    #
+    # @see Git::Commands
+    #
+    # @api private
+    #
+    # @example List all refs in a remote
+    #   ls_remote = Git::Commands::LsRemote.new(execution_context)
+    #   ls_remote.call('origin')
+    #
+    # @example List only branches and tags
+    #   ls_remote = Git::Commands::LsRemote.new(execution_context)
+    #   ls_remote.call('origin', branches: true, tags: true)
+    #
+    # @example List only refs (no symbolic refs like HEAD)
+    #   ls_remote = Git::Commands::LsRemote.new(execution_context)
+    #   ls_remote.call('origin', refs: true)
+    #
+    # @example Filter by pattern
+    #   ls_remote = Git::Commands::LsRemote.new(execution_context)
+    #   ls_remote.call('origin', 'refs/heads/main')
+    #
+    # @example Detect the default branch of a remote
+    #   ls_remote = Git::Commands::LsRemote.new(execution_context)
+    #   ls_remote.call('origin', 'HEAD', symref: true)
+    #
+    class LsRemote < Git::Commands::Base
+      arguments do
+        literal 'ls-remote'
+
+        flag_option %i[branches b]
+        flag_option %i[heads h]
+        flag_option %i[tags t]
+        flag_option :refs
+
+        # Connectivity
+        value_option :upload_pack, inline: true
+
+        flag_option %i[quiet q]
+        flag_option :exit_code
+        flag_option :get_url
+        value_option :sort, inline: true
+        flag_option :symref
+
+        value_option %i[server_option o],
+                     inline: true, repeatable: true
+
+        # Execution-only options (not emitted as CLI flags)
+        execution_option :timeout
+
+        end_of_options
+
+        operand :repository
+        operand :pattern, repeatable: true
+      end
+
+      # Exit status 2 means no matching refs were found (used with --exit-code)
+      allow_exit_status 0..2
+
+      # @!method call(*, **)
+      #
+      #   @overload call(repository = nil, *patterns, **options)
+      #
+      #     Execute the `git ls-remote` command
+      #
+      #     @param repository [String, nil] The remote name or URL to query
+      #
+      #       When nil, git uses the remote inferred from the current branch's
+      #       tracking configuration, or "origin" if no tracking remote is set.
+      #
+      #     @param patterns [Array<String>] One or more ref patterns to filter results
+      #
+      #       When omitted, all references (after filtering via `--branches`, `--tags`,
+      #       `--refs`) are shown. When specified, only refs matching one or more
+      #       patterns are displayed.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :branches (nil) limit output to refs under `refs/heads/`
+      #
+      #       Alias: :b
+      #
+      #     @option options [Boolean, nil] :heads (nil) limit output to refs under `refs/heads/`
+      #
+      #       Deprecated: use `:branches` instead. Kept for backward compatibility with
+      #       older git versions where `--heads` is the only supported flag.
+      #
+      #       Alias: :h
+      #
+      #     @option options [Boolean, nil] :tags (nil) limit output to refs under `refs/tags/`
+      #
+      #       Alias: :t
+      #
+      #     @option options [Boolean, nil] :refs (nil) exclude peeled tags and pseudorefs
+      #       like `HEAD` from the output
+      #
+      #     @option options [String] :upload_pack (nil) full path to `git-upload-pack`
+      #       on the remote host
+      #
+      #       Useful when accessing repositories via SSH where the daemon does not
+      #       use the PATH configured by the user.
+      #
+      #     @option options [Boolean, nil] :quiet (nil) do not print the remote URL to stderr
+      #
+      #       Alias: :q
+      #
+      #     @option options [Boolean, nil] :exit_code (nil) exit with status `2` when no
+      #       matching refs are found in the remote repository
+      #
+      #       Without this option, the command exits `0` whenever it successfully
+      #       communicates with the remote, even if no refs match.
+      #
+      #     @option options [Boolean, nil] :get_url (nil) expand and print the remote URL
+      #       (respecting `url.<base>.insteadOf` config) and exit without contacting
+      #       the remote
+      #
+      #     @option options [String] :sort (nil) sort output by the given key
+      #
+      #       Prefix `-` for descending order. Supports `"version:refname"` or
+      #       `"v:refname"`. See `git for-each-ref` for sort key documentation.
+      #
+      #     @option options [Boolean, nil] :symref (nil) show the underlying ref pointed to by
+      #       symbolic refs
+      #
+      #       The `upload-pack` protocol currently surfaces only the `HEAD` symref,
+      #       so that is typically the only symref shown.
+      #
+      #     @option options [String, Array<String>] :server_option (nil) transmit a
+      #       string to the server when communicating using protocol version 2
+      #
+      #       The string must not contain NUL or LF characters. Repeatable by
+      #       passing an Array. Alias: :o
+      #
+      #     @option options [Numeric] :timeout (nil) execution timeout in seconds
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git ls-remote`
+      #
+      #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
+    end
+  end
+end

data/lib/git/commands/ls_tree.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    # Implements the `git ls-tree` command
+    #
+    # Lists the contents of a tree object, showing the mode, type, object
+    # name, and file name of each item. Supports recursive listing, output
+    # format control, and path filtering.
+    #
+    # @note `arguments` block audited against https://git-scm.com/docs/git-ls-tree/2.53.0
+    #
+    # @see https://git-scm.com/docs/git-ls-tree git-ls-tree
+    #
+    # @api private
+    #
+    # @example List the top-level tree of HEAD
+    #   ls_tree = Git::Commands::LsTree.new(execution_context)
+    #   ls_tree.call('HEAD')
+    #
+    # @example Recursively list all files under HEAD
+    #   ls_tree = Git::Commands::LsTree.new(execution_context)
+    #   ls_tree.call('HEAD', r: true)
+    #
+    # @example List only file names recursively
+    #   ls_tree = Git::Commands::LsTree.new(execution_context)
+    #   ls_tree.call('HEAD', r: true, name_only: true)
+    #
+    # @example List entries under a specific path
+    #   ls_tree = Git::Commands::LsTree.new(execution_context)
+    #   ls_tree.call('HEAD', 'lib/')
+    #
+    class LsTree < Git::Commands::Base
+      arguments do
+        literal 'ls-tree'
+
+        # Listing behavior
+        flag_option :d
+        flag_option :r
+        flag_option :t
+        flag_option %i[long l]
+        flag_option :z
+
+        # Output format
+        flag_option %i[name_only name_status]
+        flag_option :object_only
+        flag_option :full_name
+        flag_option :full_tree
+        flag_or_value_option :abbrev, inline: true
+        value_option :format, inline: true
+
+        end_of_options
+
+        operand :tree_ish, required: true
+        operand :path, repeatable: true
+      end
+
+      # @!method call(*, **)
+      #
+      #   @overload call(tree_ish, *path, **options)
+      #
+      #     Execute the git ls-tree command
+      #
+      #     @param tree_ish [String] the tree object to list (SHA, branch name, tag, etc.)
+      #
+      #     @param path [Array<String>] optional path(s) to restrict the listing
+      #
+      #       When given, only entries matching these paths are shown.
+      #
+      #     @param options [Hash] command options
+      #
+      #     @option options [Boolean, nil] :d (nil) show only the named tree entry itself,
+      #       not its children
+      #
+      #     @option options [Boolean, nil] :r (nil) recurse into sub-trees
+      #
+      #     @option options [Boolean, nil] :t (nil) show tree entries even when going to
+      #       recurse them
+      #
+      #       Implies recursive listing (`:r`) in git.
+      #
+      #     @option options [Boolean, nil] :long (nil) show object size of blob (file)
+      #       objects
+      #
+      #       Cannot be combined with `:name_only` or `:object_only`.
+      #
+      #       Alias: :l
+      #
+      #     @option options [Boolean, nil] :z (nil) use NUL (`\0`) as line terminator
+      #       instead of newline, and do not quote filenames
+      #
+      #     @option options [Boolean, nil] :name_only (nil) list only filenames, one per
+      #       line
+      #
+      #       Cannot be combined with `:object_only` or `:long`.
+      #
+      #       Alias: :name_status
+      #
+      #     @option options [Boolean, nil] :object_only (nil) list only the object names
+      #       (SHAs), one per line
+      #
+      #       Cannot be combined with `:name_only` or `:long`.
+      #
+      #     @option options [Boolean, nil] :full_name (nil) show full path names instead
+      #       of paths relative to the current working directory
+      #
+      #     @option options [Boolean, nil] :full_tree (nil) do not limit the listing to
+      #       the current working directory; implies `:full_name`
+      #
+      #     @option options [Boolean, String, nil] :abbrev (nil) use abbreviated object names
+      #
+      #       When `true`, uses git's default abbreviated name length. When a string
+      #       (e.g. `'8'`), uses exactly that many hex digits.
+      #
+      #     @option options [String] :format (nil) a format string that interpolates
+      #       `%(fieldname)` placeholders from tree entries
+      #
+      #       Cannot be combined with `:long`, `:name_only`, or `:object_only`.
+      #
+      #     @return [Git::CommandLineResult] the result of calling `git ls-tree`
+      #
+      #     @raise [ArgumentError] if unsupported options are provided
+      #
+      #     @raise [ArgumentError] if the tree-ish operand is missing
+      #
+      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+    end
+  end
+end

data/lib/git/commands/maintenance/register.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Maintenance
+      # Add the current repository to the maintenance config
+      #
+      # @example Register the repository for maintenance
+      #   Git::Commands::Maintenance::Register.new(execution_context).call
+      #
+      # @example Register with a custom config file
+      #   Git::Commands::Maintenance::Register.new(execution_context).call(config_file: '/path/to/config')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-maintenance/2.54.0
+      #
+      # @see Git::Commands::Maintenance Git::Commands::Maintenance for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-maintenance git-maintenance documentation
+      #
+      # @api private
+      #
+      class Register < Git::Commands::Base
+        requires_git_version '2.30.0'
+
+        arguments do
+          literal 'maintenance'
+          literal 'register'
+
+          flag_or_value_option :config_file, negatable: true
+          execution_option :env
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(**options)
+        #
+        #     Initialize config values so scheduled maintenance will start running
+        #
+        #     This adds the repository to the `maintenance.repo` config variable
+        #     in the current user's global config (or the specified config file)
+        #     and enables recommended configuration values for
+        #     `maintenance.<task>.schedule`.
+        #
+        #     Also sets `maintenance.strategy` to 'incremental' if not previously set,
+        #     and disables foreground maintenance by setting `maintenance.auto = false`
+        #     in the current repository.
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, String, nil] :config_file (nil) use a specified
+        #       config file instead of the global config (`--config-file`)
+        #
+        #       When a String, the path is passed as `--config-file <file>`.
+        #
+        #     @option options [Boolean, nil] :no_config_file (nil) disable the config file
+        #       (`--no-config-file`)
+        #
+        #     @option options [Hash] :env (nil) environment variables to set for the git
+        #       process; merged with the default environment; not passed to the git CLI
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git maintenance register`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @raise [Git::VersionError] if git version is below 2.30.0
+        #
+        #     @api public
+      end
+    end
+  end
+end

data/lib/git/commands/maintenance/run.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'git/commands/base'
+
+module Git
+  module Commands
+    module Maintenance
+      # Run one or more maintenance tasks
+      #
+      # @example Run all enabled maintenance tasks
+      #   Git::Commands::Maintenance::Run.new(execution_context).call
+      #
+      # @example Run specific tasks in order
+      #   Git::Commands::Maintenance::Run.new(execution_context).call(task: ['gc', 'commit-graph'])
+      #
+      # @example Run tasks only if thresholds are met
+      #   Git::Commands::Maintenance::Run.new(execution_context).call(auto: true)
+      #
+      # @example Run scheduled tasks at a specific frequency
+      #   Git::Commands::Maintenance::Run.new(execution_context).call(schedule: 'hourly')
+      #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-maintenance/2.54.0
+      #
+      # @see Git::Commands::Maintenance Git::Commands::Maintenance for the full sub-command list
+      #
+      # @see https://git-scm.com/docs/git-maintenance git-maintenance documentation
+      #
+      # @api private
+      #
+      class Run < Git::Commands::Base
+        requires_git_version '2.30.0'
+
+        arguments do
+          literal 'maintenance'
+          literal 'run'
+
+          flag_option :auto, negatable: true
+          flag_option :detach, negatable: true
+          flag_option :scheduled, negatable: true
+          flag_or_value_option :schedule, negatable: true, inline: true
+          flag_option :quiet, negatable: true
+          value_option :task, inline: true, repeatable: true
+          execution_option :env
+        end
+
+        # @!method call(*, **)
+        #
+        #   @overload call(**options)
+        #
+        #     Run one or more maintenance tasks
+        #
+        #     @param options [Hash] command options
+        #
+        #     @option options [Boolean, nil] :auto (nil) run tasks only if thresholds are met (`--auto`)
+        #
+        #       Not compatible with the `:schedule` option.
+        #
+        #     @option options [Boolean, nil] :no_auto (nil) disable threshold-based execution (`--no-auto`)
+        #
+        #     @option options [Boolean, nil] :detach (nil) detach the maintenance process from the current terminal
+        #       (`--detach`)
+        #
+        #     @option options [Boolean, nil] :no_detach (nil) do not detach the maintenance process (`--no-detach`)
+        #
+        #     @option options [Boolean, nil] :scheduled (nil) run tasks that are due according to schedule config
+        #       (`--scheduled`)
+        #
+        #     @option options [Boolean, nil] :no_scheduled (nil) do not limit runs to scheduled tasks (`--no-scheduled`)
+        #
+        #     @option options [Boolean, String, nil] :schedule (nil) run tasks only if time conditions are met
+        #       (`--schedule`)
+        #
+        #       When a String (`'hourly'`, `'daily'`, or `'weekly'`), runs only tasks scheduled
+        #       for that frequency; the string is emitted as `--schedule=<frequency>`.
+        #
+        #     @option options [Boolean, nil] :no_schedule (nil) disable schedule-based filtering (`--no-schedule`)
+        #
+        #     @option options [Boolean, nil] :quiet (nil) suppress progress and informational messages (`--quiet`)
+        #
+        #     @option options [Boolean, nil] :no_quiet (nil) enable progress and informational messages (`--no-quiet`)
+        #
+        #     @option options [Array<String>, String] :task (nil) specify which task(s) to run
+        #
+        #       If specified, only the given tasks are run in the specified order.
+        #       Otherwise, tasks are determined by config options.
+        #       Valid task names: `commit-graph`, `prefetch`, `gc`, `loose-objects`,
+        #       `incremental-repack`, `pack-refs`, `reflog-expire`, `rerere-gc`, `worktree-prune`.
+        #
+        #     @option options [Hash] :env (nil) environment variables to set for the git
+        #       process; merged with the default environment; not passed to the git CLI
+        #
+        #     @return [Git::CommandLineResult] the result of calling `git maintenance run`
+        #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @raise [Git::VersionError] if git version is below 2.30.0
+        #
+        #     @api public
+      end
+    end
+  end
+end