git 5.0.0.beta.1 → 5.0.0.beta.2

data/lib/git/repository/remote_operations.rb

@@ -2,9 +2,11 @@
 
 require 'git/commands/config_option_syntax'
 require 'git/commands/fetch'
+require 'git/commands/ls_remote'
 require 'git/commands/pull'
 require 'git/commands/push'
 require 'git/commands/remote'
+require 'git/parsers/ls_remote'
 require 'git/remote'
 
 require 'git/repository/shared_private'
@@ -17,7 +19,7 @@ module Git
     #
     # @api public
     #
-    module RemoteOperations
+    module RemoteOperations # rubocop:disable Metrics/ModuleLength
       # Key normalizations for {#fetch} options
       #
       # Maps dash-style option keys (which the 4.x `Git::Lib#fetch` accepted)
@@ -370,11 +372,11 @@ module Git
         Private.push_tags(@execution_context, remote, opts).stdout
       end
 
-      # Option keys accepted by {#add_remote}
+      # Option keys accepted by {#remote_add}
       #
       # Derived from the 4.x `REMOTE_ADD_OPTION_MAP` in `Git::Lib`.
-      ADD_REMOTE_ALLOWED_OPTS = %i[fetch track].freeze
-      private_constant :ADD_REMOTE_ALLOWED_OPTS
+      REMOTE_ADD_ALLOWED_OPTS = %i[fetch track].freeze
+      private_constant :REMOTE_ADD_ALLOWED_OPTS
 
       # Register a new remote in the local repository
       #
@@ -382,19 +384,19 @@ module Git
       # configures which branches are tracked.
       #
       # @example Add a remote
-      #   repo.add_remote('upstream', 'https://github.com/user/repo.git')
+      #   repo.remote_add('upstream', 'https://github.com/user/repo.git')
       #
       # @example Add a remote and fetch immediately
-      #   repo.add_remote('upstream', 'https://github.com/user/repo.git', fetch: true)
+      #   repo.remote_add('upstream', 'https://github.com/user/repo.git', fetch: true)
       #
       # @example Add a remote tracking a specific branch
-      #   repo.add_remote('upstream', 'https://github.com/user/repo.git', track: 'main')
+      #   repo.remote_add('upstream', 'https://github.com/user/repo.git', track: 'main')
       #
       # @param name [String] the name for the new remote
       #
-      # @param url [String, Git::Base] the URL of the remote repository
+      # @param url [String, Git::Repository] the URL of the remote repository
       #
-      #   A {Git::Base} instance is accepted for local references and converted
+      #   A {Git::Repository} instance is accepted for local references and converted
       #   to `url.repo.to_s`.
       #
       # @param opts [Hash] options for adding the remote
@@ -414,22 +416,56 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
-      def add_remote(name, url, opts = {})
-        url = url.repo.to_s if url.is_a?(Git::Base)
+      def remote_add(name, url, opts = {})
+        url = url.repo.to_s if url.is_a?(Git::Repository)
         opts = Private.normalize_add_remote_keys(opts)
-        SharedPrivate.assert_valid_opts!(ADD_REMOTE_ALLOWED_OPTS, **opts)
+        SharedPrivate.assert_valid_opts!(REMOTE_ADD_ALLOWED_OPTS, **opts)
         Git::Commands::Remote::Add.new(@execution_context).call(name, url, **opts)
 
         Git::Remote.new(self, name)
       end
 
+      # @deprecated Use {#remote_add} instead.
+      #
+      # @param name [String] the name for the new remote
+      #
+      # @param url [String, Git::Repository] the URL of the remote repository
+      #
+      #   A {Git::Repository} instance is accepted for local references and converted
+      #   to `url.repo.to_s`.
+      #
+      # @param opts [Hash] options for adding the remote
+      #
+      # @option opts [Boolean, nil] :fetch (nil) fetch from the remote immediately
+      #   after adding it (`-f`)
+      #
+      #   The deprecated alias `:with_fetch` is accepted and normalized
+      #   automatically.
+      #
+      # @option opts [String, nil] :track (nil) track only the given branch during
+      #   fetch (`-t`)
+      #
+      # @return [Git::Remote] the newly added remote
+      #
+      # @raise [ArgumentError] when unsupported option keys are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero status
+      #
+      def add_remote(name, url, opts = {})
+        Git::Deprecation.warn(
+          'Git::Repository#add_remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_add instead.'
+        )
+        remote_add(name, url, opts)
+      end
+
       # Removes a remote from this repository
       #
       # Deletes the remote named `name` along with its associated configuration,
       # tracking references, and remote-tracking branches.
       #
       # @example Remove a remote named 'upstream'
