Git repositories,
written in Ruby.

Read history, stage files, and create commits from your Ruby application. Work directly with local Git data, then fetch and push objects and refs with remotes.

gem install thuban

Ruby 3.1+ · SHA-1 repositories · MIT License

Inside a repositoryHEAD → main
Git object relationships The main branch points to a commit, which points to a tree and then a blob. The index also points to the blob that stores README.md. refs/heads/main branch reference Commit tree, parents, author Tree 100644 blob README.md Blob README contents Index staged blob + mode

ReadObjects, history, status, and blame

WriteIndex, commits, refs, and reflogs

TransferLocal, smart HTTP, and SSH remotes

ComposeRuby values and Porrima diffs

Work with the repository itself.

Build repository tools around objects, index entries, and refs. Local operations read and write Git data without calling the Git executable.

Inspect objects and history
Read loose and packed objects, resolve branches and tags, walk bounded commit history, and trace lines across renames.
Understand working changes
Compare committed, staged, and worktree content. Read status codes, index conflicts, and nested ignore rules.
Stage and commit
Write blobs and trees, update the index, create or amend commits, and guard ref updates with locks and expected object IDs.
Move through history
Check out clean branches, reset, cherry-pick, revert, and stash staged or worktree changes, with collision checks.
Fetch and push
Use configured remotes or direct URLs. Authenticate HTTP requests, set push leases, and pull fast-forward changes.
Control transfers
Request shallow or blobless history, report bounded progress, cancel blocked transfers, and write interoperable packfiles.

Open your first repository.

Install the gem and run this Ruby code from an existing Git worktree. Thuban discovers the repository, reports changes, and reads recent commits.

Use branch names, tags, or full object IDs for other revisions. The guide covers staging and committing and remote transfers.

Get started
require "thuban"

repo = Thuban::Repository.new(Dir.pwd)
puts repo.branch

repo.status.each do |entry|
  puts "#{entry.code} #{entry.path}"
end

repo.each_commit(limit: 10).each do |commit|
  puts commit.message.lines.first
end

Keep exploring.