thuban 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41d8c298a842a358db7f9ec204f0b25eb9a11c6b1baa1ac7206f230d148c9874
-  data.tar.gz: 3ca82e618bf82cc6f40851ac4bd230179a242dc1ba96059379e42e3c4826e6ef
+  metadata.gz: f141979f71fdcf5cb0cc8b6678e084569285d9d3ee9f21bf2e584dbeb98a9139
+  data.tar.gz: 9fbdf6deec48a31479b5d2b12f564beeaac8cde969d9f50a68f476d89011e59d
 SHA512:
-  metadata.gz: 121c47d02bb849760a8e7ca06c8a272dc29bcdc7165401c43064146950207f763dd141118dcfdeb279baa1cc80e02d79a9086077c788ff7a2be9704aa451affe
-  data.tar.gz: e1bc999f1a766a6ddc7602c6aae005ea5fc5a90530c2646820b9b9b66f3dad0440dc6fe0fd117b31a6e0410b5fe9126d1a96cb287b7e0524ffb6b21154b61059
+  metadata.gz: b98d9e65ebe84062f9960c19557a871a80344bcbdd9c9bbb77ae9ffe8e30579464249be003a6f26831b76d63436fc4641dd741678eeb24f15b2f668706dc8512
+  data.tar.gz: 4f8eb7a9e0214dcd4e34ce1f08bb8d771c87ad86b428ac5ebe14a26a1bf86502bb6cea8b39d25c14cc475a44e2fdc3d3683d6129e53111599694339fcf03333b

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0 - 2026-09-14
+
+- Add `Thuban::IgnoreMatcher.load` with Git-compatible ignore source precedence
+- Publish the ignore matcher API and type signatures
+
 ## 0.1.0 - 2026-09-12
 
-- Initial release
+- Initial release

data/README.md

@@ -1,56 +1,147 @@
-# Thuban
-
-Thuban is a pure Ruby reader for local Git repositories. It reads SHA-1
-objects, packfiles, refs, commits, trees, blobs, indexes, status, and blame,
-and supports a guarded checkout.
+<h1 align="center">Thuban</h1>
+
+<p align="center">
+  <strong>A pure Ruby reader for local Git repositories</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/thuban"><img src="https://img.shields.io/gem/v/thuban.svg?colorB=319e8c" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/thuban"><img src="https://img.shields.io/gem/dt/thuban.svg" alt="Downloads"></a>
+  <a href="https://github.com/noxdea/thuban/actions/workflows/main.yml"><img src="https://github.com/noxdea/thuban/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby 3.1+">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#scope">Scope</a>
+</p>
+
+---
+
+Thuban is a pure Ruby Git repository reader for objects, packs, index,
+status, blame, and guarded checkout. It works directly with local repository
+data without invoking the Git executable.
+
+## Features
+
+- Reads loose objects and packfiles, including deltified objects
+- Resolves refs, branches, commits, trees, and blobs
+- Reads the index and reports staged, worktree, and untracked changes
+- Tracks line history across commits and renames with blame
+- Writes files atomically and checks out branches with collision guards
+- Supports linked worktrees and packed refs
 
 ## Installation
 
+Add Thuban to your Gemfile:
+
 ```ruby
-gem "thuban", "~> 0.1.0"
+gem "thuban", "~> 0.2.0"
 ```
 
-## Usage
+Then install it:
+
+```sh
+bundle install
+```
+
+Thuban requires Ruby 3.1 or later and targets SHA-1 Git repositories.
+
+## Quick Start
+
+Open the repository containing the current directory:
 
 ```ruby
 require "thuban"
 
 repo = Thuban::Repository.new(Dir.pwd)
-repo.head
-repo.branch
+
+puts repo.branch
+puts repo.head
+
+repo.status.each do |entry|
+  puts "#{entry.code} #{entry.path}"
+end
+```
+
+## Usage
+
+### Read Repository Data
+
+```ruby
+repo.refs
+repo.branches
+repo.commit
+repo.tree
 repo.blob("README.md")
-repo.staged_blob("README.md")
-repo.worktree_content("README.md")
-repo.status
+repo.index
 repo.blame("README.md")
 ```
 
