git 5.2.0 → 5.4.0

data/lib/git/tag_info.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require 'git/author'
+require 'time'
+
+require 'git/author_info'
 
 module Git
   # Value object representing tag metadata from git tag output
@@ -9,19 +11,25 @@ module Git
   # commands. It contains only the data parsed from git output without any
   # repository context or operations.
   #
+  # The tagger identity is a nested {Git::AuthorInfo}. Its `date` is a `Time`
+  # parsed from git's strict ISO 8601 output, not an ISO 8601 string.
+  #
   # @example Annotated tag
   #   info = Git::TagInfo.new(
   #     name: 'v1.0.0',
   #     oid: 'abc123def456',        # tag object's ID
   #     target_oid: 'def456abc789', # commit it points to
   #     objecttype: 'tag',
-  #     tagger_name: 'John Doe',
-  #     tagger_email: '<john@example.com>',
-  #     tagger_date: '2024-01-15T10:30:00-08:00',
+  #     tagger: Git::AuthorInfo.new(
+  #       name: 'John Doe',
+  #       email: 'john@example.com',
+  #       date: Time.iso8601('2024-01-15T10:30:00-08:00')
+  #     ),
   #     message: 'Release version 1.0.0'
   #   )
   #   info.annotated?   #=> true
   #   info.tagger.name  #=> 'John Doe'
+  #   info.tagger.date  #=> 2024-01-15 10:30:00 -0800
   #
   # @example Lightweight tag
   #   info = Git::TagInfo.new(
@@ -29,18 +37,19 @@ module Git
   #     oid: nil,                   # no tag object exists
   #     target_oid: 'def456abc789', # commit ID
   #     objecttype: 'commit',
-  #     tagger_name: nil,
-  #     tagger_email: nil,
-  #     tagger_date: nil,
+  #     tagger: nil,
   #     message: nil
   #   )
   #   info.lightweight?  #=> true
   #   info.tagger        #=> nil
   #
-  # @see Git::Tag for the full-featured tag object with operations
+  # @see Git::Repository::ObjectOperations#tag_list for the repository method
+  #   that returns these
   #
   # @see Git::Commands::Tag::List for the command that produces these
   #
+  # @see Git::AuthorInfo for the nested tagger identity
+  #
   # @api public
   #
   # @!attribute [r] name
@@ -65,19 +74,18 @@ module Git
   # @!attribute [r] objecttype
   #   @return [String] 'tag' for annotated tags, 'commit' for lightweight tags
   #
-  # @!attribute [r] tagger_name
-  #   @return [String, nil] the tagger's name, or nil for lightweight tags
+  # @!attribute [r] tagger
+  #   The identity of the person who created the tag object.
   #
-  # @!attribute [r] tagger_email
-  #   @return [String, nil] the tagger's email, or nil for lightweight tags
+  #   Lightweight tags have no tag object and therefore no tagger. The nested
+  #   `email` has no angle brackets and the nested `date` is a `Time`.
   #
-  # @!attribute [r] tagger_date
-  #   @return [String, nil] the tag date in ISO 8601 format, or nil for lightweight tags
+  #   @return [Git::AuthorInfo, nil] the tagger, or nil for lightweight tags
   #
   # @!attribute [r] message
   #   @return [String, nil] the tag message, or nil for lightweight tags
   #
-  TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger_name, :tagger_email, :tagger_date, :message) do
+  TagInfo = Data.define(:name, :oid, :target_oid, :objecttype, :tagger, :message) do
     # @return [Boolean] true if this is an annotated tag (oid is present)
     def annotated?
       !oid.nil?
@@ -87,20 +95,5 @@ module Git
     def lightweight?
       oid.nil?
     end
-
-    # Return the tagger as an Author object
-    #
-    # @return [Git::Author, nil] the tagger as an Author object, or nil for lightweight tags
-    def tagger
-      return nil unless annotated? && tagger_name && tagger_email
-
-      # Git::Author expects format "Name <email> timestamp timezone"
-      # We construct a minimal format that will parse correctly
-      author = Git::Author.new('')
-      author.name = tagger_name
-      # Remove angle brackets if present
-      author.email = tagger_email.gsub(/\A<|>\z/, '')
-      author
-    end
   end
 end

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.2.0'
+  VERSION = '5.4.0'
 
   # Represents a git version with major, minor, and patch components
   #

data/lib/git/worktree.rb

@@ -12,6 +12,17 @@ module Git
   #   worktree.add
   #   worktree.remove
   #
+  # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} and the
+  #   path-based worktree operations on {Git::Repository} instead
+  #
+  #   {Git::Repository::WorktreeOperations#worktree_list} returns immutable
+  #   {Git::WorktreeInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the worktree path instead (for example
+  #   {Git::Repository::WorktreeOperations#worktree_add} and
+  #   {Git::Repository::WorktreeOperations#worktree_remove}). {#gcommit},
+  #   {#add}, and {#remove} each emit a deprecation warning; the `dir`, `full`,
+  #   `to_s`, and `to_a` readers do not.
+  #
   # @api public
   #
   class Worktree