-      #   repo.remove_remote('upstream')
+      #   repo.remote_remove('upstream')
       #
       # @param name [String] the name of the remote to remove
       #
@@ -437,39 +473,76 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
-      def remove_remote(name)
+      def remote_remove(name)
         Git::Commands::Remote::Remove.new(@execution_context).call(name)
       end
 
+      # @deprecated Use {#remote_remove} instead.
+      #
+      # @param name [String] the name of the remote to remove
+      #
+      # @return [Git::CommandLineResult] the result of calling `git remote remove`
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero status
+      #
+      def remove_remote(name)
+        Git::Deprecation.warn(
+          'Git::Repository#remove_remote is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_remove instead.'
+        )
+        remote_remove(name)
+      end
+
       # Sets the URL for an existing remote
       #
       # Replaces the fetch URL configured for the remote named `name`.
       #
       # @example Set the URL for a remote
-      #   repo.set_remote_url('origin', 'https://github.com/user/repo.git')
+      #   repo.remote_set_url('origin', 'https://github.com/user/repo.git')
       #
       # @example Set the URL from a local repository reference
       #   source = Git.open('/path/to/source')
-      #   repo.set_remote_url('origin', source)
+      #   repo.remote_set_url('origin', source)
       #
       # @param name [String] the name of the remote to update
       #
-      # @param url [String, Git::Base] the new URL for the remote
+      # @param url [String, Git::Repository] the new URL for the remote
       #
-      #   A {Git::Base} instance is accepted for local references and converted
+      #   A {Git::Repository} instance is accepted for local references and converted
       #   to `url.repo.to_s`.
       #
       # @return [Git::Remote] the updated remote
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
-      def set_remote_url(name, url)
-        url = url.repo.to_s if url.is_a?(Git::Base)
+      def remote_set_url(name, url)
+        url = url.repo.to_s if url.is_a?(Git::Repository)
         Git::Commands::Remote::SetUrl.new(@execution_context).call(name, url)
 
         Git::Remote.new(self, name)
       end
 
+      # @deprecated Use {#remote_set_url} instead.
+      #
+      # @param name [String] the name of the remote to update
+      #
+      # @param url [String, Git::Repository] the new URL for the remote
+      #
+      #   A {Git::Repository} instance is accepted for local references and converted
+      #   to `url.repo.to_s`.
+      #
+      # @return [Git::Remote] the updated remote
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero status
+      #
+      def set_remote_url(name, url)
+        Git::Deprecation.warn(
+          'Git::Repository#set_remote_url is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#remote_set_url instead.'
+        )
+        remote_set_url(name, url)
+      end
+
       # Configures which branches are fetched for a remote
       #
       # Uses `git remote set-branches` to set or append fetch refspecs. When the
@@ -570,6 +643,78 @@ module Git
         result.stdout.split("\n").map { |name| Git::Remote.new(self, name) }
       end
 
