nanogit is a lightweight, cloud-native Git implementation designed for applications that need efficient Git operations over HTTPS without the complexity and resource overhead of traditional Git implementations.

• HTTPS-only Git operations - Works with any Git service supporting Smart HTTP Protocol v2 (GitHub, GitLab, Bitbucket, etc.), eliminating the need for SSH key management in cloud environments

• Stateless architecture - No local .git directory dependency, making it perfect for serverless functions, containers, and microservices where persistent local state isn't available or desired

• Memory-optimized design - Streaming packfile operations and configurable writing modes minimize memory usage, crucial for bulk operations and memory-constrained environments

• Flexible storage architecture - Pluggable object storage and configurable writing modes allow optimization for different deployment patterns, from high-performance in-memory operations to memory-efficient disk-based processing

• Cloud-native authentication - Built-in support for Basic Auth and API tokens, designed for automated workflows and CI/CD systems without interactive authentication

• Essential Git operations - Focused on core functionality (read/write objects, commit operations, diffing) without the complexity of full Git implementations, reducing attack surface and resource requirements

• High performance - Significantly faster than traditional Git implementations for common cloud operations, with up to 300x speed improvements for certain scenarios

The following features are explicitly not supported:

• git:// and Git-over-SSH protocols
• File protocol (local Git operations)
• Commit signing and signature verification
• Full Git clones
• Git hooks
• Git configuration management
• Direct .git directory access
• "Dumb" servers
• Complex permissions (all objects use mode 0644)

While go-git is a mature Git implementation, nanogit is designed for cloud-native, multitenant environments requiring minimal, stateless operations.

Choose nanogit for lightweight cloud services requiring stateless operations and minimal resources. Use go-git when you need full Git functionality, local operations, or advanced features.

This are some of the performance differences between nanogit and go-git in some of the measured scenarios:

For detailed performance metrics, see the latest performance report and performance analysis.

• Go 1.24 or later.
• Git (for development)

go get github.com/grafana/nanogit

// Create client with authentication
client, err := nanogit.NewHTTPClient(
    "https://github.com/user/repo.git",
    options.WithBasicAuth("username", "token"),
)

// Get main branch and create staged writer
ref, err := client.GetRef(ctx, "refs/heads/main")
writer, err := client.NewStagedWriter(ctx, ref)

// Create and update files
writer.CreateBlob(ctx, "docs/new-feature.md", []byte("# New Feature"))
writer.UpdateBlob(ctx, "README.md", []byte("Updated content"))

// Commit changes with proper author/committer info
author := nanogit.Author{
    Name:  "John Doe",
    Email: "john@example.com",
    Time:  time.Now(),
}
committer := nanogit.Committer{
    Name:  "Deploy Bot",
    Email: "deploy@example.com",
    Time:  time.Now(),
}

commit, err := writer.Commit(ctx, "Add feature and update docs", author, committer)
writer.Push(ctx)

nanogit provides flexible writing modes to optimize memory usage during write operations:

// Auto mode (default) - smart memory/disk switching
writer, err := client.NewStagedWriter(ctx, ref)

// Memory mode - maximum performance
writer, err := client.NewStagedWriter(ctx, ref, nanogit.WithMemoryStorage())

// Disk mode - minimal memory usage for bulk operations
writer, err := client.NewStagedWriter(ctx, ref, nanogit.WithDiskStorage())

For detailed information about writing modes, performance characteristics, and use cases, see Storage Architecture Documentation.

nanogit features a flexible two-layer storage architecture that separates concerns and allows independent optimization:

1. Writing modes: Control temporary storage during packfile creation (memory/disk/auto)
2. Object storage: Handle long-term caching and retrieval of Git objects (pluggable backends)

nanogit provides context-based object storage with pluggable backends. The default in-memory implementation is optimized for stateless operations, but you can implement custom backends for persistent caching:

// Custom storage example
ctx = storage.ToContext(ctx, myRedisStorage)
client, err := nanogit.NewHTTPClient(repo, options...)

This enables sharing Git object cache across multiple repositories, persistent caching across service restarts, and optimization for specific deployment patterns.

For detailed information about storage architecture, writing modes, and custom implementations, see Storage Architecture Documentation.

nanogit includes generated mocks for easy unit testing. The mocks are generated using counterfeiter and provide comprehensive test doubles for both the Client and StagedWriter interfaces.

For detailed testing examples and instructions, see CONTRIBUTING.md. You can also find complete working examples in mocks/example_test.go.

We welcome contributions! Please see our 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. By participating, you are expected to uphold this code.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

This project is currently in active development. While it's open source, it's important to note that it was initially created as part of a hackathon. We're working to make it production-ready, but please use it with appropriate caution.

Want to learn how Git works? The following resources are useful:

• Git on the Server - The Protocols
• Git Protocol v2
• Pack Protocol
• Git HTTP Backend
• HTTP Protocol
• Git Protocol HTTP
• Git Protocol v2
• Git Protocol Pack
• Git Protocol Common

If you find a security vulnerability, please report it to security@grafana.com. For more information, see our Security Policy.

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

• The Grafana team for their support and guidance
• The open source community for their valuable feedback and contributions