git2dart

Idiomatic Dart and Flutter bindings for libgit2.

git2dart provides a null-safe Dart API for working with Git repositories while delegating Git operations to libgit2 through FFI. It is intended for Dart CLIs, desktop Flutter apps, and mobile Flutter apps that need repository access without shelling out to the git executable.

Start Here

Goal	Next step
Add git2dart to an app	Install the package
Verify the API quickly	Run the quick start or open the complete example
Explore a full Flutter demo	Open the git2dart_examples app
Build a mobile Flutter app	Read mobile initialization, then the Android or iOS guide
Find a specific API	Use the documentation index
Contribute to the package	Read development and contributing

Installation

Add git2dart to your pubspec.yaml:

dependencies:
  git2dart: ^0.5.2

Install dependencies:

flutter pub get

For local development against this repository, use a path dependency:

dependencies:
  git2dart:
    path: ../git2dart

Quick Start

import 'dart:io';

import 'package:git2dart/git2dart.dart';

Future<void> main() async {
  print('libgit2 ${Libgit2.version}');

  final directory = await Directory.systemTemp.createTemp('git2dart-example');
  final repo = Repository.init(path: directory.path);

  final oid = Blob.create(repo: repo, content: 'Hello from git2dart\n');
  final blob = Blob.lookup(repo: repo, oid: oid);

  print('Repository: ${repo.path}');
  print('Blob: ${blob.oid.sha}');
  print(blob.content);

  blob.free();
  repo.free();
  await directory.delete(recursive: true);
}

The example application shows a longer runnable flow. For a full multi-platform Flutter showcase, see the git2dart_examples app.

Most wrapper objects are backed by native libgit2 resources. Finalizers provide a safety net, but long-running tools and apps should call free() when they are done with repositories, objects, streams, iterators, and other native-backed values.

Mobile Initialization

Flutter apps on Android and iOS should initialize platform support before using repository, remote, credential, or certificate APIs:

import 'package:flutter/widgets.dart';
import 'package:git2dart/git2dart.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await PlatformSpecific.initialize();
  runApp(const MyApp());
}

Platform-specific setup:

• Android setup
• iOS setup

Use app-private storage for repositories on mobile platforms.

Documentation

Start with the documentation index, or jump directly to common API areas:

• Repository
• Git objects and Oid
• Working tree and index
• Remotes and callbacks
• Certificates
• Shared enums and options
• Error handling

The tests in test/ are the source of truth for additional usage scenarios and edge cases.

Platform Support

Platform	Support	Notes
Windows	Supported	64-bit desktop.
Linux	Supported	64-bit desktop.
macOS	Supported	64-bit desktop.
Android	Supported	Flutter apps with arm64-v8a and x86_64.
iOS	Supported	Flutter apps through CocoaPods integration.

Minimum SDK versions:

• Dart SDK >=3.7.2 <4.0.0
• Flutter >=3.29.3

Version 0.5.2 depends on git2dart_binaries >=1.11.4 <1.12.0. The companion package provides prebuilt libgit2 artifacts and generated FFI bindings, so normal git2dart development does not regenerate bindings in this repository.

Features

• Repository lifecycle APIs: init, open, clone, discover, bare repositories, worktrees, and repository state checks.
• Git object APIs for blobs, commits, trees, tags, object databases, object IDs, and streaming blob writes.
• Working tree and index APIs for checkout, status, diff, patch, stash, ignore rules, pathspec matching, and index conflict handling.
• Reference and remote APIs for branches, tags, reflogs, remotes, fetch, prune, refspec matching, callbacks, credentials, and certificates.
• Higher-level Git operations including merge, rebase, reset, revert, blame, describe, notes, pack building, and submodules.
• Prebuilt libgit2 binaries and generated FFI bindings through git2dart_binaries.

Native Dependencies

git2dart uses prebuilt libgit2 binaries, but some platforms still require native TLS or runtime libraries to be present.

Linux

sudo apt-get install libssl-dev libpcre3

On non-Debian distributions, the bundled native libraries may look for Debian-style PCRE library names. If loading fails with libpcre.so.3 or libpcreposix.so.3, create distribution-appropriate compatibility symlinks.

macOS

brew install openssl

Windows

choco install openssl -y

When running tests on Windows, ensure the git2dart_binaries directory that contains libgit2.dll is on PATH.

Development

Install project dependencies:

flutter pub get

Run the standard checks:

dart format . --set-exit-if-changed
flutter analyze
flutter test

If Flutter is not installed on the machine, use scripts/install_flutter.sh.

Contributing

Issues and pull requests are welcome at DartGit-dev/git2dart.

Before opening a pull request:

• Add or update documentation for public API changes.
• Add positive and negative tests for new public API behavior.
• Run dart format . --set-exit-if-changed, flutter analyze, and flutter test.
• Keep code, comments, documentation, issue titles, pull request titles, branch names, and commit messages in English.

License

git2dart is released under the MIT License. See LICENSE for details.