+      # Option keys accepted by {#ls_remote}
+      #
+      # @return [Array<Symbol>]
+      #
+      # @api private
+      #
+      LS_REMOTE_ALLOWED_OPTS = %i[
+        branches b heads h tags t refs upload_pack quiet q exit_code sort server_option o timeout
+      ].freeze
+      private_constant :LS_REMOTE_ALLOWED_OPTS
+
+      # List references available in a remote repository
+      #
+      # Queries a remote for its available refs and returns a structured Hash
+      # mapping ref types to name/sha pairs. The remote is contacted but no local
+      # objects are created or updated.
+      #
+      # @example List all refs from the local repository
+      #   repo.ls_remote
+      #   # => {"head"=>{ref: "HEAD", sha: "abc123"},
+      #   #     "branches"=>{"main"=>{ref: "refs", sha: "abc123"}}}
+      #
+      # @note The `:ref` value in each pair is only the **first path segment** of the
+      #   full git ref (e.g. `"refs"` for `refs/heads/main`), not the complete ref
+      #   path. This matches the behavior of 4.x. See
+      #   [issue 1416](https://github.com/ruby-git/ruby-git/issues/1416) for the
+      #   planned fix.
+      #
+      # @example List all refs from a named remote
+      #   repo.ls_remote('origin')
+      #   # => {"head"=>..., "branches"=>..., "tags"=>...}
+      #
+      # @example List only tags from a named remote
+      #   repo.ls_remote('origin', tags: true)
+      #   # => {"tags"=>{"v1.0"=>{ref: "refs", sha: "def456"}}}
+      #
+      # @param location [String, nil] the remote name or URL to query; defaults to
+      #   `'.'` (the local repository) when nil
+      #
+      # @param opts [Hash] options for the ls-remote command
+      #
+      # @option opts [Boolean, nil] :branches (nil) limit output to refs under
+      #   `refs/heads/`; alias: `:b`
+      #
+      # @option opts [Boolean, nil] :heads (nil) limit output to refs under
+      #   `refs/heads/`; kept for backward compatibility; alias: `:h`
+      #
+      # @option opts [Boolean, nil] :tags (nil) limit output to refs under
+      #   `refs/tags/`; alias: `:t`
+      #
+      # @option opts [Boolean, nil] :refs (nil) exclude peeled tags and pseudorefs
+      #   like `HEAD` from the output
+      #
+      # @option opts [Numeric] :timeout (nil) execution timeout in seconds
+      #
+      # @return [Hash{String => Hash}] a Hash keyed by ref type (e.g. `"head"`,
+      #   `"branches"`, `"tags"`; other git namespace segments may appear for
+      #   non-standard refs); for named refs the value is a Hash keyed by ref name
+      #   mapping to `{ ref: String, sha: String }`; for the `"head"` entry the value
+      #   is `{ ref: String, sha: String }` directly
+      #
+      # @raise [ArgumentError] if unsupported options are provided
+      #
+      # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
+      #
+      def ls_remote(location = nil, opts = {})
+        SharedPrivate.assert_valid_opts!(LS_REMOTE_ALLOWED_OPTS, **opts)
+        repository = location || '.'
+        output_lines = Git::Commands::LsRemote.new(@execution_context).call(repository, **opts).stdout.split("\n")
+        Git::Parsers::LsRemote.parse_output(output_lines)
+      end
+
       # Helpers private to the `RemoteOperations` topic module
       #
       # @api private
@@ -707,7 +852,7 @@ module Git
           Git::Commands::Push.new(execution_context).call(*[remote].compact, **opts)
         end
 
-        # Normalize deprecated {#add_remote} option keys to their canonical equivalents
+        # Normalize deprecated option keys for {#remote_add} to their canonical equivalents
         #
         # Renames the deprecated `:with_fetch` key to `:fetch`, removing it from
         # the copy. When both keys are present, `:with_fetch` takes precedence.

data/lib/git/repository/staging.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 require 'git/commands/add'
+require 'git/commands/am/apply'
+require 'git/commands/apply'
 require 'git/commands/clean'
 require 'git/commands/ls_files'
+require 'git/commands/mv'
+require 'git/commands/read_tree'
 require 'git/commands/reset'
 require 'git/commands/rm'
 require 'git/escaped_path'
@@ -10,8 +14,8 @@ require 'git/repository/shared_private'
 
 module Git
   class Repository
-    # Facade methods for staging-area operations: adding, resetting, removing, and
-    # cleaning files
+    # Facade methods for staging-area operations: adding, resetting, moving,
+    # removing, and cleaning files
     #
     # Included by {Git::Repository}.
     #
@@ -63,31 +67,140 @@ module Git
 
       # Reset the current HEAD to a specified state
       #
-      # @overload reset(commitish = nil, **options)
+      # @example Reset the index and working tree to HEAD
+      #   repo.reset
       #
