git 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd870e7039cc00b042255eaf275983499afc046343ddae22a0ae121c0ccae5e2
-  data.tar.gz: c107f2b83705d0c5353328f011346c01dbed28671323e36258d73c3c5205f835
+  metadata.gz: e100c7e550894cd173db6f141a4a79963d1ccb832d028a459cf7e4193ae968ec
+  data.tar.gz: 9275a29a6a88c441e44084a9ba26dbbd0d40889784225635d410965dafaea2af
 SHA512:
-  metadata.gz: 82be60353d5481abd360bc7c0a1b18ef5c6dacadfe9c6185d524d754e0203b4dd2a687942c8813962ccc329cea6c14014d0a77296801c7d557e62b9b91880f75
-  data.tar.gz: b6aeeb8d2f12639ff26837de8ca5d910457b58b8356cd82c5843ebc4ea269f49b8cf0fe1b1e1c0f598304b8f82018416c5f2d701b84cc8f0494ce127316605c9
+  metadata.gz: e29086daa9c6089c6e7f1e4b889aae7cac9e1cd199937f3e8eb44e5b59dccaa3c484d85dab56f2da07172161b6e2f87269b78e5aab868b947a2f161e7c9de977
+  data.tar.gz: f09a9f3a7e7e9cdc218016737e2dc444392351191f456b6ace8dd32088c17517b43de0f93b6f6925e0d9ec2a8e8be9866d4b35b28420ebc7f6e43adc889e4bab

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.2.0"
+  ".": "4.3.0"
 }

data/.rubocop_todo.yml

@@ -9,4 +9,4 @@
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 1150
+  Max: 1160

data/CHANGELOG.md

@@ -5,6 +5,13 @@
 
 # Change Log
 
