git 5.7.0 → 6.0.0

data/lib/git/log.rb

@@ -9,10 +9,10 @@ module Git
   # return every matching commit. Calling {#all} adds the `--all` flag to include
   # all refs in the search but does not change the number of commits returned.
   #
-  # The query is lazily executed when results are requested either via the modern
-  # `#execute` method or the deprecated Enumerable methods.
+  # The query runs when {#execute} is called and returns a {Git::Log::Result}
+  # holding the matching commits.
   #
-  # @example Using the modern `execute` API
+  # @example Running a query
   #   log = git.log.max_count(50).between('v1.0', 'v1.1').author('Scott')
   #   results = log.execute
   #   puts "Found #{results.size} commits."
@@ -21,8 +21,6 @@ module Git
   # @api public
   #
   class Log
-    include Enumerable
-
     # An immutable, Enumerable collection of `Git::Object::Commit` objects.
     # Returned by `Git::Log#execute`.
     #
@@ -236,76 +234,6 @@ module Git
       Result.new(@commits)
     end
 
-    # @!group Deprecated Enumerable Interface
-
-    # @deprecated Use {#execute} and call `each` on the result.
-    def each(&)
-      Git::Deprecation.warn(
-        'Calling Git::Log#each is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #each on the result object.'
-      )
-      run_log_if_dirty
-      @commits.each(&)
-    end
-
-    # @deprecated Use {#execute} and call `size` on the result.
-    def size
-      Git::Deprecation.warn(
-        'Calling Git::Log#size is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #size on the result object.'
-      )
-      run_log_if_dirty
-      @commits.size
-    end
-
-    # @deprecated Use {#execute} and call `to_s` on the result.
-    def to_s
-      Git::Deprecation.warn(
-        'Calling Git::Log#to_s is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #to_s on the result object.'
-      )
-      run_log_if_dirty
-      @commits.join("\n")
-    end
-
-    # @deprecated Use {#execute} and call the method on the result.
-    def first
-      Git::Deprecation.warn(
-        'Calling Git::Log#first is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #first on the result object.'
-      )
-      run_log_if_dirty
-      @commits.first
-    end
-
-    # @deprecated Use {#execute} and call the method on the result.
-    def last
-      Git::Deprecation.warn(
-        'Calling Git::Log#last is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #last on the result object.'
-      )
-      run_log_if_dirty
-      @commits.last
-    end
-
-    # @param index [Integer, Range] the commit index or range to retrieve
-    #
-    # @return [Git::Object::Commit, Array<Git::Object::Commit>, nil] the selected
-    #   commit or commits
-    #
-    # @deprecated Use {#execute} and call the method on the result.
-    #
-    def [](index)
-      Git::Deprecation.warn(
-        'Calling Git::Log#[] is deprecated and will be removed in v6.0.0. ' \
-        'Call #execute and then #[] on the result object.'
-      )
-      run_log_if_dirty
-      @commits[index]
-    end
-
-    # @!endgroup
-
     private
 
     # Sets a log query option and marks cached results dirty

data/lib/git/object.rb

@@ -223,6 +223,9 @@ module Git
       #
       # @raise [Git::FailedError] if `git archive` fails
       #
+      # @note A failure leaves nothing behind and does not replace an existing
+      #   `file`; see {Git::Repository::ObjectOperations#archive}.
+      #
       # @api public
       #
       def archive(file = nil, opts = {})
@@ -481,22 +484,6 @@ module Git
         diff(parent)
       end
 
-      # Sets parsed commit data on this commit object
-      #
-      # @param data [Hash] parsed commit data
-      #
-      # @return [void]
-      #
-      # @deprecated use {#from_data} instead
-      #
-      def set_commit(data) # rubocop:disable Naming/AccessorMethodName
-        Git::Deprecation.warn(
-          'Git::Object::Commit#set_commit is deprecated and will be removed in v6.0.0. ' \
-          'Use #from_data instead.'
-        )
-        from_data(data)
-      end
-
       # Loads parsed commit data into this commit object
       #
       # @param data [Hash] parsed commit data from `git cat-file commit`