-      #   @example Reset the index and working tree to HEAD
-      #     repo.reset
+      # @example Hard reset to a specific commit
+      #   repo.reset('HEAD~1', hard: true)
+      #
+      # @param commitish [String, nil] the commit or tree-ish to reset to;
+      #   defaults to HEAD when `nil`
+      #
+      # @param opts [Hash] options for the reset command
+      #
+      # @option opts [Boolean, nil] :hard (nil) reset the index and working
+      #   tree; discards all tracked changes
+      #
+      # @return [String] git's stdout from the reset
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def reset(commitish = nil, opts = {})
+        SharedPrivate.assert_valid_opts!(RESET_ALLOWED_OPTS, **opts)
+        Git::Commands::Reset.new(@execution_context).call(commitish, **opts).stdout
+      end
+
+      # Reset the current HEAD to a specified state with `--hard`
+      #
+      # @deprecated Use {#reset} with `hard: true` instead.
+      #
+      #   @example Hard reset to HEAD
+      #     repo.reset_hard
       #
       #   @example Hard reset to a specific commit
-      #     repo.reset('HEAD~1', hard: true)
+      #     repo.reset_hard('HEAD~1')
       #
-      #   @param commitish [String, nil] the commit or tree-ish to reset to;
-      #     defaults to HEAD when `nil`
+      # @param commitish [String, nil] the commit or tree-ish to reset to;
+      #   defaults to HEAD when `nil`
       #
-      #   @param options [Hash] options for the reset command
+      # @param opts [Hash] options passed through to {#reset}
       #
-      #   @option options [Boolean, nil] :hard (nil) reset the index and working
-      #     tree; discards all tracked changes
+      # @return [String] git's stdout from the reset
       #
-      #   @return [String] git's stdout from the reset
+      # @raise [ArgumentError] when unsupported options are provided
       #
-      #   @raise [ArgumentError] when unsupported options are provided
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
-      #   @raise [Git::FailedError] when git exits with a non-zero exit status
+      def reset_hard(commitish = nil, opts = {})
+        Git::Deprecation.warn(
+          'Git::Repository::Staging#reset_hard is deprecated and will be removed in a future version. ' \
+          'Use #reset(commitish, hard: true) instead.'
+        )
+        reset(commitish, **opts, hard: true)
+      end
+
+      # Apply a patch file to the working tree
       #
-      def reset(commitish = nil, **)
-        SharedPrivate.assert_valid_opts!(RESET_ALLOWED_OPTS, **)
-        Git::Commands::Reset.new(@execution_context).call(commitish, **).stdout
+      # Reads the unified diff in `file` and applies it to the working tree via
+      # `git apply`. If `file` does not exist, the method returns `nil` without
+      # calling git — preserving the 4.x `Git::Base#apply` no-op contract.
+      #
+      # @example Apply a patch to the working tree
+      #   repo.apply('fix.patch')
+      #
+      # @param file [String] path to the patch file to apply
+      #
+      # @return [String] git's stdout (usually empty on success)
+      #
+      # @return [nil] when `file` does not exist
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def apply(file)
+        return unless File.exist?(file)
+
+        Git::Commands::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).stdout
+      end
+
+      # Apply a series of patches from a mailbox file to the current branch
+      #
+      # Reads the mbox-format file in `file` and applies the patches via
+      # `git am`. If `file` does not exist, the method returns `nil` without
+      # calling git — preserving the 4.x `Git::Base#apply_mail` no-op contract.
+      #
+      # @example Apply patches from a mailbox
+      #   repo.apply_mail('patches.mbox')
+      #
+      # @param file [String] path to the mbox patch file to apply
+      #
+      # @return [String] git's stdout (usually empty on success)
+      #
+      # @return [nil] when `file` does not exist
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def apply_mail(file)
+        return unless File.exist?(file)
+
+        Git::Commands::Am::Apply.new(@execution_context).call(file, chdir: @execution_context.git_work_dir).stdout
+      end
+
+      # Option keys accepted by {#read_tree}
+      READ_TREE_ALLOWED_OPTS = %i[prefix].freeze
+      private_constant :READ_TREE_ALLOWED_OPTS
+
+      # Read tree information into the index
+      #
+      # Reads the named tree object into the index. This is a low-level plumbing
+      # operation used to stage the contents of a tree without updating the
+      # working tree. Typically called before {#checkout_index} or as part of
+      # custom merge flows.
+      #
+      # @example Read HEAD into the index
+      #   repo.read_tree('HEAD')
+      #
+      # @example Read a tree under a prefix directory
+      #   repo.read_tree('HEAD', { prefix: 'subdir/' })
+      #
+      # @param treeish [String] the tree-ish to read into the index
+      #
+      # @param opts [Hash] options for the read-tree command
+      #
+      # @option opts [String] :prefix (nil) keep the current index contents and
+      #   read the named tree-ish under the directory at the given prefix
+      #   (`--prefix=<prefix>`)
+      #
+      # @return [String] git's stdout (usually empty on success)
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def read_tree(treeish, opts = {})
+        SharedPrivate.assert_valid_opts!(READ_TREE_ALLOWED_OPTS, **opts)
+        Git::Commands::ReadTree.new(@execution_context).call(treeish, **opts).stdout
       end
 
       # Option keys accepted by {#rm}
