git 5.0.0.beta.3 → 5.0.0.beta.4

data/lib/git/repository/diffing.rb

@@ -17,7 +17,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Diffing
       # Option keys accepted by {#diff_full}
@@ -133,10 +133,11 @@ module Git
       #   repo.diff_numstat('abc1234', 'def5678')
       #
       # @example Get working tree changes since HEAD
-      #   repo.diff_numstat #=> {
-      #     total: { insertions: 5, deletions: 2, lines: 7, files: 1 },
-      #     files: { "lib/foo.rb" => { insertions: 5, deletions: 2 } }
-      #   }
+      #   repo.diff_numstat
+      #   #=> {
+      #   #     total: { insertions: 5, deletions: 2, lines: 7, files: 1 },
+      #   #     files: { "lib/foo.rb" => { insertions: 5, deletions: 2 } }
+      #   #   }
       #
       # @example Get unstaged changes (index vs. working tree)
       #   repo.diff_numstat(nil) #=> { ... }
@@ -387,11 +388,6 @@ module Git
       # (staging area) and the working directory. These are changes that have
       # been made to tracked files but not yet staged.
       #
-      # @note The field names in the returned hash are **legacy names** inherited
-      #   from `Git::Lib#diff_files` and appear counterintuitive: `:mode_repo`
-      #   and `:sha_repo` hold **index (staging area)** values, while
-      #   `:mode_index` and `:sha_index` hold **working tree** values.
-      #
       # @example List all files with unstaged changes
       #   repo.diff_files
       #   #=> {
@@ -418,6 +414,11 @@ module Git
       #
       # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
       #
+      # @note The field names in the returned hash are **legacy names** inherited
+      #   from `Git::Lib#diff_files` and appear counterintuitive: `:mode_repo`
+      #   and `:sha_repo` hold **index (staging area)** values, while
+      #   `:mode_index` and `:sha_index` hold **working tree** values.
+      #
       # @see https://git-scm.com/docs/git-diff-files git-diff-files documentation
       #
       def diff_files
@@ -437,18 +438,6 @@ module Git
       # This is equivalent to the 4.x `Git::Lib#diff_index` behavior, which also
       # ran `git diff-index` without `--cached`.
       #
-      # @note `git diff-index` without `--cached` uses the index as a stat cache:
-      #   any file whose index entry differs from the tree is reported as changed,
-      #   even when the on-disk working-tree content is byte-for-byte identical to
-      #   the tree. A staged change that has been reverted in the working tree will
-      #   therefore still appear in the result (because the index still differs from
-      #   the tree).
-      #
-      # @note The field names in the returned hash are **legacy names** inherited
-      #   from `Git::Lib#diff_index` and appear counterintuitive: `:mode_repo`
-      #   and `:sha_repo` hold **tree (treeish)** values, while `:mode_index` and
-      #   `:sha_index` hold **working tree** values.
-      #
       # @example List all working-tree files that differ from HEAD
       #   repo.diff_index('HEAD')
       #   #=> {
@@ -478,6 +467,18 @@ module Git
       #
       # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
       #
+      # @note `git diff-index` without `--cached` uses the index as a stat cache:
+      #   any file whose index entry differs from the tree is reported as changed,
+      #   even when the on-disk working-tree content is byte-for-byte identical to
+      #   the tree. A staged change that has been reverted in the working tree will
+      #   therefore still appear in the result (because the index still differs from
+      #   the tree).
+      #
+      # @note The field names in the returned hash are **legacy names** inherited
+      #   from `Git::Lib#diff_index` and appear counterintuitive: `:mode_repo`
+      #   and `:sha_repo` hold **tree (treeish)** values, while `:mode_index` and
+      #   `:sha_index` hold **working tree** values.
+      #
       # @see https://git-scm.com/docs/git-diff-index git-diff-index documentation
       #
       def diff_index(treeish)
@@ -502,6 +503,12 @@ module Git
         #
         # @param opts [Hash] the options hash from {#diff_path_status}
         #
+        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+        #   primary path limiter value used as-is when present
+        #
+        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
+        #   **deprecated** — fallback path limiter when `:path_limiter` is not provided
+        #
         # @return [String, Pathname, Array<String, Pathname>, nil]
         #   the effective path limiter
         #
@@ -545,7 +552,7 @@ module Git
         #
         # @param pathspecs [Array<String>, nil] path limiters
         #