@@ -531,146 +518,6 @@ module Git
       end
     end
 
-    # A Git tag object
-    #
-    # This class represents a tag in Git, which can be either annotated or lightweight.
-    #
-    # Annotated tags contain additional metadata such as the tagger's name, email, and
-    # the date when the tag was created, along with a message.
-    #
-    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} and
-    #   {Git::TagInfo} instead
-    #
-    #   {Git::TagInfo} is an immutable value object carrying the tag's `name`,
-    #   `oid`, `target_oid`, `annotated?`, `message`, and `tagger`. Call the
-    #   corresponding {Git::Repository} method (e.g. `archive`, `log`, `diff`,
-    #   `cat_file_contents`) with `info.oid || info.target_oid` for operations
-    #   on a tag; that is the object this class resolves and pins at
-    #   construction, so a later move of the tag does not redirect an existing
-    #   object, whereas the tag name would. Constructing a `Git::Object::Tag`
-    #   emits a deprecation warning.
-    #
-    class Tag < AbstractObject
-      # @return [String] the tag name
-      #
-      attr_accessor :name
-
-      # @overload initialize(base, name)
-      #
-      #   @param base [Git::Repository] the git repository
-      #
-      #   @param name [String] the name of the tag
-      #
-      # @overload initialize(base, sha, name)
-      #
-      #   `sha` is kept as the object that the inherited operations (`size`,
-      #   `contents`, `grep`, `diff`, `log`, `archive`) run against; `annotated?`,
-      #   `message`, and `tagger` read the ref `name`. {Git::TagInfo} describes a
-      #   ref, so there is no OID-based replacement for this form: pass `sha` to
-      #   the {Git::Repository} operation directly, or read the tag object with
-      #   {Git::Repository::ObjectOperations#cat_file_tag}.
-      #
-      #   @param base [Git::Repository] the git repository
-      #
-      #   @param sha [String] the SHA of the tag object
-      #
-      #   @param name [String] the name of the tag
-      #
-      def initialize(base, sha, name = nil)
-        Git::Deprecation.warn(
-          'Git::Object::Tag is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#tag_list and Git::TagInfo instead.'
-        )
-        sha, name = resolve_sha_and_name(base, sha, name)
-        super(base, sha)
-
-        @name = name
-        @annotated = nil
-        @loaded = false
-      end
-
-      # Returns whether this tag is annotated
-      #
-      # @return [Boolean] `true` when the tag has an annotated tag object
-      #
-      def annotated?
-        @annotated = @annotated.nil? ? (object_repository.cat_file_type(name) == 'tag') : @annotated
-      end
-
-      # Returns the tag message
-      #
-      # @return [String, nil] the annotated tag message, or `nil` for a
-      #   lightweight tag
-      #
-      def message
-        check_tag
-        @message
-      end
-
-      # Returns whether this object is a tag
-      #
-      # @return [Boolean] `true`
-      #
-      def tag?
-        true
-      end
-
-      # Returns the tagger identity
-      #
-      # @return [Git::AuthorInfo, nil] the tagger for an annotated tag, or `nil`
-      #   for a lightweight tag
-      #
-      def tagger
-        check_tag
-        @tagger
-      end
-
-      private
-
-      # Resolves the two-argument constructor form to a SHA and a tag name
-      #
-      # In the two-argument form `sha` carries the tag name and the SHA is
-      # looked up from the repository.
-      #
-      # @param base [Git::Repository] the git repository
-      #
-      # @param sha [String] the SHA of the tag object, or the tag name in the
-      #   two-argument form
-      #
-      # @param name [String, nil] the tag name, or `nil` in the two-argument form
-      #
-      # @return [Array(String, String)] the resolved `[sha, name]` pair
-      #
-      # @raise [Git::UnexpectedResultError] if the tag does not exist
-      #
-      def resolve_sha_and_name(base, sha, name)
-        return [sha, name] unless name.nil?
-
-        resolved = base.tag_sha(sha)
-        raise Git::UnexpectedResultError, "Tag '#{sha}' does not exist." if resolved == ''
-
-        [resolved, sha]
-      end
-
-      # Loads annotated tag data when available
-      #
-      # @return [void]
-      #
-      def check_tag
-        return if @loaded
-
-        if annotated?
-          tdata = object_repository.cat_file_tag(@name)
-          @message = tdata['message'].chomp
-          @tagger = Git::AuthorInfo.parse(tdata['tagger'])
-        else
-          @message = @tagger = nil
-        end
-
-        @loaded = true
-      end
-    end
-
     # if we're calling this, we don't know what type it is yet
     # so this is our little factory method
     #