@@ -100,13 +213,13 @@ module Git
       # Remove file(s) from the working tree and the index
       #
       # @example Remove a single file
-      #   repo.rm('obsolete.txt', force: true)
+      #   repo.rm('obsolete.txt', { force: true })
       #
       # @example Remove a directory recursively
-      #   repo.rm('build', r: true)
+      #   repo.rm('build', { r: true })
       #
       # @example Remove from the index only, keeping the working tree copy
-      #   repo.rm('keep_me.txt', cached: true)
+      #   repo.rm('keep_me.txt', { cached: true })
       #
       # @param path [String, Array<String>] a file or files to remove (relative to
       #   the worktree root); defaults to `'.'` (all files)
@@ -157,6 +270,57 @@ module Git
         Git::Commands::Rm.new(@execution_context).call(*Array(path), **opts).stdout
       end
 
+      alias remove rm
+
+      # Option keys accepted by {#mv}
+      MV_ALLOWED_OPTS = %i[force f dry_run n k].freeze
+      private_constant :MV_ALLOWED_OPTS
+
+      # Move or rename a file, directory, or symlink in the working tree
+      #
+      # Updates the index after successful completion, but the change must still
+      # be committed.
+      #
+      # @example Move a single file
+      #   repo.mv('old.rb', 'new.rb')
+      #
+      # @example Move multiple files to a directory
+      #   repo.mv(['file1.rb', 'file2.rb'], 'destination_dir/')
+      #
+      # @example Force overwrite if destination exists
+      #   repo.mv('source.rb', 'dest.rb', force: true)
+      #
+      # @param source [String, Array<String>] one or more source file(s),
+      #   directory(ies), or symlink(s) to move (relative to the worktree root)
+      #
+      # @param destination [String] the destination file or directory
+      #
+      # @param options [Hash] options for the mv command
+      #
+      # @option options [Boolean, nil] :force (nil) force renaming or moving even
+      #   if the destination exists (alias: `:f`)
+      #
+      # @option options [Boolean, nil] :f (nil) alias for `:force`
+      #
+      # @option options [Boolean, nil] :dry_run (nil) do not actually move any
+      #   files; only show what would happen (alias: `:n`)
+      #
+      # @option options [Boolean, nil] :n (nil) alias for `:dry_run`
+      #
+      # @option options [Boolean, nil] :k (nil) skip move or rename actions which
+      #   would lead to an error
+      #
+      # @return [String] git's stdout from the mv command
+      #
+      # @raise [ArgumentError] when unsupported options are provided
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      def mv(source, destination, options = {})
+        SharedPrivate.assert_valid_opts!(MV_ALLOWED_OPTS, **options)
+        Git::Commands::Mv.new(@execution_context).call(*Array(source), destination, verbose: true, **options).stdout
+      end
+
       # Option keys accepted by {#clean}
       #
       # The deprecated `:ff` and `:force_force` keys are handled by
@@ -168,13 +332,13 @@ module Git
       # Remove untracked files from the working tree
       #
       # @example Remove untracked files
-      #   repo.clean(force: true)
+      #   repo.clean({ force: true })
       #
       # @example Remove untracked files and directories