-Text comparison stays explicit:
+Pass a branch, tag, or object ID when reading another revision:
 
 ```ruby
-diff = Porrima.diff(
-  repo.staged_blob("README.md").to_s,
-  repo.worktree_content("README.md").to_s
-)
+repo.commit("v0.1.0")
+repo.tree("main")
+repo.blob("README.md", reference: "v0.1.0")
+```
+
+### Compare and Restore Changes
+
+Thuban exposes staged and worktree content for explicit comparison with
+[Porrima](https://github.com/noxdea/porrima):
+
+```ruby
+before = repo.staged_blob("README.md").to_s
+after = repo.worktree_content("README.md").to_s
+diff = Porrima.diff(before, after)
 
-hunk = diff.hunks.first
-repo.write("README.md", Porrima.revert(repo.worktree_content("README.md"), hunk)) if hunk
+if (hunk = diff.hunks.first)
+  repo.write("README.md", Porrima.revert(after, hunk))
+end
+```
+
+### Write and Check Out
+
+```ruby
+repo.write("README.md", "updated contents\n")
+repo.checkout("feature")
 ```
 
 `Repository#write` rejects symlinks, preserves the file mode, and replaces the
 file atomically. `Repository#checkout` requires a clean tracked worktree and
-aborts on untracked collisions.
+aborts on untracked or ignored collisions.
+
+### Match Ignored Paths
+
+Load Git's global excludes, `.git/info/exclude`, and nested `.gitignore` files.
+Thuban also reads nested `.ignore` files for editor compatibility:
+
+```ruby
+ignore = Thuban::IgnoreMatcher.load(Dir.pwd)
+ignore.ignored?("tmp/output.log")
+ignore.ignored?("build", directory: true)
+```
+
+Pass root-relative or absolute files as `extra_files:` to apply them last, or
+set `global: false` to skip `core.excludesFile` and the default global ignore
+file. Thuban resolves the setting from system, XDG, home, and repository config
+files, followed by an enabled worktree config. Included configs, line
+continuations, and command-scoped overrides are not evaluated.
 
 ## Scope
 
-Thuban does not implement a diff algorithm; blame delegates line matching to
-Porrima through the injectable `differ:` argument. It does not perform network
-operations such as fetch or push. Writes are limited to atomic worktree
-replacement and checkout; it does not rewrite history.
+Thuban does not perform network operations such as fetch or push, rewrite
+history, or provide its own diff algorithm. Blame delegates line matching to
+Porrima through the injectable `differ:` argument.
 
-Thuban targets SHA-1 repositories. It supports the index and pack formats
-covered by its test suite, not every optional Git extension. Submodule checkout
-is deliberately excluded.
+Support is limited to the index and pack formats covered by the test suite.
+Submodule checkout and optional Git extensions outside that coverage are not
+supported. Design decisions are recorded in [docs/adr](docs/adr/README.md).
 
 ## Development
 
@@ -62,6 +153,11 @@ bundle exec rbs -I sig -r porrima validate
 gem build --strict thuban.gemspec
 ```
 
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/noxdea/thuban).
+
 ## License
 
-Thuban is available under the MIT License.
+Thuban is available under the [MIT License](LICENSE.txt).

data/lib/thuban/ignore_matcher.rb

@@ -4,6 +4,24 @@ module Thuban
   class IgnoreMatcher
     Rule = Struct.new(:base, :expression, :negated, :directory, keyword_init: true)
 
+    def self.load(root, extra_files: [], global: true)
+      root = File.realpath(root)
+      raise ArgumentError, "ignore root must be a directory" unless File.directory?(root)
+
+      extra_files = Array(extra_files)
+      matcher = new
+      matcher = add_file(matcher, global_ignore_file(root)) if global
+      matcher = add_file(matcher, repository_exclude_file(root))
+      matcher = discover(root, "", matcher, prune: extra_files.empty?)
+      extra_files.each do |file|
+        absolute = File.expand_path(file, root)
+        relative = absolute.delete_prefix(root + File::SEPARATOR)
+        base = absolute == relative ? "" : File.dirname(relative)
+        matcher = add_file(matcher, absolute, base == "." ? "" : base)
+      end
+      matcher
+    end
+
     def initialize(rules = [])
       @rules = rules.freeze
     end
@@ -31,15 +49,143 @@ module Thuban
     end
 
     def ignored?(path, directory: false)
-      ignored = false
-      @rules.each do |rule|
-        next if rule.directory && !directory
-        next unless rule.base.empty? || path.start_with?(rule.base + "/")
+      parts = path.to_s.sub(%r{\A\./}, "").delete_suffix("/").split("/")
+      parts.each_index do |index|
+        candidate = parts[0..index].join("/")
+        candidate_directory = index < parts.length - 1 || directory
+        ignored = false
+        @rules.each do |rule|
+          next if rule.directory && !candidate_directory
+          next unless rule.base.empty? || candidate.start_with?(rule.base + "/")
+
+          local = rule.base.empty? ? candidate : candidate[(rule.base.length + 1)..]
+          ignored = !rule.negated if rule.expression.match?(local)
+        end
+        return true if ignored
+      end
+      false
+    end
+
+    class << self
+      private
+
+      def add_file(matcher, path, base = "")
+        path && File.file?(path) ? matcher.add(File.read(path, encoding: "UTF-8"), base: base) : matcher
+      end
+
+      def discover(root, directory, matcher, prune:)
+        %w[.gitignore .ignore].each do |name|
+          path = File.join(root, directory, name)
+          matcher = add_file(matcher, path, directory) unless File.symlink?(path)
+        end
+        Dir.children(File.join(root, directory)).sort.each do |name|
+          next if name == ".git"
+
+          relative = directory.empty? ? name : File.join(directory, name)
+          absolute = File.join(root, relative)
+          matcher = discover(root, relative, matcher, prune: prune) if File.directory?(absolute) && !File.symlink?(absolute) && (!prune || !matcher.ignored?(relative, directory: true))
+        rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+          next
+        end
+        matcher
+      end
+
+      def global_ignore_file(root)
+        configured = git_config_files(root).filter_map { |path| excludes_file_from(path) }.last
+        return File.expand_path(configured, root) if configured
+
+        File.join(xdg_config_home, "git", "ignore")
+      end
+
+      def git_config_files(root)
+        files = []
+        files << (ENV["GIT_CONFIG_SYSTEM"] || "/etc/gitconfig") unless ENV["GIT_CONFIG_NOSYSTEM"]
+        if ENV["GIT_CONFIG_GLOBAL"]
+          files << ENV["GIT_CONFIG_GLOBAL"]
+        else
+          files << File.join(xdg_config_home, "git", "config") << File.join(Dir.home, ".gitconfig")
+        end
+        if (git_dirs = repository_git_dirs(root))
+          worktree_dir, common_dir = git_dirs
+          common_config = File.join(common_dir, "config")
+          files << common_config
+          files << File.join(worktree_dir, "config.worktree") if worktree_config?(common_config)
+        end
+        files
+      end
+
+      def excludes_file_from(path) = config_value(path, "core", "excludesfile")
+
+      def worktree_config?(path)
+        %w[true yes on 1].include?(config_value(path, "extensions", "worktreeconfig").to_s.downcase)
+      end
+
+      def config_value(path, wanted_section, wanted_key)
+        section = nil
+        value = nil
+        File.foreach(path, encoding: "UTF-8") do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?("#", ";")
+
+          if (match = line.match(/\A\[\s*([^\s\]"]+)\s*\]\z/))
+            section = match[1].downcase
+          elsif section == wanted_section && (match = line.match(/\A#{Regexp.escape(wanted_key)}\s*=\s*(.*)\z/i))
+            value = parse_config_value(match[1])
+          end
+        end
+        value
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+
+      def parse_config_value(source)
+        escapes = {"n" => "\n", "t" => "\t", "b" => "\b", "\\" => "\\", "\"" => "\""}
+        value = +""
+        significant = 0
+        quoted = escaped = false
+        source.each_char do |character|
+          if escaped
+            value << escapes.fetch(character, character)
+            significant = value.length
+            escaped = false
+          elsif character == "\\"
+            escaped = true
+          elsif character == "\""
+            quoted = !quoted
+          elsif !quoted && ["#", ";"].include?(character)
+            break
+          else
+            value << character
+            significant = value.length if quoted || !character.match?(/\s/)
+          end
+        end
+        value[0, significant]
+      end
+
+      def xdg_config_home
+        value = ENV["XDG_CONFIG_HOME"]
+        !value || value.empty? ? File.join(Dir.home, ".config") : value
+      end
+
+      def repository_exclude_file(root)
+        git_dirs = repository_git_dirs(root)
+        File.join(git_dirs[1], "info", "exclude") if git_dirs
+      end
+
+      def repository_git_dirs(root)
+        git_dir = File.join(root, ".git")
+        if File.file?(git_dir)
+          value = File.read(git_dir).strip
+          return unless value.start_with?("gitdir: ")
+
+          git_dir = File.expand_path(value.delete_prefix("gitdir: "), root)
+        end
+        return unless File.directory?(git_dir)
 
-        local = rule.base.empty? ? path : path[(rule.base.length + 1)..]
-        ignored = !rule.negated if rule.expression.match?(local)
+        common = File.join(git_dir, "commondir")
+        common_dir = File.file?(common) ? File.expand_path(File.read(common).strip, git_dir) : git_dir
+        [git_dir, common_dir]
       end
-      ignored
     end
 
     private

data/lib/thuban/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Thuban
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/sig/thuban.rbs

@@ -26,6 +26,20 @@ module Thuban
     def self.new: (path: String, oid: String, mode: Integer) -> instance
   end
 
+  class IgnoreMatcher
+    class Rule < Struct[untyped]
+      attr_accessor base: String
+      attr_accessor expression: Regexp
+      attr_accessor negated: bool
+      attr_accessor directory: bool
+      def self.new: (?base: String, ?expression: Regexp, ?negated: bool, ?directory: bool) -> instance
+    end
+    def self.load: (String root, ?extra_files: Array[String], ?global: bool) -> IgnoreMatcher
+    def initialize: (?Array[Rule] rules) -> void
+    def add: (String source, ?base: String) -> IgnoreMatcher
+    def ignored?: (String path, ?directory: bool) -> bool
+  end
+
   class Repository
     attr_reader root: String?
     attr_reader git_dir: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thuban
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -68,7 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A pure Ruby Git repository reader
 test_files: []