@@ -680,15 +527,10 @@ module Git
     #
     # @param type [String, nil] object type hint: `blob`, `commit`, or `tree`
     #
-    # @param is_tag [Boolean] whether to construct a tag object
-    #
     # @return [Git::Object::AbstractObject] the concrete object wrapper
     #
-    def self.new(base, objectish, type = nil, is_tag = false) # rubocop:disable Style/OptionalBooleanParameter
-      return new_tag(base, objectish) if is_tag
-
+    def self.new(base, objectish, type = nil)
       type ||= object_repository_for(base).cat_file_type(objectish)
-      # TODO: why not handle tag case here too?
       klass =
         case type
         when /blob/   then Blob
@@ -698,29 +540,6 @@ module Git
       klass.new(base, objectish)
     end
 
-    # Creates a tag object through the deprecated factory path
-    #
-    # @param base [Git::Repository] the repository used to query object data
-    #
-    # @param objectish [String] the tag name or SHA
-    #
-    # @return [Git::Object::Tag] the tag object wrapper
-    #
-    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} instead
-    #
-    #   The warning names `Git::Object::Tag.new`, the replacement this path
-    #   shipped with, and the {Git::Object::Tag} constructor is deprecated as
-    #   well; this method silences it so one call emits one warning. Go
-    #   straight to `Git::Repository#tag_list(name).first`.
-    #
-    private_class_method def self.new_tag(base, objectish)
-      Git::Deprecation.warn(
-        'Git::Object.new with is_tag argument is deprecated and will be removed in v6.0.0. ' \
-        'Use Git::Object::Tag.new instead.'
-      )
-      Git::Deprecation.silence { Git::Object::Tag.new(base, objectish) }
-    end
-
     # Returns the repository used for object lookup
     #
     # @param base [Git::Repository] the repository to return

data/lib/git/path_resolver.rb

@@ -4,20 +4,37 @@ require 'git/commands/rev_parse'
 require 'git/errors'
 require 'git/execution_context'
 require 'git/execution_context/global'
+require 'git/system_call_guard'
 
 module Git
   # Resolves and normalizes the filesystem paths that locate a Git repository
   #
   # `PathResolver` is the single home for the path-resolution logic used by the
-  # `Git::Repository` factory class methods ({Git::Repository.open} and
-  # {Git::Repository.bare}). It computes the absolute working-directory,
-  # repository (`.git`), and index paths from the caller-supplied values,
-  # following the same rules Git itself uses (including gitdir-pointer files for
-  # submodules and linked worktrees).
+  # `Git` factory methods ({Git.open}, {Git.bare}, {Git.init}, and {Git.clone}).
+  # It computes the absolute working-directory, repository (`.git`), and index
+  # paths from the caller-supplied values, following the same rules Git itself
+  # uses (including gitdir-pointer files for submodules and linked worktrees).
+  #
+  # A relative path given by the caller is expanded against the process working
+  # directory, as git does for a path on its command line. Only the defaults are
+  # derived from the layout: an omitted repository is `<working_directory>/.git`
+  # and an omitted index is `<repository>/index`.
   #
   # @api private
   #
   module PathResolver
+    # The {Git::Error} message when a working directory path cannot be expanded
+    WORKING_DIRECTORY_MESSAGE = 'Failed to resolve the working directory'
+
+    # The {Git::Error} message when a repository directory path cannot be expanded
+    REPOSITORY_MESSAGE = 'Failed to resolve the repository directory'
+
+    # The {Git::Error} message when an index file path cannot be expanded
+    INDEX_MESSAGE = 'Failed to resolve the index file'
+
+    # The {Git::Error} message when the `:chdir` option of `Git.clone` cannot be expanded
+    CHDIR_MESSAGE = 'Failed to resolve the chdir directory'
+
     module_function
 
     # Resolve and normalize the paths that locate a Git repository