-      #   repo.clean(force: true, d: true)
+      #   repo.clean({ force: true, d: true })
       #
       # @example Remove untracked and ignored files
-      #   repo.clean(force: true, x: true)
+      #   repo.clean({ force: true, x: true })
       #
       # @param opts [Hash] options for the clean command
       #

data/lib/git/repository/stashing.rb

@@ -19,6 +19,13 @@ module Git
       # message is the stash description with the leading branch prefix (e.g.
       # `"On main:"` or `"WIP on main:"`) stripped.
       #
+      # @note The sequential index returned here is **not** the same as git's
+      #   `stash@{N}` reference used by {#stash_apply}. In git, `stash@{0}` is the
+      #   **most recent** stash, while index `0` here is the **oldest**. To apply a
+      #   specific stash from this list, convert the entry's position to a git
+      #   reference: `'stash@{%d}' % (total - 1 - index)`, or pass the string
+      #   reference directly to {#stash_apply}.
+      #
       # @example List all stashes (oldest first)
       #   repo.stashes_all #=> [[0, "Fix bug"], [1, "Add feature"]]
       #
@@ -34,12 +41,38 @@ module Git
         result = Git::Commands::Stash::List.new(@execution_context).call
         stashes = Git::Parsers::Stash.parse_list(result.stdout)
         stashes.reverse.each_with_index.map do |info, i|
-          match_data = info.message.match(/^[^:]+:(.*)$/)
-          message = match_data ? match_data[1].strip : info.message
+          message = info.message.sub(/^(?:WIP on|On)\s+[^:]+:\s*/, '')
           [i, message]
         end
       end
 
+      # Returns stash entries as a formatted string matching `git stash list` output
+      #
+      # @deprecated Use {#stashes_all} instead.
+      #
+      # @example List stashes as a formatted string
+      #   repo.stash_list #=> "stash@{0}: On main: WIP\nstash@{1}: On feature: Fix bug"
+      #
+      # @return [String] newline-joined `"stash@{n}: <full message>"` entries, or an
+      #   empty string when there are no stashes; the format matches `git stash list`
+      #   output
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @see #stashes_all
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      def stash_list
+        Git::Deprecation.warn(
+          'Git::Repository#stash_list is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#stashes_all instead.'
+        )
+        result = Git::Commands::Stash::List.new(@execution_context).call
+        stashes = Git::Parsers::Stash.parse_list(result.stdout)
+        stashes.map { |info| "#{info.name}: #{info.message}" }.join("\n")
+      end
+
       # Save the current working directory and index state to a new stash
       #
       # @param message [String] the stash message
@@ -72,7 +105,10 @@ module Git
       #   repo.stash_apply('stash@{1}') #=> "HEAD is now at abc1234 Initial commit"
       #
       # @param id [String, Integer, nil] the stash identifier (e.g., `'stash@{0}'`,
-      #   `0`) or `nil` to apply the most recent stash entry
+      #   `0`) or `nil` to apply the most recent stash entry. When an Integer is
+      #   given it is passed directly to git as `stash@{N}`, where `0` is the
+      #   **most recent** stash — the opposite order from {#stashes_all}'s
+      #   sequential indices, where `0` is the **oldest** stash.
       #
       # @return [String] the output from the git stash apply command
       #

data/lib/git/repository/status_operations.rb

@@ -43,6 +43,27 @@ module Git
         true
       end
 
+      # Returns `true` if the repository has no commits yet
+      #
+      # @example Check whether a repository is empty
+      #   repo.empty? #=> true   # freshly initialized, no commits yet
+      #   repo.empty? #=> false  # at least one commit exists
+      #
+      # @return [Boolean] `true` when the repository has no commits, `false` otherwise
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status other
+      #   than when the repository has no commits
+      #
+      # @deprecated Use {#no_commits?} instead
+      #
+      def empty?
+        Git::Deprecation.warn(
+          'Git::Repository#empty? is deprecated and will be removed in a future version. ' \
+          'Use Git::Repository#no_commits? instead.'
+        )
+        no_commits?
+      end
+
       # List all files in the working tree that are not tracked by git
       #
       # Runs `git ls-files --others --exclude-standard` from the working tree