girt

girt is an experimental Rust library for applications that work with Git repositories. It is dual-licensed under MIT and Apache-2.0.

Status

girt can open SHA-1 and SHA-256 repositories and work with their objects, references, and indexes. It also provides history queries and explicit local, HTTP, and SSH transfer workflows. The API may change. The girt command-line tool exposes the library for inspection and comparison with Git.

Raw status and checkout run on macOS/Linux and do not apply Git's attribute, filter, or EOL transformations. Native local transfer requires callers to exclude external GC/pruning and worktree/HEAD changes through publication. Inspect partial publication before retrying. The published API documentation describes public contracts; compatibility evidence records tested boundaries and provenance.

First use

Add girt = "0.8" to your dependencies (Rust 1.97.1 or newer). This small example computes a Git blob identity without opening a repository:

use girt::{ObjectFormat, ObjectKind};

let id = ObjectFormat::Sha1.hash_object(ObjectKind::Blob, b"hello");
assert_eq!(id.to_string(), "b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0");

Run a blob write and read in a disposable object directory:

cargo run --example loose_blob

The example prints the object ID and removes its temporary directory when it exits. To read an existing repository without changing it, run cargo run --example open_repository -- /path/to/repo <blob-id>. Run cargo doc --open to build the API documentation locally, or read the published API documentation.

Examples

Run the examples from a source checkout. Each linked guide explains prerequisites, effects, limits, and recovery for the corresponding operation.

Create or inspect a repository: Run cargo run --example init_repository, then read repository layouts and shallow history.
Write and read objects: Run cargo run --example loose_commit, then use cargo run --example packed_repository -- /path/to/repo <object-id> to inspect an existing repository. See the API documentation for object and pack APIs.
Edit refs with explicit history: Run cargo run --example reference_transaction and read conditional references and reflogs, including partial failure recovery.
Resolve or edit configuration: Run cargo run --example config or cargo run --example edit_config; see layered configuration.
Fetch, clone, or push: Start with fetch_remote, clone_repository, or push_local in examples/; see transfer scope and evidence.
Inspect and update a working tree: Run cargo run --example status or cargo run --example checkout; read the working-tree guide for preconditions and failure recovery.

For HTTP, enable http and start with cargo run --features http --example http_local; see HTTP setup and contracts. For SSH on macOS/Linux, enable ssh and start with cargo run --features ssh --example ssh_local; its loopback fixture needs sshd and temporary keys. See SSH setup and contracts. The tracing feature and its operation guide are optional.

Contributing

See CONTRIBUTING.md for setup, checks, compatibility testing, and contribution guidance.

License