@@ -44,10 +61,12 @@ module Git
     # @return [Hash{Symbol => (String, nil)}] a hash with `:working_directory`,
     #   `:repository`, and `:index` keys
     #
+    # @raise [Git::Error] if the repository path is a gitdir pointer file that
+    #   cannot be read
+    #
     def resolve_paths(working_directory: nil, repository: nil, index: nil, bare: false)
       working_dir = resolve_working_directory(working_directory, bare: bare)
-      # For bare repos, use working_directory as the default repository location
-      repo_path = resolve_repository(repository, working_dir, bare: bare, bare_default: working_directory)
+      repo_path = resolve_repository(repository, working_dir)
       index_path = resolve_index(index, repo_path)
 
       {
@@ -81,17 +100,20 @@ module Git
     # @raise [ArgumentError] if `working_dir` does not exist, is not a
     #   directory, or is not inside a git working tree
     #
-    #   Also raised if the git binary cannot be found.
+    # @raise [Git::Error] if the git binary cannot be found or fails to launch, or
+    #   if `working_dir` cannot be expanded to an absolute path
     #
     def root_of_worktree(working_dir, binary_path: :use_global_config, git_ssh: :use_global_config)
-      raise ArgumentError, "'#{working_dir}' does not exist or is not a directory" unless Dir.exist?(working_dir)
+      expanded_dir = expand_path(working_dir, 'Failed to expand the working directory path')
+      raise ArgumentError, "'#{working_dir}' does not exist or is not a directory" unless Dir.exist?(expanded_dir)
 
-      execute_rev_parse_toplevel(working_dir, binary_path: binary_path, git_ssh: git_ssh)
+      execute_rev_parse_toplevel(expanded_dir, binary_path: binary_path, git_ssh: git_ssh)
     end
 
     # Run `git rev-parse --show-toplevel` from `working_dir` and return stdout
     #
-    # @param working_dir [String] a path inside the working tree
+    # @param working_dir [String] the absolute path of a directory inside the
+    #   working tree
     #
     # @param binary_path [String, :use_global_config] path to the git binary
     #
@@ -99,18 +121,16 @@ module Git
     #
     # @return [String] the top-level directory reported by git
     #
-    # @raise [ArgumentError] if the git binary is not found or `working_dir` is
-    #   not inside a git working tree
+    # @raise [ArgumentError] if `working_dir` is not inside a git working tree
+    #
+    # @raise [Git::Error] if the git binary cannot be found or fails to launch
     #
     # @api private
     #
     def execute_rev_parse_toplevel(working_dir, binary_path: :use_global_config, git_ssh: :use_global_config)
       execution_context = Git::ExecutionContext::Global.new(binary_path: binary_path, git_ssh: git_ssh)
-      Git::Commands::RevParse.new(execution_context).call(
-        show_toplevel: true, chdir: File.expand_path(working_dir)
-      ).stdout
-    rescue Errno::ENOENT
-      raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
+
+      Git::Commands::RevParse.new(execution_context).call(show_toplevel: true, chdir: working_dir).stdout
     rescue Git::FailedError
       raise ArgumentError, "'#{working_dir}' is not in a git working tree"
     end
@@ -124,12 +144,15 @@ module Git
     #
     # @return [String, nil] the absolute path, or `nil` for bare repos
     #
+    # @raise [Git::Error] if the path cannot be expanded, which happens when the
+    #   process working directory has been removed
+    #
     # @api private
     #
     def resolve_working_directory(path, bare:)
       return nil if bare
 
-      File.expand_path(path || Dir.pwd)
+      expand_path(path, WORKING_DIRECTORY_MESSAGE)
     end
     private_class_method :resolve_working_directory
 
@@ -139,24 +162,24 @@ module Git
     #
     # @param path [String, nil] the repository path or `nil`
     #
-    # @param working_dir [String, nil] the working directory used for relative
-    #   path resolution
-    #
-    # @param bare [Boolean] whether this is a bare repository
-    #
-    # @param bare_default [String, nil] for bare repos, used as the default when
-    #   `path` is `nil`
+    # @param working_dir [String, nil] the working directory whose `.git` is the
+    #   default when `path` is `nil`, or `nil` for a bare repository, whose
+    #   default is the process working directory
     #
     # @return [String] the absolute path to the repository
     #
+    # @raise [Git::Error] if the path cannot be expanded, which happens when the
+    #   process working directory has been removed
+    #
     # @api private
     #
-    def resolve_repository(path, working_dir, bare:, bare_default: nil)
-      initial_path = if bare
-                       File.expand_path(path || bare_default || Dir.pwd)
-                     else
-                       File.expand_path(path || '.git', working_dir)
-                     end
+    def resolve_repository(path, working_dir)
+      initial_path =
+        if working_dir && path.nil?
+          File.join(working_dir, '.git')
+        else
+          expand_path(path, REPOSITORY_MESSAGE)
+        end
 
       resolve_gitdir_pointer(initial_path)
     end
@@ -171,6 +194,8 @@ module Git
     #
     # @return [String] the resolved absolute path
     #
+    # @raise [Git::Error] if `path` is a file that cannot be read
+    #
     # Relative pointer targets are resolved from the directory containing the
     # pointer file itself, matching git's pointer-file semantics.
     #
@@ -179,7 +204,7 @@ module Git
     def resolve_gitdir_pointer(path)
       return path unless File.file?(path)
 
-      gitdir_content = File.read(path).strip
+      gitdir_content = Git::SystemCallGuard.call('Failed to read the gitdir pointer file') { File.read(path) }.strip
       return path unless gitdir_content.start_with?('gitdir: ')
 
       gitdir_path = gitdir_content.sub(/\Agitdir: /, '')
@@ -191,16 +216,59 @@ module Git
     #
     # @param path [String, nil] the index path or `nil`
     #
-    # @param repository [String] the repository directory used for relative
-    #   path resolution
+    # @param repository [String] the repository directory whose `index` is the
+    #   default when `path` is `nil`
     #
     # @return [String] the absolute path to the index file
     #
+    # @raise [Git::Error] if the path cannot be expanded, which happens when the
+    #   process working directory has been removed
+    #
     # @api private
     #
     def resolve_index(path, repository)
-      File.expand_path(path || 'index', repository)
+      return File.join(repository, 'index') unless path
+
+      expand_path(path, INDEX_MESSAGE)
     end
     private_class_method :resolve_index
+
+    # Expand a path the way a shell prompt would before git runs
+    #
+    # Follows `File.expand_path`: `~` is the home directory, a relative path is
+    # joined onto `base` (or onto the process working directory when `base` is
+    # `nil`), `.` and `..` are normalized, and an absolute path is unchanged.
+    #
+    # @example Expand a relative path against the process working directory
+    #   Git::PathResolver.expand_path('repo', 'Failed to resolve the working directory')
+    #   #=> '/current/dir/repo'
+    #
+    # @example Expand a relative path against another directory
+    #   Git::PathResolver.expand_path('repo', 'Failed to resolve the working directory', base: '/output')
+    #   #=> '/output/repo'
+    #
+    # @param path [String, Pathname, nil] the path to expand, or `nil` for
+    #   `base` itself
+    #
+    # @param message [String] the message of the {Git::Error} raised when the
+    #   expansion fails
+    #
+    # @param base [String, Pathname, nil] the directory a relative `path` is
+    #   expanded against, or `nil` for the process working directory
+    #
+    # @return [String] the absolute path
+    #
+    # @raise [ArgumentError] if `~` cannot be expanded because no home directory
+    #   can be determined, or if the path begins with `~user` for a user that
+    #   does not exist
+    #
+    # @raise [Git::Error] if the path cannot be expanded, which happens when the
+    #   process working directory has been removed
+    #
+    # @api private
+    #
+    def expand_path(path, message, base: nil)
+      Git::SystemCallGuard.call(message) { File.expand_path(path || '.', base) }
+    end
   end
 end