Compatibility topic

Compatibility

This page is the only statement of the package's compatibility policy.

Platforms and toolchain

The package runs on the Dart VM on Linux, macOS and Windows and requires Dart SDK ^3.3.0. The process backend needs git 2.28 or newer, the release that provides init --initial-branch; reference transactions already need 2.27. GitMerge.mergeTree needs git 2.38 or newer (merge-tree --write-tree). Browsers are not supported, and the dart:io server adapter targets the Dart VM.

Versioned libraries

package:git_engine/git_engine.dart, package:git_engine/process.dart, package:git_engine/server_io.dart and package:git_engine/testing.dart follow semantic versioning.

package:git_engine/backend.dart serves the engines maintained with the package and stays outside that promise.

Everything under lib/src/ is private.

Capability contracts

These small shapes are implemented outside the package by a backend or a host. They grow only in a major version, by a new interface that extends the old one.

Repository-side contracts:

• GitObjectReader, GitObjectWriter, GitObjectStore, GitRefReader.
• GitRevisionResolver, GitHistoryReader, GitRefTransaction.
• GitRepositoryReader, GitRepositoryWriter.

Server-side contracts:

• GitPrincipal, GitAuthorizationPolicy, GitServiceResponse.
• GitUploadPackService, GitHttpRequest.

Facades

Facades aggregate capabilities and convenience methods. Members may be added to them in a minor version, and they are not meant to be implemented outside the package.

• The repository hierarchy: GitRepository, GitIndexedRepository, GitFileRepository.
• GitWorkingRepository, GitBareRepository, GitFileBareRepository.
• GitRepositoryManager, GitFileClient, GitEngineRuntime, GitSmartHttpHandler.
• Repository configuration: GitConfig, GitRemotes.
• Branches and tags: GitBranches, GitTags, GitRefs.
• Revisions and history: GitRevisions, GitHistory.
• Objects and index: GitObjects, GitIndex.
• Work tree and patches: GitWorktree, GitPatches, GitIndexedPatches.
• GitWorkingPatches, GitMerge, GitWorkingMerge, GitDirectoryFiles.

Incompatible changes

An incompatible change waits for a major version and goes through deprecations first.

Classes

GitAuthorizationPolicy

Decides whether an identity may read or write a served repository.

GitHistoryReader

Walks the commit graph of one repository.

GitHttpRequest

A request received by a transport adapter, independent of any HTTP framework.

GitObjectReader

Read access to the objects of one repository, addressed by object name.

GitObjectStore

Read and write access to the objects of one repository.

GitObjectWriter

Writes any object to a repository from its type and serialized content.

GitPrincipal

An identity authenticated by the host application.

GitRefReader

Read access to the references of one repository.

GitRefTransaction

A set of reference updates applied together, all or nothing.

GitRepositoryReader

Read-only view of one repository's stored data.

GitRepositoryWriter

Read and write view of the stored data of one repository.

GitRevisionResolver

Interprets git revision expressions (HEAD~2, main^{tree}…).

GitServiceResponse

Response stream of a server service, transport independent.

GitUploadPackService

Serves clone and fetch for a repository designated by its identifier.