Thuban
A pure Ruby Git implementation for local repositories and remote transfers.
Website · User Guide · Features · Installation · Quick start
Thuban lets Ruby applications inspect Git history, stage and commit changes, and transfer objects and refs with remotes. Local repository operations read and write Git data directly, without invoking the Git executable. It uses Porrima for line matching in blame and for composing diffs in your application.
Features
- Read loose and packed objects, including deltas, refs, commits, trees, and blobs.
- Inspect the index, staged and worktree changes, ignored paths, and line history across renames.
- Write objects, stage files, create commits, and update refs and reflogs with locks and old-OID checks.
- Check out branches, reset, cherry-pick, revert, resolve index conflicts, and stash changes.
- Fetch and push local, smart HTTP, and SSH remotes; pull fast-forward updates.
- Use Basic, Bearer, callback, or Git credential helper authentication for HTTP.
- Fetch shallow or blobless history and report transfer progress with cancellation support.
- Write interoperable delta-free packfiles and work with linked worktrees and packed refs.
Installation
Add Thuban to your Gemfile:
gem "thuban", "~> 0.6.0"Then run bundle install. To install it directly:
gem install thubanThuban requires Ruby 3.1 or newer and supports SHA-1 Git repositories.
Local read and write operations need no Git executable. Local remote transfers
need git-upload-pack and git-receive-pack; SSH remotes need the system
ssh client, and Git credential helpers need git. Smart HTTP transfers use
Ruby's standard library.
Quick start
Run this from an existing Git worktree:
require "thuban"
repo = Thuban::Repository.new(Dir.pwd)
puts repo.branch
puts repo.head
repo.status.each do |entry|
puts "#{entry.code} #{entry.path}"
end
repo.each_commit(limit: 10).each do |commit|
puts "#{commit.oid[0, 7]} #{commit.message.lines.first.to_s.chomp}"
endRepository discovery walks up from the supplied directory. Status codes use
two columns for index and worktree changes, such as M for an unstaged
modification or ?? for an untracked file. History reads require a positive
limit.
Usage
Read a committed file, the index version, or its current worktree content:
repo.blob("README.md")
repo.blob("README.md", reference: "main")
repo.staged_blob("README.md")
repo.worktree_content("README.md")
repo.blame("README.md")Stage an existing regular file, then commit the index:
path = "README.md"
absolute = repo.worktree_path(path)
stat = File.stat(absolute)
mode = (stat.mode & 0o100).positive? ? 0o100755 : 0o100644
index = repo.index
index.stage(path, repo.write_blob(File.binread(absolute)), mode, stat: stat)
index.write
oid = repo.commit!(message: "Update README", author: repo.signature)
puts oidrepo.signature reads the author environment variables, then user.name and
user.email from Git configuration. Set an identity before committing. The
writing guide also covers
amending commits, restoring index entries, and resolving conflicts.
For a repository with an origin remote:
repo.fetch("origin")
repo.push("origin", refspecs: "refs/heads/main:refs/heads/main")
repo.pull("origin", branch: "main")Fetch updates configured remote-tracking refs. Push requires explicit refspecs and supports leases and atomic updates. Pull requires a clean tracked worktree and applies only fast-forward updates. See remote transfers for authentication, shallow fetches, SSH options, progress, and cancellation.
Scope and limits
Thuban is a library for existing repositories. It does not expose init,
clone, a command-line interface, or a general merge operation. SHA-256
repositories, submodule checkout, automatic retrieval of omitted promisor
objects, and pack delta generation are outside the current scope.
Worktree operations reject unsupported submodules and file collisions. Supported index and pack formats are covered by the test suite. See the limits and error handling guide before integrating write or transfer operations.
Documentation
- User Guide
- Repository data and status
- Writing and conflict resolution
- Remote transfers and authentication
- Development
- Architecture decisions
- Type signatures
- Changelog
Development
bundle install
bundle exec rake
ruby tools/check_isolation.rb
bundle exec rbs -I sig -r porrima validate
gem build --strict thuban.gemspecBug reports and pull requests are welcome on GitHub.
License
Thuban is released under the MIT License.