@@ -69,7 +80,19 @@ module Git
     # @raise [Git::FailedError] if git must resolve the commit and exits with a
     #   non-zero exit status
     #
+    # @deprecated Use {Git::WorktreeInfo#head} from
+    #   {Git::Repository::WorktreeOperations#worktree_list} instead
+    #
+    #   `head` is always the commit SHA as a `String` (or `nil` for a bare main
+    #   worktree). Call `repo.gcommit(info.head)` for the commit object.
+    #
+    # @see Git::WorktreeInfo#head
+    #
     def gcommit
+      Git::Deprecation.warn(
+        'Git::Worktree#gcommit is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::WorktreeInfo#head from Git::Repository#worktree_list instead.'
+      )
       @gcommit ||= worktree_repository.gcommit(@full)
       @gcommit
     end
@@ -87,7 +110,15 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_add} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_add
+    #
     def add
+      Git::Deprecation.warn(
+        'Git::Worktree#add is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_add instead.'
+      )
       worktree_repository.worktree_add(@dir, @gcommit)
     end
 
@@ -102,7 +133,15 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_remove} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_remove
+    #
     def remove
+      Git::Deprecation.warn(
+        'Git::Worktree#remove is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_remove instead.'
+      )
       worktree_repository.worktree_remove(@dir)
     end
 

data/lib/git/worktree_info.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object for one entry of `git worktree list`
+  #
+  # Each entry carries what `git worktree list --porcelain` reports for a
+  # worktree: its path, the checked-out HEAD and branch, and whether it is bare,
+  # detached, locked, or prunable, with the reason git gives for the last two.
+  #
+  # @example A locked linked worktree with a branch checked out
+  #   info = Git::WorktreeInfo.new(
+  #     path: '/tmp/wt/linked',
+  #     head: 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f',
+  #     branch: 'refs/heads/linked',
+  #     bare: false,
+  #     detached: false,
+  #     locked: true,
+  #     lock_reason: 'on purpose',
+  #     prunable: false,
+  #     prune_reason: nil
+  #   )
+  #
+  #   info.path         # => '/tmp/wt/linked'
+  #   info.head         # => 'f3e2c1ffb860086504eeb27b77a1d0028b68fd8f'
+  #   info.branch       # => 'refs/heads/linked'
+  #   info.locked?      # => true
+  #   info.lock_reason  # => 'on purpose'
+  #   info.detached?    # => false
+  #   info.to_s         # => '/tmp/wt/linked'
+  #
+  # @example Pass an entry back to a worktree operation
+  #   info = repo.worktree_list.find { |w| w.branch == 'refs/heads/linked' }
+  #   repo.worktree_remove(info)
+  #
+  # @see Git::Repository::WorktreeOperations#worktree_list for the repository
+  #   method that returns these
+  #
+  # @api public
+  #
+  # @!attribute [r] path
+  #   @return [String] the worktree directory as git reports it
+  #
+  # @!attribute [r] head
+  #   @return [String, nil] the full object ID of the checked-out HEAD commit
+  #     (the all-zero object ID when the branch has no commits yet), or nil for a
+  #     bare main worktree
+  #
+  # @!attribute [r] branch
+  #   @return [String, nil] the full refname of the checked-out branch (e.g.,
+  #     'refs/heads/main'), or nil when the worktree is bare or detached
+  #
+  # @!attribute [r] bare
+  #   @return [Boolean] true if this is the main worktree of a bare repository
+  #
+  # @!attribute [r] detached
+  #   @return [Boolean] true if HEAD is detached in this worktree
+  #
+  # @!attribute [r] locked
+  #   @return [Boolean] true if the worktree is locked
+  #
+  # @!attribute [r] lock_reason
+  #   @return [String, nil] the reason given when the worktree was locked, or nil
+  #     when it is not locked or was locked without a reason
+  #
+  # @!attribute [r] prunable
+  #   @return [Boolean] true if `git worktree prune` would remove this entry
+  #
+  # @!attribute [r] prune_reason
+  #   @return [String, nil] git's explanation of why the entry is prunable, or
+  #     nil when it is not prunable
+  #
+  WorktreeInfo = Data.define(
+    :path,
+    :head,
+    :branch,
+    :bare,
+    :detached,
+    :locked,
+    :lock_reason,
+    :prunable,
+    :prune_reason
+  ) do
+    # Whether this is the main worktree of a bare repository
+    #
+    # @example
+    #   info.bare? # => false
+    #
+    # @return [Boolean] true if the worktree is bare
+    def bare? = bare
+
+    # Whether HEAD is detached in this worktree
+    #
+    # @example
+    #   info.detached? # => false
+    #
+    # @return [Boolean] true if HEAD is detached
+    def detached? = detached
+
+    # Whether the worktree is locked
+    #
+    # @example
+    #   info.locked? # => true
+    #
+    # @return [Boolean] true if the worktree is locked
+    def locked? = locked
+
+    # Whether `git worktree prune` would remove this entry
+    #
+    # @example
+    #   info.prunable? # => false
+    #
+    # @return [Boolean] true if the entry is prunable
+    def prunable? = prunable
+
+    # Returns the worktree path
+    #
+    # Lets an entry be passed directly to the worktree operations that take a
+    # path, such as {Git::Repository::WorktreeOperations#worktree_remove}.
+    #
+    # @example Convert to string
+    #   info.to_s # => '/tmp/wt/linked'
+    #
+    # @return [String] the worktree path
+    def to_s
+      path
+    end
+  end
+end

