What is nanogit?

nanogit is a lightweight Git client library for Go, built for services that read from and write to Git repositories over HTTPS — with no local clone, no .git directory, and no git binary. It speaks the Git Smart HTTP Protocol v2 directly, so it works with GitHub, GitLab, Bitbucket, Gitea, and any other server that supports protocol v2.

Grafana built nanogit to power Git Sync, which syncs dashboards with tenants' own Git repositories from inside Grafana's multitenant backend — a workload where cloning every repository to disk is not an option. Read the full story in Why nanogit exists.

• Stateless — reads and writes Git objects directly over HTTPS; nothing is persisted locally, so there is no per-repository state to store, clean up, or keep consistent across replicas
• Works with any protocol v2 server — one code path for GitHub, GitLab, Bitbucket, Gitea, and self-hosted servers; token-based auth, no SSH key management
• Essential operations — refs, blobs, trees, commits, diffs, staged writes, and shallow clones with glob-based path filtering
• Memory-efficient — streaming packfile processing and configurable memory/disk/auto writing modes for bulk operations
• Fast — orders of magnitude faster and leaner than a full Git implementation for common server-side operations (benchmarks below)
• Commit signing — sign commits with GPG, SSH, or S/MIME keys
• Pluggable — object storage (caching) and retry policies are injected via context, with sensible defaults

When should I use it?

Use nanogit when your code runs server-side and talks to Git over HTTPS:

• GitOps and as-code services — sync configuration, dashboards, or manifests between your application and users' repositories
• Bots and automation — commit generated files, open changes, or mirror content without shelling out to git
• Multitenant platforms — operate on thousands of repositories without maintaining a checkout per tenant
• Serverless and containers — environments with little or no persistent disk
• CI tooling — fetch only the subpaths you need from large repositories using path-filtered, shallow clones

When should I not use it?

nanogit is deliberately narrow. Reach for the git CLI or go-git instead when you need:

• Local development workflows — working trees, the index, .git directories, or repositories on disk
• Full Git functionality — merges, rebases, blame, hooks, or Git configuration management
• Other transports — SSH, git://, or local file access; nanogit is HTTPS-only
• Protocol v1 or "dumb" HTTP servers — nanogit requires Smart HTTP protocol v2 and does not fall back. Notably, Azure DevOps / Azure Repos only speaks v1 and is not supported. Run nanogit check against a new provider before integrating
• Signature verification — nanogit can sign commits but does not verify signatures
• Fine-grained file permissions — all files are written with mode 0644

See Why Git Protocol v2 Only? for the rationale behind the strictest of these constraints.

How is it different from go-git?

go-git is a mature, full-featured Git implementation. nanogit trades that breadth for a small, stateless core optimized for cloud services:

Feature	nanogit	go-git
Protocol	HTTPS only (Smart HTTP v2)	All protocols
Storage	Stateless; pluggable object storage and writing modes	Local disk operations
Cloning	Shallow, with glob-based path filtering	Full repository clones
Scope	Essential operations only	Full Git functionality
Use case	Cloud services, multitenant backends	General purpose
Resource usage	Minimal footprint	Full Git features

Because it never materializes a full repository, nanogit is dramatically faster and lighter for typical server-side operations. From the benchmark suite comparing both libraries across repository sizes:

Scenario	Speed	Memory usage
CreateFile (XL repo)	306x faster	186x less
UpdateFile (XL repo)	291x faster	178x less
DeleteFile (XL repo)	302x faster	175x less
BulkCreateFiles (1000 files, medium repo)	607x faster	11x less
CompareCommits (XL repo)	60x faster	96x less
GetFlatTree (XL repo)	258x faster	160x less

See the performance analysis for methodology and full results.

Is it production-ready?

Yes. nanogit is the Git engine behind Git Sync in grafana/grafana, reading and writing dashboards across tenants' repositories in production, and the default Git driver in grafana-bench. See who uses nanogit.

Releases follow semantic versioning: the v1 API is stable, and breaking changes only land in major versions. The project is actively developed by Grafana Labs.

Getting started

Install the library (requires Go 1.26+):

go get github.com/grafana/nanogit@latest

Then follow the guides:

• Installation — install nanogit in your project
• Quick Start — read, write, clone, retry, and authenticate in a few minutes
• CLI — terminal-based Git operations for testing and demos
• Server Compatibility — verify your Git server supports nanogit in four CLI commands
• API Reference (GoDoc) — complete API documentation

Guides

Task-focused guides for production use:

• Writing with the StagedWriter — the transactional write model: staging, multi-commit, push, retry semantics
• Authentication — basic auth, raw tokens, and per-provider conventions
• Error Handling — sentinel and typed errors, errors.Is/errors.As patterns
• Commit Signing — GPG, SSH, and S/MIME signatures
• Response Limits — cap response sizes for multitenant safety
• History and Diffs — ListCommits pagination/filtering and CompareCommits

Architecture

Learn about nanogit's design and internals:

• Architecture Overview — core design principles and components
• Storage Backend — pluggable storage and writing modes
• Retry Mechanism — pluggable retry mechanism for robust operations
• Delta Resolution — Git delta handling implementation
• Performance — performance characteristics and benchmarks
• Learn how Git works — pointers to the upstream Git protocol documentation nanogit implements

Testing

nanogit ships the tooling to test code that depends on it:

• Testing Guide — complete guide with patterns and best practices
• gittest Package — integration testing with a real containerized Git server, local repository helpers, and automatic cleanup
• Unit testing — generated mocks for the Client and StagedWriter interfaces

Contributing

We welcome contributions! Please see the Contributing Guide for details on how to submit pull requests, report issues, and set up your development environment. This project follows the Grafana Code of Conduct.

License

This project is licensed under the Apache License 2.0.

Security

If you find a security vulnerability, please report it according to our security policy.

Support

• GitHub Issues: Create an issue
• Community: Grafana Community Forums