+## [4.3.0](https://github.com/ruby-git/ruby-git/compare/v4.2.0...v4.3.0) (2026-01-15)
+
+
+### Features
+
+* Add support for git fsck command ([c402003](https://github.com/ruby-git/ruby-git/commit/c402003ce0c626a5c4737838cddc4b932638c172)), closes [#218](https://github.com/ruby-git/ruby-git/issues/218)
+
 ## [4.2.0](https://github.com/ruby-git/ruby-git/compare/v4.1.2...v4.2.0) (2026-01-11)
 
 

data/README.md

@@ -277,6 +277,20 @@ repo.worktrees.each do |worktree|
   worktree.to_s
 end
 
+# Check repository integrity with fsck
+result = repo.fsck
+result.dangling.each { |obj| puts "dangling #{obj.type}: #{obj.sha}" }
+result.missing.each { |obj| puts "missing #{obj.type}: #{obj.sha}" }
+
+# Check if repository has any issues
+puts "Repository is clean" if result.empty?
+
+# fsck with options
+result = repo.fsck(unreachable: true, strict: true)
+
+# Suppress dangling object output
+result = repo.fsck(dangling: false)
+
 repo.config('user.name')  # returns 'Scott Chacon'
 repo.config # returns whole config hash
 

data/lib/git/args_builder.rb

@@ -12,6 +12,14 @@ module Git
     ARG_BUILDERS = {
       boolean: ->(config, value) { value ? config[:flag] : [] },
 
+      boolean_negatable: lambda do |config, value|
+        case value
+        when true then config[:flag]
+        when false then config[:flag].sub('--', '--no-')
+        else []
+        end
+      end,
+
       valued_equals: ->(config, value) { "#{config[:flag]}=#{value}" if value },
 
       valued_space: ->(config, value) { [config[:flag], value.to_s] if value },

data/lib/git/base.rb

@@ -654,6 +654,57 @@ module Git
       lib.gc
     end
 
+    # Verifies the connectivity and validity of objects in the database
+    #
+    # Runs `git fsck` to check repository integrity and identify dangling,
+    # missing, or unreachable objects.
+    #
+    # @overload fsck(objects = [], options = {})
+    #   @param objects [Array<String>] specific objects to treat as heads for unreachability trace.
+    #     If no objects are given, git fsck defaults to using the index file, all SHA-1
+    #     references in the refs namespace, and all reflogs.
+    #   @param [Hash] options options to pass to the underlying `git fsck` command
+    #
+    #   @option options [Boolean] :unreachable print unreachable objects
+    #   @option options [Boolean] :strict enable strict checking
+    #   @option options [Boolean] :connectivity_only check only connectivity (faster)
+    #   @option options [Boolean] :root report root nodes
+    #   @option options [Boolean] :tags report tags
+    #   @option options [Boolean] :cache consider objects in the index
+    #   @option options [Boolean] :no_reflogs do not consider reflogs
+    #   @option options [Boolean] :lost_found write dangling objects to .git/lost-found
+    #     (note: this modifies the repository by creating files)
+    #   @option options [Boolean, nil] :dangling print dangling objects (true/false/nil for default)
+    #   @option options [Boolean, nil] :full check objects in alternate pools (true/false/nil for default)
+    #   @option options [Boolean, nil] :name_objects name objects by refs (true/false/nil for default)
+    #   @option options [Boolean, nil] :references check refs database consistency (true/false/nil for default)
+    #
+    #   @return [Git::FsckResult] categorized objects flagged by fsck
+    #
+    #   @example Check repository integrity
+    #     result = git.fsck
+    #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.sha}" }
+    #
+    #   @example Check with strict mode and suppress dangling output
+    #     result = git.fsck(strict: true, dangling: false)
+    #
+    #   @example Check if repository has any issues
+    #     result = git.fsck
+    #     puts "Repository is clean" if result.empty?
+    #
+    #   @example List root commits
+    #     result = git.fsck(root: true)
+    #     result.root.each { |obj| puts obj.sha }
+    #
+    #   @example Check specific objects
+    #     result = git.fsck('abc1234', 'def5678')
+    #
+    # rubocop:disable Style/ArgumentsForwarding
+    def fsck(*objects, **opts)
+      lib.fsck(*objects, **opts)
+    end
+    # rubocop:enable Style/ArgumentsForwarding
+
     def apply(file)
       return unless File.exist?(file)
 

data/lib/git/fsck_object.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents an object returned by `git fsck`
+  #
+  # This class provides information about dangling, missing, unreachable, or
+  # problematic Git objects found during repository integrity checks.
+  #
+  # @api public
+  #
+  class FsckObject
+    # The type of the Git object
+    # @return [Symbol] one of :commit, :tree, :blob, or :tag
+    attr_reader :type
+
+    # The SHA-1 hash of the object
+    # @return [String] the 40-character SHA-1 hash
+    attr_reader :sha
+
+    # A warning or error message associated with this object
+    # @return [String, nil] the message, or nil if no message
+    attr_reader :message
+
+    # A name describing how the object is reachable (from --name-objects)
+    # @return [String, nil] the name, or nil if not provided
+    attr_reader :name
+
+    # Create a new FsckObject
+    #
+    # @param type [Symbol] the object type (:commit, :tree, :blob, or :tag)
+    # @param sha [String] the 40-character SHA-1 hash
+    # @param message [String, nil] optional warning/error message
+    # @param name [String, nil] optional name from --name-objects (e.g., "HEAD~2^2:src/")
+    #
+    def initialize(type:, sha:, message: nil, name: nil)
+      @type = type
+      @sha = sha
+      @message = message
+      @name = name
+    end
+
+    # Returns the SHA as the string representation
+    # @return [String] the SHA-1 hash
+    def to_s
+      sha
+    end
+  end
+end

data/lib/git/fsck_result.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents the result of running `git fsck`
+  #
+  # This class provides structured access to the objects found during a
+  # repository integrity check, categorized by their status.
+  #
+  # @api public
+  #
+  class FsckResult
+    # Objects not referenced by any other object
+    # @return [Array<Git::FsckObject>]
+    attr_reader :dangling
+
+    # Objects that are referenced but not present in the repository
+    # @return [Array<Git::FsckObject>]
+    attr_reader :missing
+
+    # Objects not reachable from any ref
+    # @return [Array<Git::FsckObject>]
+    attr_reader :unreachable
+
+    # Objects with warnings (each includes a message)
+    # @return [Array<Git::FsckObject>]
+    attr_reader :warnings
+
+    # Root nodes (commits with no parents) when --root is used
+    # @return [Array<Git::FsckObject>]
+    attr_reader :root
+
+    # Tagged objects when --tags is used
+    # @return [Array<Git::FsckObject>]
+    attr_reader :tagged
+
+    # rubocop:disable Metrics/ParameterLists
+
+    # Create a new FsckResult
+    #
+    # @param dangling [Array<Git::FsckObject>] dangling objects
+    # @param missing [Array<Git::FsckObject>] missing objects
+    # @param unreachable [Array<Git::FsckObject>] unreachable objects
+    # @param warnings [Array<Git::FsckObject>] objects with warnings
+    # @param root [Array<Git::FsckObject>] root nodes
+    # @param tagged [Array<Git::FsckObject>] tagged objects
+    #
+    def initialize(dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [])
+      @dangling = dangling
+      @missing = missing
+      @unreachable = unreachable
+      @warnings = warnings
+      @root = root
+      @tagged = tagged
+    end
+
+    # rubocop:enable Metrics/ParameterLists
+
+    # Returns true if any issues were found
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Repository has issues!" if result.any_issues?
+    #
+    def any_issues?
+      [dangling, missing, unreachable, warnings].any?(&:any?)
+    end
+
+    # Returns true if no issues were found
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Repository is clean" if result.empty?
+    #
+    def empty?
+      !any_issues?
+    end
+
+    # Returns all objects from all categories (excluding informational root/tagged)
+    #
+    # @return [Array<Git::FsckObject>]
+    #
+    # @example
+    #   result = git.fsck
+    #   result.all_objects.each { |obj| puts obj.sha }
+    #
+    def all_objects
+      dangling + missing + unreachable + warnings
+    end
+
+    # Returns the total number of issues found
+    #
+    # @return [Integer]
+    #
+    # @example
+    #   result = git.fsck
+    #   puts "Found #{result.count} issues"
+    #
+    def count
+      all_objects.size
+    end
+
+    # Returns a hash representation of the result
+    #
+    # @return [Hash{Symbol => Array<Git::FsckObject>}]
+    #
+    # @example
+    #   result = git.fsck
+    #   result.to_h # => { dangling: [...], missing: [...], ... }
+    #
+    def to_h
+      {
+        dangling: dangling, missing: missing, unreachable: unreachable,
+        warnings: warnings, root: root, tagged: tagged
+      }
+    end
+  end
+end

data/lib/git/lib.rb

@@ -1530,6 +1530,38 @@ module Git
       command('gc', '--prune', '--aggressive', '--auto')
     end
 
+    FSCK_OPTION_MAP = [
+      { flag: '--no-progress', type: :static },
+      { keys: [:unreachable],       flag: '--unreachable',       type: :boolean },
+      { keys: [:strict],            flag: '--strict',            type: :boolean },
+      { keys: [:connectivity_only], flag: '--connectivity-only', type: :boolean },
+      { keys: [:root],              flag: '--root',              type: :boolean },
+      { keys: [:tags],              flag: '--tags',              type: :boolean },
+      { keys: [:cache],             flag: '--cache',             type: :boolean },
+      { keys: [:no_reflogs],        flag: '--no-reflogs',        type: :boolean },
+      { keys: [:lost_found],        flag: '--lost-found',        type: :boolean },
+      { keys: [:dangling],          flag: '--dangling',          type: :boolean_negatable },
+      { keys: [:full],              flag: '--full',              type: :boolean_negatable },
+      { keys: [:name_objects],      flag: '--name-objects',      type: :boolean_negatable },
+      { keys: [:references],        flag: '--references',        type: :boolean_negatable }
+    ].freeze
+
+    def fsck(*objects, **opts)
+      args = ArgsBuilder.build(opts, FSCK_OPTION_MAP)
+      args.concat(objects) unless objects.empty?
+      # fsck returns non-zero exit status when issues are found:
+      # 1 = errors found, 2 = missing objects, 4 = warnings
+      # We still want to parse the output in these cases
+      output = begin
+        command('fsck', *args)
+      rescue Git::FailedError => e
+        raise unless [1, 2, 4].include?(e.result.status.exitstatus)
+
+        e.result.stdout
+      end
+      parse_fsck_output(output)
+    end
+
     READ_TREE_OPTION_MAP = [
       { keys: [:prefix], flag: '--prefix', type: :valued_equals }
     ].freeze
@@ -1684,8 +1716,52 @@ module Git
       { keys: [:between], type: :custom, builder: ->(value) { "#{value[0]}..#{value[1]}" if value } }
     ].freeze
 
+    FSCK_OBJECT_PATTERN = /\A(dangling|missing|unreachable) (\w+) ([0-9a-f]{40})(?: \((.+)\))?\z/
+    FSCK_WARNING_PATTERN = /\Awarning in (\w+) ([0-9a-f]{40}): (.+)\z/
+    FSCK_ROOT_PATTERN = /\Aroot ([0-9a-f]{40})\z/
+    FSCK_TAGGED_PATTERN = /\Atagged (\w+) ([0-9a-f]{40}) \((.+)\) in ([0-9a-f]{40})\z/
+
+    private_constant :FSCK_OBJECT_PATTERN, :FSCK_WARNING_PATTERN, :FSCK_ROOT_PATTERN, :FSCK_TAGGED_PATTERN
+
     private
 
+    def parse_fsck_output(output)
+      result = { dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [] }
+      output.each_line { |line| parse_fsck_line(line.strip, result) }
+      Git::FsckResult.new(**result)
+    end
+
+    def parse_fsck_line(line, result)
+      parse_fsck_object_line(line, result) ||
+        parse_fsck_warning_line(line, result) ||
+        parse_fsck_root_line(line, result) ||
+        parse_fsck_tagged_line(line, result)
+    end
+
+    def parse_fsck_object_line(line, result)
+      return unless (match = FSCK_OBJECT_PATTERN.match(line))
+
+      result[match[1].to_sym] << Git::FsckObject.new(type: match[2].to_sym, sha: match[3], name: match[4])
+    end
+
+    def parse_fsck_warning_line(line, result)
+      return unless (match = FSCK_WARNING_PATTERN.match(line))
+
+      result[:warnings] << Git::FsckObject.new(type: match[1].to_sym, sha: match[2], message: match[3])
+    end
+
+    def parse_fsck_root_line(line, result)
+      return unless (match = FSCK_ROOT_PATTERN.match(line))
+
+      result[:root] << Git::FsckObject.new(type: :commit, sha: match[1])
+    end
+
+    def parse_fsck_tagged_line(line, result)
+      return unless (match = FSCK_TAGGED_PATTERN.match(line))
+
+      result[:tagged] << Git::FsckObject.new(type: match[1].to_sym, sha: match[2], name: match[3])
+    end
+
     def parse_diff_path_status(args)
       command_lines('diff', *args).each_with_object({}) do |line, memo|
         status, path = split_status_line(line)

data/lib/git/version.rb

@@ -3,5 +3,5 @@
 module Git
   # The current gem version
   # @return [String] the current gem version.
-  VERSION = '4.2.0'
+  VERSION = '4.3.0'
 end

data/lib/git.rb

@@ -18,6 +18,8 @@ require 'git/diff'
 require 'git/encoding_utils'
 require 'git/errors'
 require 'git/escaped_path'
+require 'git/fsck_object'
+require 'git/fsck_result'
 require 'git/index'
 require 'git/lib'
 require 'git/log'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.3.0
 platform: ruby
 authors:
 - Scott Chacon and others
@@ -276,6 +276,8 @@ files:
 - lib/git/encoding_utils.rb
 - lib/git/errors.rb
 - lib/git/escaped_path.rb
+- lib/git/fsck_object.rb
+- lib/git/fsck_result.rb
 - lib/git/index.rb
 - lib/git/lib.rb
 - lib/git/log.rb
@@ -308,8 +310,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/4.2.0/file/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/git/4.2.0
+  changelog_uri: https://rubydoc.info/gems/git/4.3.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/git/4.3.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: