ExGitObjectstore

Pure Elixir git object store with pluggable storage backends.

Read, write, and manipulate git objects (blobs, trees, commits, tags), refs, and packfiles without requiring libgit2, the git CLI, or any NIF. All git data is stored through a pluggable storage backend — use the local filesystem, S3, or in-memory storage.

Features

• Git objects — encode, decode, hash, read, and write blobs, trees, commits, and tags
• Refs — branches, tags, HEAD, compare-and-swap updates
• Packfiles — read and write .pack and .idx v2 files, delta resolution
• Three-way merge — recursive tree merge with conflict detection
• Diff engine — Myers diff algorithm with unified diff output and context hunks
• Graph traversal — commit log, merge base (LCA) finding
• Git wire protocol — pkt-line framing, upload-pack, receive-pack
• Pluggable storage — filesystem, S3 (any S3-compatible service), and in-memory backends
• ETS caching — LRU object cache with configurable size limits
• Integrity verification — fsck with full (SHA re-hash) and quick (refs-only) modes

Installation

Add ex_git_objectstore to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_git_objectstore, "~> 0.1.0"}
  ]
end

Quick Start

alias ExGitObjectstore.{Repo, Object}
alias ExGitObjectstore.Object.{Blob, Commit, Tree}

# Create a repo with in-memory storage
repo = %Repo{
  id: "my-repo",
  storage: ExGitObjectstore.Storage.Memory,
  storage_config: %{}
}

# Initialize and write objects
:ok = ExGitObjectstore.init(repo)

{:ok, blob_sha} = Object.write(repo, Blob.from_content("Hello, world!\n"))

{:ok, tree_sha} = Object.write(repo, Tree.new([
  %{mode: "100644", name: "README.md", sha: blob_sha}
]))

{:ok, commit_sha} = Object.write(repo, %Commit{
  tree: tree_sha,
  parents: [],
  author: "Alice <alice@example.com> 1700000000 +0000",
  committer: "Alice <alice@example.com> 1700000000 +0000",
  message: "Initial commit"
})

:ok = ExGitObjectstore.create_branch(repo, "main", commit_sha)

# Read it back
{:ok, {^commit_sha, commit}} = ExGitObjectstore.commit(repo, "main")
{:ok, tree} = ExGitObjectstore.tree(repo, "main")
{:ok, content} = ExGitObjectstore.blob(repo, blob_sha)

Storage Backends

Filesystem

repo = %Repo{
  id: "my-repo",
  storage: ExGitObjectstore.Storage.Filesystem,
  storage_config: %{root: "/var/git/repos/my-repo"}
}

Uses the standard git loose object layout with atomic writes (temp file + rename) and lock-file compare-and-swap for ref updates.

S3

repo = %Repo{
  id: "my-repo",
  storage: ExGitObjectstore.Storage.S3,
  storage_config: %{
    bucket: "my-git-bucket",
    prefix: "repos/my-repo",
    ex_aws_config: [
      access_key_id: "...",
      secret_access_key: "...",
      region: "us-east-1"
    ]
  }
}

Works with AWS S3, MinIO, or any S3-compatible service. Handles pagination for repositories with many objects.

Memory

repo = %Repo{
  id: "my-repo",
  storage: ExGitObjectstore.Storage.Memory,
  storage_config: %{}
}

Stores everything in an ETS table. Useful for testing and ephemeral operations.

Git protocol v2 capability matrix

UploadPackV2 and ReceivePack are validated against a real git CLI via the integration test suite. The table below lists every capability / sub-argument the protocol v2 spec defines and the current implementation status.

UploadPack

ReceivePack

Known Limitations

• ofs-delta generation — pack writer stores full objects only, no delta compression on the write side.
• Atomic ref updates are validation-based with rollback from a pre-flight snapshot, not a native multi-key storage transaction. A VM crash mid-rollback can leave refs partially applied. Failures are logged via Logger.error and emitted as a [:ex_git_objectstore, :protocol, :receive_pack, :rollback_failed] telemetry event.

License

Copyright 2026 Cole Christensen

Licensed under the Apache License, Version 2.0. See LICENSE for details.