Thuban User Guide

Read Git data, write commits, and transfer objects and refs from Ruby.

Thuban is a library for existing SHA-1 Git repositories. Local repository operations work directly with Git files. The examples below use repo for the repository opened in Getting started; branch, tag, and file names must exist in your repository.

Getting started

You need Ruby 3.1 or newer. Add Thuban to your Gemfile and run bundle install:

gem "thuban", "~> 0.6.0"

Or install the gem directly with gem install thuban. Save the following code as inspect_repo.rb inside an existing Git worktree and run bundle exec ruby inspect_repo.rb (or ruby inspect_repo.rb after a direct gem installation):

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}"
end

Discovery walks up from the supplied directory or file path. Normal worktrees, linked worktrees, and bare repositories can be opened. repo.root is the worktree path, or nil for a bare repository; repo.git_dir and repo.common_dir identify Git's metadata directories. Use bare repositories for object and ref operations, rather than worktree status or file access.

Thuban does not provide init or clone. Create or clone a repository with Git before opening it. Local reads and writes need no Git executable. Local remote transfers use Git service executables, and SSH and credential helpers have their own prerequisites.

Read repository data

repo.refs                      # Full ref names => object IDs
repo.branches                  # Local branch names
repo.resolve("main")           # Full SHA-1 object ID, or nil
repo.commit                    # HEAD as a Thuban::Commit, or nil
repo.tree                      # Paths => Thuban::TreeEntry values
repo.blob("README.md")          # Committed bytes, or nil
repo.staged_blob("README.md")   # Index bytes, or nil
repo.worktree_content("README.md")
repo.index                     # Thuban::Index

revision = repo.commit("main")
puts revision.message if revision
repo.tree("main")
repo.blob("README.md", reference: "main")

Read methods accept branch names, tags, full ref names, or complete 40-character SHA-1 object IDs. Annotated tags are peeled when reading commits. Short object IDs and revision expressions such as HEAD~1 are not supported; use repo.commit.parents.first to read the first parent.

A commit exposes oid, tree, parents, author, committer, and message. A tree entry exposes path, oid, and mode. For raw object data, repo.object(oid) returns a [type, data] pair.

repo.each_commit("main", limit: 100).each do |commit|
  puts "#{commit.oid} #{commit.message.lines.first.to_s.chomp}"
end

each_commit returns an Enumerator without a block. It visits the selected tip and then its parents in deterministic parent order, yields merge ancestors once, and requires a positive integer limit. The walk is not sorted by commit timestamp.

Inspect status and line history

Each status entry has a path, an index column, a worktree column, and their combined code. Clean files are omitted. Status honors core.filemode; repo.filemode? returns the effective setting.

Common status codes
CodeMeaning
 MModified in the worktree, with no staged change
M Modification staged in the index
A Addition staged in the index
 DTracked file deleted from the worktree
??Untracked file
UUUnresolved conflict with base, ours, and theirs entries

For blame, Thuban follows committed line history across changes and renames:

repo.blame("README.md").each do |line|
  puts "#{line.line}: #{line.commit[0, 7]} #{line.text}"
end

Each line also exposes author, original_line, and the original path. Pass reference: to blame another revision. Line matching uses Porrima by default; differ: accepts a compatible implementation.

Compare and restore changes

Thuban exposes the three versions of a file for comparison. Compose them with Porrima, which is already a Thuban dependency:

before = repo.staged_blob("README.md").to_s
after = repo.worktree_content("README.md").to_s
diff = Porrima.diff(before, after)

if (hunk = diff.hunks.first)
  repo.write("README.md", Porrima.revert(after, hunk))
end

This compares the index with the worktree and restores the first unstaged hunk. Compare repo.blob(path) with repo.staged_blob(path) for staged changes. Thuban has no separate diff algorithm.

repo.write(path, content) replaces an existing regular file atomically and preserves its permissions. It rejects symlinks and unsafe paths. It does not create a missing file; create new files explicitly before staging them.

Stage files and create commits

Use a repository-relative path and read from the repository's worktree. This example stages an existing regular file while preserving its executable bit:

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 oid

index.stage changes the in-memory index; index.write publishes it using index.lock. commit! writes a tree from the entire index, creates a commit, and advances HEAD. It rejects unresolved index conflicts. The worktree is not staged automatically.

Set the author and committer

repo.signature(role: :author) reads GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL, then user.name and user.email from Git configuration. Use role: :committer for the matching committer variables. Missing or invalid identity values raise ArgumentError. The signature uses the current time and UTC offset.

Pass a signature explicitly when your application manages identities:

author = Thuban::Signature.new(
  name: "Example Author", email: "author@example.com", time: Time.now
)
repo.commit!(message: "Update README", author: author)

Without a separate committer:, commit! uses the author signature as the committer. To amend while preserving the original author and author timestamp:

original = repo.commit
repo.commit!(
  message: "Update README",
  author: original.signature(role: :author),
  committer: repo.signature(role: :committer),
  amend: true
)

Restore or remove index entries

index.unstage(path) removes the stage-zero entry; it does not restore the HEAD version of a tracked file. To undo a staged change, put the HEAD entry back, or remove the entry if HEAD does not contain the path:

path = "README.md"
index = repo.index
if (entry = repo.tree[path])
  index.stage(path, entry.oid, entry.mode)
else
  index.unstage(path)
end
index.write

To stage a deletion, use index.remove(path) and index.write. This removes index entries, including conflict stages, without deleting a worktree file. Optional index extensions are retained as raw bytes; entry-dependent caches are invalidated after mutation.

Resolve existing index conflicts

repo.conflicts captures each conflicted path, its base/ours/theirs entries, HEAD, the index checksum, and worktree state. Resolve that captured snapshot with one choice:

conflict = repo.conflicts.first
if conflict
  repo.resolve_conflict(conflict, choice: :ours)
end

Other choices are :theirs, :both, and :manual. For manual resolution, pass the edited content and mode:

conflict = repo.conflicts.first
if conflict
  repo.resolve_conflict(conflict,
    choice: :manual, content: "Resolved text\n", mode: 0o100644)
end

:ours and :theirs can select a deleted side. :both performs a text three-way merge and places ours before theirs in remaining conflicting regions. Binary and symlink conflicts support selecting a side or manual replacement; they cannot use :both.

HEAD and the index are locked, and the captured worktree is revalidated at write boundaries. A detected change raises Thuban::RefLockError before publishing the resolution. Capture a fresh conflict before retrying. Uncoordinated writes racing the final atomic replacement need external coordination. Other conflicted paths remain unresolved.

For index-only changes, index.conflicts exposes stage 1/2/3 entries and index.resolve(path, oid, mode) replaces them with a stage-zero entry. Write the index explicitly; this lower-level API does not update the worktree.

Update refs and check out branches

Capture the expected object ID before updating a ref. This guards against overwriting a concurrent change:

previous = repo.head
repo.create_branch("topic", previous)
repo.update_ref("refs/heads/topic", repo.head,
  old_oid: previous, message: "advance topic")
repo.reflog("topic") # Raw Git reflog records

repo.checkout("topic")

Ref mutations use .lock files. A held lock or mismatched old_oid: raises Thuban::RefLockError. Loose updates override packed refs, and deletion removes both forms. repo.delete_branch(name) and repo.delete_ref(name, old_oid: expected) provide deletion APIs.

Checkout requires a clean index and tracked worktree. Untracked files remain unless they would collide with the target tree; ignored collisions also abort. Submodule checkout is unsupported. Save, commit, or stash tracked changes before switching branches.

Change history and stash work

Find a merge base or apply individual non-merge commits:

base = repo.merge_base("main", "topic")
picked = repo.cherry_pick("topic")
repo.revert(picked)

Cherry-pick and revert require a clean tracked worktree and reject commits with more than one parent. They merge non-overlapping text changes and report remaining conflicts before changing files. They do not start an interactive conflict-resolution session.

Reset accepts a branch, tag, or full commit ID:

repo.reset("main", mode: :mixed)
Reset modes
ModeEffect
:softMove HEAD; retain index and worktree content
:mixedMove HEAD and replace the index; retain worktree content
:hardMove HEAD and replace the index and tracked worktree content

Hard reset discards tracked worktree changes. Save any content you need first. Collision checks protect untracked paths but do not preserve modified tracked files.

stash = repo.stash_push(message: "before refactor", include_untracked: true)
repo.stash_list # Newest first, as Thuban::Commit values
repo.stash_pop if stash

Stash uses Git's standard commit and reflog layout and retains staged state. stash_push returns nil when there is nothing to save. Untracked files are included only with include_untracked: true. stash_pop(0) restores the newest entry and requires a clean tracked worktree; conflicts or collisions prevent applying it.

Fetch, push, and pull

For a normal [remote "origin"] configuration, Thuban reads its URL and fetch refspecs. Fetch imports objects and updates remote-tracking refs without checking out files:

repo.remotes
advertised = repo.fetch("origin")
repo.blob("README.md", reference: "refs/remotes/origin/main")

Remote names, direct paths, file:// URLs, HTTP(S), and SSH URLs are accepted. Direct URLs or paths do not create remote-tracking refs unless you provide destination refspecs. Relative local paths are resolved from the repository's worktree or common directory.

Smart HTTP discovery prefers protocol v2 and falls back to v0. HTTP transfers use Ruby's standard library. Local transfers invoke git-upload-pack or git-receive-pack, which must be on PATH. SSH needs a system SSH client and the Git service on the server.

Fetch shallow or blobless history

repo.fetch("origin", depth: 1)
repo.fetch("origin", filter: "blob:none")

depth: accepts a positive 32-bit integer; filter: currently accepts only "blob:none". The server must advertise the requested capability. Shallow boundaries are maintained atomically in Git's shallow file.

Configured partial fetches set remote.<name>.promisor and remote.<name>.partialclonefilter so Git can retrieve omitted objects later. Thuban itself does not download them on demand: reading an omitted blob raises KeyError.

Push explicit refspecs

repo.push("origin", refspecs: "refs/heads/main:refs/heads/main")

Normal updates must be fast-forward. For a guarded rewrite, pass the expected remote object ID as a lease. Refresh it deliberately before the operation:

advertised = repo.fetch("origin")
expected = advertised.find { |ref| ref.name == "refs/heads/topic" }&.oid
raise "Remote topic branch is missing" unless expected

repo.push("origin", refspecs: "refs/heads/topic:refs/heads/topic",
  lease: expected)

Use force: true only for an unconditional rewrite. To update multiple refs atomically, request atomic: true; the server must support it:

repo.push("origin", refspecs: [
  "refs/heads/main:refs/heads/main",
  "refs/tags/v1:refs/tags/v1"
], atomic: true)

An empty source refspec, such as :refs/heads/topic, deletes the remote ref.

Pull fast-forward changes

repo.pull("origin", branch: "main")

Pull fetches and advances the current branch, index, and worktree only when the named remote branch is a fast-forward. It rejects tracked changes, detached HEADs, bare repositories, and untracked collisions. If the fast-forward cannot be applied, fetched objects and tracking refs remain available. General merge pulls and ff_only: false are unsupported.

Use a connection directly

Keep the connection open while discovering and fetching refs, and close it in an ensure block:

connection = Thuban::Remote.open("https://example.com/project.git")
begin
  refs = connection.refs
  refs.each { |ref| puts "#{ref.oid} #{ref.name}" }
  wanted = refs.find { |ref| ref.name == "refs/heads/main" }&.oid
  if wanted
    connection.fetch(repo, wants: [wanted], haves: repo.refs.values.compact)
  end
ensure
  connection.close
end

Remote refs expose name, oid, symref_target, and peeled. Low-level fetch returns received object IDs and does not update tracking refs. connection.push(repo, updates) accepts [ref, old_oid, new_oid] updates; an explicit old ID is an optimistic lease, while nil uses the advertised value.

Authenticate HTTP and configure SSH

Pass credential objects to high-level operations or Thuban::Remote.open. Load secrets from your application's configuration or environment:

credentials = Thuban::Remote::Credentials.static(
  username: ENV.fetch("GIT_USERNAME"),
  password: ENV.fetch("GIT_PASSWORD")
)
repo.fetch("origin", credentials: credentials)

token = Thuban::Remote::Credentials.bearer(token: ENV.fetch("GIT_TOKEN"))
repo.fetch("origin", credentials: token)

A callback can choose or refresh credentials at runtime. It receives the remote URL without embedded user information and returns another credential object. In this example, token_for is supplied by your application:

credentials = Thuban::Remote::Credentials.callback do |url|
  Thuban::Remote::Credentials.bearer(token: token_for(url))
end

Use the configured Git credential helpers, or select a helper by name:

credentials = Thuban::Remote::Credentials.helper
repo.fetch("origin", credentials: credentials)

credentials = Thuban::Remote::Credentials.helper("store --file=/secure/path")

Helper lookup invokes git credential fill with terminal prompting disabled and is bounded by the connection timeout. Credential objects redact their inspection output. Transport errors omit credentials, helper output, response bodies, and remote URLs. URL-embedded HTTP credentials and redirects are rejected to prevent forwarding authorization to another origin.

SSH clients and keys

Both ssh://git@example.com/project.git and git@example.com:project.git are supported. Use normal SSH keys, agents, and configuration; passwords in SSH URLs are unsupported.

repo.fetch("git@example.com:project.git",
  ssh: ["ssh", "-F", "/safe/config"], timeout: 30)

ssh: accepts an argument array or safely parsed command string. When omitted, Thuban parses GIT_SSH_COMMAND or uses ssh. It invokes the client without a local shell, enables batch mode, validates address syntax, and discards stderr. Configure host trust and key access before starting a transfer. SSH uses the same shallow, partial, progress, and pack validation paths as HTTP.

Report progress and cancel transfers

High-level fetch, push, and pull accept credentials:, ssh:, timeout:, and a zero-argument cancelled: callback. Set the cancellation flag from your application when the user requests it:

cancelled = false
repo.fetch("origin", timeout: 15, cancelled: -> { cancelled }) do |event|
  warn "#{event.phase}: #{event.current}/#{event.total} (#{event.bytes} bytes)"
end

Progress values expose phase, current, total, and bytes; fields can be nil when not applicable. Pack event bytes are cumulative; remote event bytes describe the current sideband message. Cancellation closes a blocked transport and raises Thuban::Cancelled.

A cancelled push may already have been applied on the server. Refresh remote refs before deciding whether to retry; cancellation does not roll back a remote update.

Read and write packfiles

Thuban::Pack.write accepts [type, data] pairs, reports completed objects to an optional block, and returns the hexadecimal pack checksum:

objects = [["blob", "hello from Thuban\n"]]
File.open("out.pack", "wb") do |file|
  checksum = Thuban::Pack.write(file, objects) do |current, total|
    warn "#{current}/#{total}"
  end
  puts checksum
end

The PACK v2 stream stores complete compressed objects without generating deltas. Git's index-pack and verify-pack can consume it. To import a received pack into the local object database:

File.open("out.pack", "rb") do |file|
  received_oids = Thuban::Pack.read_stream(file, repo.odb)
  puts received_oids
end

Pack ingestion verifies checksums, supports offset and reference deltas, and bounds byte counts, object counts, and expanded sizes. Loose and packed object reads share repo.odb.

Match ignored paths

Load global excludes, .git/info/exclude, and nested .gitignore files. Thuban also reads nested .ignore files for editor compatibility:

ignore = Thuban::IgnoreMatcher.load(repo.root)
ignore.ignored?("tmp/output.log")
ignore.ignored?("build", directory: true)

ignore = Thuban::IgnoreMatcher.load(repo.root,
  extra_files: [".customignore"], global: false)

extra_files: accepts root-relative or absolute paths and applies them last. global: false skips core.excludesFile and the default global ignore file. Configuration is read from system, XDG, home, repository, and enabled worktree files. Included configs, line continuations, and command-scoped overrides are not evaluated.

Scope, limits, and errors

Thuban supports SHA-1 repositories and the index and pack formats covered by its tests. It is not a full replacement for every Git command. General merges, SHA-256 repositories, submodule checkout, automatic retrieval of omitted promisor objects, and pack delta generation are unsupported.

Keep worktree writes inside the opened repository. Paths and symlinks are checked, checkout requires clean tracked state, and worktree-changing history operations reject unsupported submodules and untracked collisions. Atomic replacement and lock files coordinate Git-aware writers; applications must coordinate independent writes to worktree files.

Errors callers should handle
ExceptionTypical cause and response
ArgumentErrorInvalid input, unsupported operation, dirty tracked state, or a collision. Check the request and repository state.
KeyErrorMissing object, including an omitted blob after a partial fetch. Obtain the object before reading it.
Thuban::CorruptObjectInvalid repository data or a corrupt object. Inspect the repository with Git before retrying.
Thuban::RefLockErrorHeld ref lock or a changed ref, index, or conflict snapshot. Refresh state before retrying.
IOErrorA held index lock or I/O failure. Resolve the active writer or storage failure.
Thuban::AuthenticationErrorUnavailable or rejected credentials. Update authentication.
Thuban::TransportErrorProtocol failure, timeout, rejected push, or unsupported server capability. Check the remote and requested operation.
Thuban::CancelledThe caller cancelled a transfer. Refresh remote refs before retrying a push.

AuthenticationError and Cancelled inherit from TransportError. Handle them before a general transport rescue when your application needs different recovery behavior.

Development and documentation

From a source checkout, install dependencies and run the same checks used by CI:

bundle install
bundle exec rake
ruby tools/check_isolation.rb
bundle exec rbs -I sig -r porrima validate
gem build --strict thuban.gemspec

Git is needed for the test fixtures and interoperability checks. Run the optional performance assertions when changing pack writing or SSH transfers:

ruby bench/pack_write.rb --assert
ruby bench/ssh_fetch.rb --assert

The website is plain HTML and CSS in docs/, with no build step. GitHub Pages is configured to publish main's /docs directory. To preview it locally with Python 3:

python3 -m http.server 8000 --directory docs

Open http://localhost:8000/ for the homepage or http://localhost:8000/guide/ for this guide.