-        # @return [Git::CommandLineResult] the result of calling `git diff`
+        # @return [Git::CommandLine::Result] the result of calling `git diff`
         #
         def call_diff_command(execution_context, from, to, pathspecs)
           Git::Commands::Diff.new(execution_context).call(
@@ -624,6 +631,7 @@ module Git
         # Parses a single raw `git diff-files` output line into a path/entry pair
         #
         # @param line [String] a single non-empty line containing a tab character
+        #
         # @param tab_pos [Integer] the index of the first tab in the line
         #
         # @return [Array(String, Hash)] two-element array of `[path, entry_hash]`
@@ -637,6 +645,7 @@ module Git
         # Builds a single file-info hash for {#parse_diff_files_output}
         #
         # @param path [String] the file path
+        #
         # @param parts [Array<String>] the whitespace-split fields from the info
         #   portion of the diff-files line: `[mode_src, mode_dest, sha_src,
         #   sha_dest, type]`

data/lib/git/repository/factories.rb

@@ -9,32 +9,31 @@ require 'pathname'
 
 module Git
   class Repository
-    # Factory class methods for constructing {Git::Repository} instances
+    # Implementation of the {Git} module factory entry points
     #
-    # The four public factories — {clone}, {init}, {open}, {bare} — mirror the
-    # top-level `Git.*` entry points and return a {Git::Repository}.
+    # Provides `.open`, `.init`, `.clone`, and `.bare` — the four methods that
+    # construct a {Git::Repository}. Extended onto the {Git} module so that
+    # `Git.open(...)`, `Git.init(...)`, etc. resolve here.
     #
-    # Extended by {Git::Repository}.
-    #
-    # @api public
+    # @api private
     #
     module Factories # rubocop:disable Metrics/ModuleLength
       # Clone a repository into a new directory
       #
       # @example Clone into the default directory
-      #   repository = Git::Repository.clone('https://github.com/ruby-git/ruby-git.git')
+      #   repository = Git.clone('https://github.com/ruby-git/ruby-git.git')
       #
       # @example Clone into a specific directory
       #   repo_url = 'https://github.com/ruby-git/ruby-git.git'
-      #   repository = Git::Repository.clone(repo_url, 'local')
+      #   repository = Git.clone(repo_url, 'local')
       #
       # @example Clone a bare repository
       #   repo_url = 'https://github.com/ruby-git/ruby-git.git'
-      #   repository = Git::Repository.clone(repo_url, nil, bare: true)
+      #   repository = Git.clone(repo_url, nil, bare: true)
       #
-      # @param repository_url [String] the URL or path of the repository to clone
+      # @param repository_url [String, URI, Pathname] the URL or path of the repository to clone
       #
-      # @param directory [String, nil] the local directory name to clone into;
+      # @param directory [String, Pathname, nil] the local directory name to clone into;
       #   git derives the name from the URL when `nil`
       #
       # @param options [Hash] options that control cloning
@@ -187,13 +186,13 @@ module Git
       # Create an empty Git repository or reinitialize an existing one
       #
       # @example Initialize in the current directory
-      #   repository = Git::Repository.init
+      #   repository = Git.init
       #
       # @example Initialize in a specific directory
-      #   repository = Git::Repository.init('/path/to/project')
+      #   repository = Git.init('/path/to/project')
       #
       # @example Initialize a bare repository
-      #   repository = Git::Repository.init('/path/to/project.git', bare: true)
+      #   repository = Git.init('/path/to/project.git', bare: true)
       #
       # @param directory [String] the directory to initialize; defaults to `'.'`
       #
@@ -249,11 +248,8 @@ module Git
 
       # Open a working copy at an existing path
       #
-      # Note: this method opens working copies only. To open a bare repository, use
-      # `Git::Repository.bare`.
-      #
       # @example Open the working copy in the current directory
-      #   repository = Git::Repository.open('.')
+      #   repository = Git.open('.')
       #
       # @param working_dir [String] the path to the root of the working copy
       #
@@ -288,6 +284,9 @@ module Git
       # @raise [ArgumentError] if `working_dir` is not a directory or is not inside
       #   a git working tree
       #
+      # @note This method opens working copies only. To open a bare repository, use
+      #   `Git.bare`.
+      #
       # @api public
       #
       def open(working_dir, options = {})
@@ -307,7 +306,7 @@ module Git
       # Open an existing bare repository at `git_dir`
       #
       # @example Open a bare repository
-      #   repository = Git::Repository.bare('/path/to/repo.git')
+      #   repository = Git.bare('/path/to/repo.git')
       #
       # @param git_dir [String] the path to the bare repository directory
       #
@@ -341,16 +340,27 @@ module Git
 
       # Run the `git clone` command using a global execution context
       #
-      # @param repository_url [String] the URL or path of the repository to clone
+      # @param repository_url [String, URI, Pathname] the URL or path of the repository to clone
       #
-      # @param directory [String, nil] the local directory name to clone into
+      # @param directory [String, Pathname, nil] the local directory name to clone into
       #
       # @param opts [Hash] command-ready clone options
       #
       # @param context_opts [Hash] context options produced while preparing clone
       #   options
       #
-      # @return [Git::CommandLineResult] the result of running `git clone`
+      # @option opts [Boolean, nil] :bare clone as a bare repository
+      #
+      # @option context_opts [String, :use_global_config] :binary_path path to
+      #   the git binary
+      #
+      # @option context_opts [String, nil, :use_global_config] :git_ssh path to
+      #   a custom SSH executable
+      #
+      # @option context_opts [Logger, nil] :logger logger used for clone
+      #   operations
+      #
+      # @return [Git::CommandLine::Result] the result of running `git clone`
       #
       # @raise [ArgumentError] if unsupported options are provided
       #
@@ -370,13 +380,23 @@ module Git
 
       # Resolve repository paths from a completed clone result
       #
-      # @param clone_result [Git::CommandLineResult] the completed clone result
+      # @param clone_result [Git::CommandLine::Result] the completed clone result
       #
       # @param opts [Hash] command-ready clone options
       #
       # @param context_opts [Hash] context options produced while preparing clone
       #   options
       #
+      # @option opts [String, Pathname, nil] :chdir run `git clone` from within
+      #   this directory
+      #
+      # @option opts [Boolean, nil] :bare clone as a bare repository
+      #
+      # @option opts [Boolean, nil] :mirror set up a mirror of the source
+      #
+      # @option context_opts [String, nil] :index custom index path for the
+      #   returned repository
+      #
       # @return [Hash{Symbol => (String, nil)}] resolved path hash
       #
       # @raise [Git::UnexpectedResultError] if the clone directory cannot be parsed
@@ -417,6 +437,12 @@ module Git
       #
       # @param options [Hash] the caller-supplied options hash
       #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
       # @return [Hash] context defaults with two keys: `:binary_path`
       #   (`String` or `:use_global_config` — `nil` is not valid and raises
       #   `ArgumentError` in {Git::ExecutionContext#initialize}) and `:git_ssh`
@@ -437,6 +463,12 @@ module Git
       #
       # @param options [Hash] the caller-supplied options hash from {.open}
       #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
       # @return [String] the absolute path to the root of the working tree
       #
       # @raise [ArgumentError] if `working_dir` is not inside a git working tree
@@ -454,12 +486,20 @@ module Git
       #
       # @param paths [Hash{Symbol => (String, nil)}] the resolved paths
       #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [Logger, nil] :log logger used for git operations
+      #
       # @return [Git::Repository] the constructed repository
       #
       # @api private
       #
       def from_paths(options, paths)
-        new(execution_context: Git::ExecutionContext::Repository.from_hash(
+        Git::Repository.new(execution_context: Git::ExecutionContext::Repository.from_hash(
           options.merge(paths), logger: options[:log]
         ))
       end
@@ -475,6 +515,8 @@ module Git
       #
       # @param options [Hash] raw caller-supplied options
       #
+      # @option options [Boolean, nil] :bare clone as a bare repository
+      #
       # @return [Array<Hash>] a two-element tuple `[command_opts, context_opts]`
       #
       # @api private
@@ -494,6 +536,17 @@ module Git
       #
       # @param opts [Hash] clone options (mutated in place)
       #
+      # @option opts [Logger, nil] :log logger used for clone operations
+      #
+      # @option opts [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option opts [String, :use_global_config] :binary_path path to the git
+      #   binary
+      #
+      # @option opts [String, nil] :index custom index path for the returned
+      #   repository
+      #
       # @return [Hash{Symbol => Object}] context options for clone setup
       #
       # @api private
@@ -511,6 +564,8 @@ module Git
       #
       # @param opts [Hash] clone options (mutated in place)
       #
+      # @option opts [String, nil] :repository alternate git directory path
+      #
       # @return [void] mutates `opts` in place
       #
       # @api private
@@ -545,7 +600,23 @@ module Git
       #
       # @param options [Hash] the normalized options hash (after alias resolution)
       #
-      # @return [Git::CommandLineResult] the result of running `git init`
+      # @option options [Boolean, nil] :bare create a bare repository at
+      #   `directory`
+      #
+      # @option options [String, nil] :initial_branch the name for the initial
+      #   branch
+      #
+      # @option options [String, nil] :repository path for the `.git` directory
+      #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option options [Logger, nil] :log logger used for git operations
+      #
+      # @return [Git::CommandLine::Result] the result of running `git init`
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
@@ -565,6 +636,22 @@ module Git
       #
       # @param options [Hash] the normalized options hash
       #
+      # @option options [Boolean, nil] :bare create a bare repository at
+      #   `directory`
+      #
+      # @option options [String, nil] :repository path for the `.git` directory
+      #
+      # @option options [String, nil] :index custom index path for the returned
+      #   repository
+      #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option options [Logger, nil] :log logger used for git operations
+      #
       # @return [Git::Repository] the repository opened after initialization
       #
       # @api private
@@ -579,6 +666,14 @@ module Git
       #
       # @param options [Hash] the normalized options hash
       #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [Logger, nil] :log logger used for git operations
+      #
       # @return [Hash{Symbol => Object}] options accepted by {.open} and {.bare}
       #
       # @api private
@@ -596,6 +691,19 @@ module Git
       #
       # @param options [Hash] the normalized options hash
       #
+      # @option options [String, nil, :use_global_config] :git_ssh path to a
+      #   custom SSH executable
+      #
+      # @option options [String, :use_global_config] :binary_path path to the
+      #   git binary
+      #
+      # @option options [Logger, nil] :log logger used for git operations
+      #
+      # @option options [String, nil] :index custom index path for the returned
+      #   repository
+      #
+      # @option options [String, nil] :repository path for the `.git` directory
+      #
       # @return [Hash{Symbol => Object}] options accepted by {.open}
       #
       # @api private
@@ -628,6 +736,12 @@ module Git
       #
       # @param opts [Hash] clone options (mutated in place)
       #
+      # @option opts [String, Pathname, nil] :path deprecated; use `:chdir`
+      #   instead
+      #
+      # @option opts [String, Pathname, nil] :chdir run `git clone` from within
+      #   this directory
+      #
       # @return [void] mutates `opts` in place
       #
       # @api private
@@ -636,7 +750,7 @@ module Git
         return unless opts.key?(:path)
 
         if defined?(Git::Deprecation)
-          Git::Deprecation.warn('The :path option for Git::Repository.clone is deprecated, use :chdir instead')
+          Git::Deprecation.warn('The :path option for Git.clone is deprecated, use :chdir instead')
         end
         path = opts.delete(:path)
         opts[:chdir] ||= path
@@ -646,6 +760,12 @@ module Git
       #
       # @param opts [Hash] clone options (mutated in place)
       #
+      # @option opts [Boolean, nil] :recursive deprecated; use
+      #   `:recurse_submodules` instead
+      #
+      # @option opts [Boolean, String, Array<String>, nil] :recurse_submodules
+      #   initialize submodules after cloning
+      #
       # @return [void] mutates `opts` in place
       #
       # @api private
@@ -655,7 +775,7 @@ module Git
 
         if defined?(Git::Deprecation)
           Git::Deprecation.warn(
-            'The :recursive option for Git::Repository.clone is deprecated, use :recurse_submodules instead'
+            'The :recursive option for Git.clone is deprecated, use :recurse_submodules instead'
           )
         end
         opts[:recurse_submodules] = opts.delete(:recursive)
@@ -665,6 +785,11 @@ module Git
       #
       # @param opts [Hash] clone options (mutated in place)
       #
+      # @option opts [String, nil] :remote deprecated; use `:origin` instead
+      #
+      # @option opts [String, nil] :origin remote name to use instead of
+      #   `origin`
+      #
       # @return [void] mutates `opts` in place
       #
       # @api private
@@ -673,7 +798,7 @@ module Git
         return unless opts.key?(:remote)
 
         if defined?(Git::Deprecation)
-          Git::Deprecation.warn('The :remote option for Git::Repository.clone is deprecated, use :origin instead')
+          Git::Deprecation.warn('The :remote option for Git.clone is deprecated, use :origin instead')
         end
         opts[:origin] = opts.delete(:remote)
       end

data/lib/git/repository/inspecting.rb

@@ -14,7 +14,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Inspecting
       # Give a human-readable name to a commit based on the most recent reachable tag