git_core #

git_core is a pure Dart Git plumbing library for reading and writing Git repositories, object databases, refs, indexes, packs, and structured local or remote workflows without shelling out to the git CLI.

It is designed as a foundation layer for tools, agents, editors, and other packages that need Git behavior in-process and in Dart.

Status #

This repository is public, but it is still not ready for use.

What it is:

• A pure Dart, platform-neutral Git core
• A structured API around repositories, objects, refs, indexes, packs, and conflict-aware workflows
• Suitable for agentic and application use cases that need deterministic result objects instead of parsing CLI output

What it is not:

• A full drop-in replacement for every git porcelain command
• A hosting server or background Git daemon
• A promise of byte-for-byte CLI parity for every obscure Git edge case

Highlights #

• Loose object, tree, commit, tag, ref, reflog, and index read/write support
• Packfile encode/decode, pack index support, and thin-pack base resolution
• SHA-1 and SHA-256 repository support
• Everyday repository operations such as add(...), commit(...), status(...), lsFiles(...), revParse(...), show(...), diff(...), log(...), checkIgnore(...), and mergeBase(...)
• Worktree mutation helpers including apply(...), branch(...), checkout(...), reset(...), restore(...), stash(...), merge(...), and worktree(...)
• Conflict-aware result models and recovery helpers like mergeContinue(...), mergeAbort(), and applyAbort()
• Remote configuration, tracking branches, and fetch(...), push(...), pull(...), and clone(...) over filesystem, static HTTP, smart HTTP, and SSH transports
• SSH host verification via known_hosts or explicit host fingerprints

Getting Started #

Add the package from pub.flutter-io.cn:

dart pub add git_core

Or declare it in pubspec.yaml:

dependencies:
  git_core: ^0.1.0-dev.1

If you need unreleased commits before the next publish, you can depend on the GitHub repository directly:

dependencies:
  git_core:
    git:
      url: git@github.com:Atrac613/git_core.git

Then import the package:

import 'package:git_core/git_core.dart';

To clone the repository itself for local development:

git clone git@github.com:Atrac613/git_core.git

Quick Start #

import 'dart:convert';

import 'package:git_core/git_core.dart';

Future<void> inspectRepository() async {
  final repo = await GitRepository.discover('/projects/example');
  if (repo == null) return;

  final head = await repo.resolveReferenceObjectId('HEAD');
  final status = await repo.status();
  final log = await repo.log('HEAD', maxCount: 5);
  final diff = await repo.diff(includeUntracked: true);

  print(head?.hex);
  print(status.entries.length);
  print(log.map((entry) => entry.commit.message).join('\n---\n'));
  print(diff.entries.length);
}

Future<void> writeObject() async {
  final object = GitObject.blob(utf8.encode('hello\n'));
  print(object.id().hex);
}

For a runnable inspect-and-print example, see example/basic.dart.

Public API #

The main public surface lives in lib/git_core.dart.

Primary types:

• GitRepository: repository discovery, refs, index, working tree, local workflows, remote sync, recovery helpers, and transport-aware operations
• GitObject, GitObjectId, GitObjectType: object modeling and identity
• GitReference, GitReferenceInfo, GitBranch, GitTag: refs and symbolic ref abstractions
• GitIndex, GitIndexCodec: staged entry modeling and raw index encoding
• GitPack, GitPackCodec, GitPackIndex, GitPackIndexCodec, GitPackResolver: packfile support
• GitDiff*, GitApply*, GitMerge*, GitStatus*, GitStash*, GitFetch*, GitPush*, GitPull*, GitCheckout*, GitReset*, GitRestore*, and GitWorktree*: structured operation result models

Representative repository methods:

• Repository inspection: status(...), lsFiles(...), revParse(...), show(...), diff(...), log(...), reflog(...), checkIgnore(...), mergeBase(...)
• Local updates: add(...), commit(...), apply(...), branch(...), checkout(...), reset(...), restore(...), stash(...), merge(...), worktree(...)
• Recovery: mergeContinue(...), mergeAbort(), applyAbort()
• Remotes and sync: setRemote(...), remote(...), branchTracking(...), fetch(...), push(...), pull(...), pullCurrent(...), clone(...)

Current Scope #

Implemented areas include:

• Repository discovery for bare, worktree, and linked-worktree layouts
• Object database operations for blobs, trees, commits, tags, and packs
• Index parsing and staging behavior with conflict stage preservation
• Structured patch application, 3-way fallback, and merge conflict reporting
• Local branch, checkout, reset, restore, stash, merge, and worktree flows
• Remote sync over filesystem, HTTP, and SSH with branch tracking and dry-run support
• Agent-safe operation results that avoid forcing callers to parse raw CLI text

Benchmarking #

For a quick local sync benchmark against a generated packed filesystem remote:

dart run tool/benchmark_remote_sync.dart --commits 50 --rounds 5

The script creates temporary repositories, builds a deeper history, optionally packs the remote object store, and reports average/min/max timings for fetch(...) and clone(...).

Development #

Run the standard verification set locally:

dart format .
dart analyze
dart test
dart run example/basic.dart /path/to/repository

GitHub Actions also validates pushes to main and pull requests with:

• dart format --output=none --set-exit-if-changed .
• dart analyze
• dart test

Roadmap #

Likely next areas of expansion are:

• Further transport hardening, capability negotiation, and protocol parity
• More fixture depth around larger repositories and failure-path coverage
• Additional documentation and examples for embedding git_core in higher level tools

Contributing #

Issues and pull requests are welcome. For local contributor workflow details, see AGENTS.md and commit message guidance in CONTRIBUTING.md.

License #

This project is available under the MIT License.