data/lib/git/worktrees.rb

@@ -10,6 +10,15 @@ module Git
   #   worktrees = repo.worktrees
   #   worktrees.each { |wt| puts wt.dir }
   #
+  # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead
+  #
+  #   {Git::Repository::WorktreeOperations#worktree_list} returns
+  #   `Array<Git::WorktreeInfo>` (immutable value objects). Look a worktree up
+  #   by path with `worktree_list.find { |w| w.path == path }` in place of
+  #   {#[]}, and call {Git::Repository::WorktreeOperations#worktree_prune} in
+  #   place of {#prune}. Constructing a `Git::Worktrees` emits a deprecation
+  #   warning.
+  #
   # @api public
   #
   class Worktrees
@@ -24,12 +33,21 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead
+    #
+    # @see Git::Repository::WorktreeOperations#worktree_list
+    #
     def initialize(base)
+      Git::Deprecation.warn(
+        'Git::Worktrees is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#worktree_list instead.'
+      )
       @worktrees = {}
 
       @base = base
 
-      worktree_repository.worktrees_all.each do |w|
+      # worktrees_all is deprecated too; silence it so one Git::Worktrees.new emits one warning
+      Git::Deprecation.silence { worktree_repository.worktrees_all }.each do |w|
         @worktrees[w[0]] = Git::Worktree.new(@base, w[0], w[1])
       end
     end

data/lib/git.rb

@@ -46,6 +46,7 @@ module Git
 end
 
 require 'git/author'
+require 'git/author_info'
 require 'git/branch'
 require 'git/branch_info'
 require 'git/branches'
@@ -74,6 +75,7 @@ require 'git/fsck_object'
 require 'git/fsck_result'
 require 'git/parsers/ls_remote'
 require 'git/parsers/remote'
+require 'git/parsers/status'
 require 'git/version_constraint'
 require 'git/commands'
 require 'git/log'
@@ -82,6 +84,8 @@ require 'git/remote'
 require 'git/remote_info'
 require 'git/repository'
 require 'git/status'
+require 'git/status_file_info'
+require 'git/status_info'
 require 'git/stash'
 require 'git/stash_info'
 require 'git/stashes'
@@ -91,6 +95,7 @@ require 'git/tag_info'
 require 'git/url'
 require 'git/version'
 require 'git/worktree'
+require 'git/worktree_info'
 require 'git/worktrees'
 
 # The Git module provides the basic functions to open a git

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.4.0
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -311,6 +311,7 @@ files:
 - git.gemspec
 - lib/git.rb
 - lib/git/author.rb
+- lib/git/author_info.rb
 - lib/git/branch.rb
 - lib/git/branch_delete_failure.rb
 - lib/git/branch_delete_result.rb
@@ -504,7 +505,9 @@ files:
 - lib/git/parsers/ls_tree.rb
 - lib/git/parsers/remote.rb
 - lib/git/parsers/stash.rb
+- lib/git/parsers/status.rb
 - lib/git/parsers/tag.rb
+- lib/git/parsers/worktree.rb
 - lib/git/path_resolver.rb
 - lib/git/remote.rb
 - lib/git/remote_info.rb
@@ -528,6 +531,8 @@ files:
 - lib/git/stash_info.rb
 - lib/git/stashes.rb
 - lib/git/status.rb
+- lib/git/status_file_info.rb
+- lib/git/status_info.rb
 - lib/git/tag_delete_failure.rb
 - lib/git/tag_delete_result.rb
 - lib/git/tag_info.rb
@@ -535,6 +540,7 @@ files:
 - lib/git/version.rb
 - lib/git/version_constraint.rb
 - lib/git/worktree.rb
+- lib/git/worktree_info.rb
 - lib/git/worktrees.rb
 homepage: http://github.com/ruby-git/ruby-git
 licenses:
@@ -542,8 +548,8 @@ licenses:
 metadata:
   homepage_uri: http://github.com/ruby-git/ruby-git
   source_code_uri: http://github.com/ruby-git/ruby-git
-  changelog_uri: https://rubydoc.info/gems/git/5.2.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/5.2.0
+  changelog_uri: https://rubydoc.info/gems/git/5.4.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/5.4.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: