Agate

Crystal bindings to libgit2, inspired by Rugged.

Prerequisites

• Crystal >= 1.13.0
• libgit2 >= 1.7.2 (>= 1.9 recommended)

Install libgit2 via your package manager:

# macOS
brew install libgit2

# Alpine
apk add libgit2-dev

# Ubuntu / Debian
apt-get install libgit2-dev

# FreeBSD
pkg install libgit2

Installation

Add the dependency to your shard.yml:

dependencies:
  agate:
    gitlab: bjjb/agate

Then run shards install.

Note: shards install does not install libgit2 itself — you must install it via your system package manager (see Prerequisites above).

Usage

require "agate"

# Open an existing repository
repo = Agate::Repository.open("/path/to/repo")

# Initialize a new repository
repo = Agate::Repository.init("/path/to/new/repo") do |opts|
  opts.initial_head = "main"
  opts.mkpath = true
end

# Read HEAD
commit = repo.last_commit
commit.message  # => "Initial commit\n"
commit.author   # => Agate::Signature(@name="...", @email="...")

# Stage and commit
index = repo.index
index.add("README.md")
index.write
tree = Agate::Tree.lookup(repo, index.write_tree)
sig = Agate::Signature.now("Name", "email@example.com")
Agate::Commit.create(repo, "Add README", tree, sig, sig, [commit])

# Diff
diff = commit.diff(repo)
diff.patch  # => "diff --git a/..."

# Clone
cloned = Agate::Repository.clone_at("https://gitlab.com/user/repo.git", "/tmp/repo")

# Branches, tags, remotes
repo.branches.each { |b| puts b.name }
repo.tags.each { |t| puts t.name }
repo.remotes.each { |r| puts "#{r.name}: #{r.url}" }

API Documentation

Full API docs are available at crystaldoc.info.

Contributing

See src/README.md for the source code style guide and spec/README.md for testing conventions.

crystal tool format   # format code
./bin/ameba           # run linter
crystal spec          # run tests

See BUILDING.md for Docker-based cross-platform testing.

License

MIT — Copyright (c) 2025 JJ Buckley