git2dart

Description:

git2dart

git2dart #
Dart bindings to libgit2 #
git2dart package provides ability to use libgit2 in Dart/Flutter.
This is a hardfork of libgit2dart
Currently supported platforms are 64-bit Windows, Linux, MacOS on both Flutter and Dart VM.

Getting Started
Usage

Repository
Commit
Tree and TreeEntry
Tag
Blob
Commit Walker
Index and IndexEntry
References and RefLog
Branches
Diff
Patch
Config Files
Checkout
Merge
Stashes
Worktrees
Submodules


Contributing
Development

Getting Started #

Add package as a dependency in your pubspec.yaml
Import:

import 'package:git2dart/git2dart.dart';
copied to clipboard

Verify installation (should return string with version of libgit2 shipped with package):

...
print(Libgit2.version);
...
copied to clipboard
Note: The following steps only required if you are using package in Dart application (Flutter application will have libgit2 library bundled automatically when you build for release).
After adding the package as dependency you should run:
Usage #
git2dart provides you ability to manage Git repository. You can read and write objects (commit, tag, tree and blob), walk a tree, access the staging area, manage config and lots more.
Let's look at some of the classes and methods (you can also check example).
Repository #
Instantiation
You can instantiate a Repository class with a path to open an existing repository:
final repo = Repository.open('path/to/repository'); // => Repository
copied to clipboard
You can create new repository with provided path and optional bare argument if you want it to be bare:
final repo = Repository.init(path: 'path/to/folder', bare: true); // => Repository
copied to clipboard
You can clone the existing repository at provided url into local path:
final repo = Repository.clone(
url: 'https://some.url/',
localPath: 'path/to/clone/into',
); // => Repository
copied to clipboard
Also you can discover the path to the '.git' directory of repository if you provide a path to subdirectory:
Repository.discover(startPath: '/repository/lib/src'); // => '/repository/.git/'
copied to clipboard
Once the repository object is instantiated (repo in the following examples) you can perform various operations on it.
Accessing repository
// Boolean repository state values
repo.isBare; // => false
repo.isEmpty; // => true
repo.isHeadDetached; // => false
repo.isBranchUnborn; // => false
repo.isWorktree; // => false

// Path getters
repo.path; // => 'path/to/repository/.git/'
repo.workdir; // => 'path/to/repository/

// The HEAD of the repository
final ref = repo.head; // => Reference

// From returned ref you can get the 'name', 'target', target 'sha' and much more
ref.name; // => 'refs/heads/master'
ref.target; // => Oid
ref.target.sha; // => '821ed6e80627b8769d170a293862f9fc60825226'

// Looking up object with oid
final oid = repo['821ed6e80627b8769d170a293862f9fc60825226']; // => Oid
final commit = Commit.lookup(repo: repo, oid: oid); // => Commit
commit.message; // => 'initial commit'
copied to clipboard
Writing to repository
// Suppose you created a new file named 'new.txt' in your freshly initialized
// repository and you want to commit it.

final index = repo.index; // => Index
index.add('new.txt');
index.write();
final tree = Tree.lookup(repo: repo, oid: index.writeTree()); // => Tree

Commit.create(
repo: repo,
updateRef: 'refs/heads/master',
message: 'initial commit\n',
author: repo.defaultSignature,
committer: repo.defaultSignature,
tree: tree,
parents: [], // empty list for initial commit, 1 parent for regular and 2+ for merge commits
); // => Oid
copied to clipboard

Git Objects #
There are four kinds of base object types in Git: commits, trees, tags, and blobs. git2dart have a corresponding class for each of these object types.
Lookups of these objects requires Oid object, which can be instantiated from provided SHA-1 string in two ways:
// Using alias on repository object with SHA-1 string that can be any length
// between 4 and 40 characters
final oid = repo['821ed6e'];

// Using named constructor from Oid class (rules for SHA-1 string length is
// the same)
final oid = Oid.fromSHA(repo: repo, sha: '821ed6e');
copied to clipboard
Commit #
Commit lookup and some of the getters of the object:
final commit = Commit.lookup(repo: repo, oid: repo['821ed6e']); // => Commit

commit.message; // => 'initial commit\n'
commit.time; // => 1635869993 (seconds since epoch)
commit.author; // => Signature
commit.tree; // => Tree
copied to clipboard
Tree and TreeEntry #
Tree and TreeEntry lookup and some of their getters and methods:
final tree = Tree.lookup(repo: repo, oid: repo['a8ae3dd']); // => Tree

tree.entries; // => [TreeEntry, TreeEntry, ...]
tree.length; // => 3
tree.oid; // => Oid

// You can lookup single tree entry in the tree with index
final entry = tree[0]; // => TreeEntry

// You can lookup single tree entry in the tree with path to file
final entry = tree['some/file.txt']; // => TreeEntry

// Or you can lookup single tree entry in the tree with filename
final entry = tree['file.txt']; // => TreeEntry

entry.oid; // => Oid
entry.name // => 'file.txt'
entry.filemode // => GitFilemode.blob
copied to clipboard
You can also write trees with TreeBuilder:
final builder = TreeBuilder(repo: repo); // => TreeBuilder
builder.add(
filename: 'file.txt',
oid: index['file.txt'].oid,
filemode: GitFilemode.blob,
);
final treeOid = builder.write(); // => Oid

// Perform commit using that tree in arguments
...
copied to clipboard
Tag #
Tag create and lookup methods and some of the object getters:
// Create annotated tag
final annotated = Tag.createAnnotated(
repo: repo,
tagName: 'v0.1',
target: repo['821ed6e'],
targetType: GitObject.commit,
tagger: repo.defaultSignature,
message: 'tag message',
); // => Oid

// Create lightweight tag
final lightweight = Tag.createLightweight(
repo: repo,
tagName: 'v0.1',
target: repo['821ed6e'],
targetType: GitObject.commit,
); // => Oid

// Lookup tag
final tag = Tag.lookup(repo: repo, oid: repo['f0fdbf5']); // => Tag

// Get list of all the tags names in repository
repo.tags; // => ['v0.1', 'v0.2']

tag.oid; // => Oid
tag.name; // => 'v0.1'
copied to clipboard
Blob #
Blob create and lookup methods and some of the object getters:
// Create a new blob from the file at provided path
final oid = Blob.createFromDisk(repo: repo, path: 'path/to/file.txt'); // => Oid

// Lookup blob
final blob = Blob.lookup(repo: repo, oid: repo['e69de29']); // => Blob

blob.oid; // => Oid
blob.content; // => 'content of the file'
blob.size; // => 19
copied to clipboard

Commit Walker #
There's two ways to traverse a set of commits. Through Repository object alias or by using RevWalk class for finer control:
// Traverse a set of commits starting at provided oid
final commits = repo.log(oid: repo['821ed6e']); // => [Commit, Commit, ...]

// Use RevWalk object to fine tune traversal
final walker = RevWalk(repo); // => RevWalk

// Set desired sorting (optional)
walker.sorting({GitSort.topological, GitSort.time});

// Push Oid for the starting point
walker.push(repo['821ed6e']);

// Hide commits if you are not interested in anything beneath them
walker.hide(repo['c68ff54']);

// Perform traversal
final commits = walker.walk(); // => [Commit, Commit, ...]
copied to clipboard

Index and IndexEntry #
Some methods and getters to inspect and manipulate the Git index ("staging area"):
// Initialize Index object
final index = repo.index; // => Index

// Get number of entries in index
index.length; // => 69

// Re-read the index from disk
index.read();

// Write an existing index object to disk
index.write();

// Iterate over index entries
for (final entry in index) {
print(entry.path); // => 'path/to/file.txt'
}

// Get a specific entry
final entry = index['file.txt']; // => IndexEntry

// Stage using path to file or IndexEntry (updates existing entry if there is one)
index.add('new.txt');

// Unstage entry from index
index.remove('new.txt');
copied to clipboard

References and RefLog #
// Get names of all of the references that can be found in repository
final refs = repo.references; // => ['refs/heads/master', 'refs/tags/v0.1', ...]

// Lookup reference
final ref = Reference.lookup(repo: repo, name: 'refs/heads/master'); // => Reference

ref.type; // => ReferenceType.direct
ref.target; // => Oid
ref.name; // => 'refs/heads/master'

// Create reference
final ref = Reference.create(
repo: repo,
name: 'refs/heads/feature',
target: repo['821ed6e'],
); // => Reference

// Update reference
ref.setTarget(repo['c68ff54']);

// Rename reference
Reference.rename(repo: repo, oldName: 'refs/heads/feature', newName: 'refs/heads/feature2');

// Delete reference
Reference.delete(repo: repo, name: 'refs/heads/feature2');

// Access the reflog
final reflog = ref.log; // => RefLog
final entry = reflog.first; // RefLogEntry

entry.message; // => 'commit (initial): init'
entry.committer; // => Signature
copied to clipboard

Branches #
// Get all the branches that can be found in repository
final branches = repo.branches; // => [Branch, Branch, ...]

// Get only local/remote branches
final local = repo.branchesLocal; // => [Branch, Branch, ...]
final remote = repo.branchesRemote; // => [Branch, Branch, ...]

// Lookup branch (lookups in local branches if no value for argument `type`
// is provided)
final branch = Branch.lookup(repo: repo, name: 'master'); // => Branch

branch.target; // => Oid
branch.isHead; // => true
branch.name; // => 'master'

// Create branch
Branch.create(repo: repo, name: 'feature', target: commit); // => Branch

// Rename branch
Branch.rename(repo: repo, oldName: 'feature', newName: 'feature2');

// Delete branch
Branch.delete(repo: repo, name: 'feature2');
copied to clipboard

Diff #
There is multiple ways to get the diff:
// Diff between index (staging area) and current working directory
final diff = Diff.indexToWorkdir(repo: repo, index: repo.index); // => Diff

// Diff between tree and index (staging area)
final diff = Diff.treeToIndex(repo: repo, tree: tree, index: repo.index); // => Diff

// Diff between tree and current working directory
final diff = Diff.treeToWorkdir(repo: repo, tree: tree); // => Diff

// Diff between tree and current working directory with index
final diff = Diff.treeToWorkdirWithIndex(repo: repo, tree: tree); // => Diff

// Diff between two tree objects
final diff = Diff.treeToTree(repo: repo, oldTree: tree1, newTree: tree2); // => Diff

// Diff between two index objects
final diff = Diff.indexToIndex(repo: repo, oldIndex: repo.index, newIndex: index); // => Diff

// Read the contents of a git patch file
final diff = Diff.parse(patch.text); // => Diff
copied to clipboard
Some methods for inspecting Diff object:
// Get the number of diff records
diff.length; // => 3

// Get the patch
diff.patch; // => 'diff --git a/modified_file b/modified_file ...'

// Get the DiffStats object of the diff
final stats = diff.stats; // => DiffStats
stats.insertions; // => 69
stats.deletions; // => 420
stats.filesChanged; // => 1

// Get the list of DiffDelta's containing file pairs with and old and new revisions
final deltas = diff.deltas; // => [DiffDelta, DiffDelta, ...]
final delta = deltas.first; // => DiffDelta
delta.status; // => GitDelta.modified
delta.oldFile; // => DiffFile
delta.newFile; // => DiffFile
copied to clipboard

Patch #
Some API methods to generate patch:
// Patch from difference between two blobs
final patch = Patch.fromBlobs(
oldBlob: null, // empty blob
newBlob: blob,
newBlobPath: 'file.txt',
); // => Patch

// Patch from entry in the diff list at provided index position
final patch = Patch.fromDiff(diff: diff, index: 0); // => Patch
copied to clipboard
Some methods for inspecting Patch object:
// Get the content of a patch as a single diff text
patch.text; // => 'diff --git a/modified_file b/modified_file ...'

// Get the size of a patch diff data in bytes
patch.size(); // => 1337

// Get the list of hunks in a patch
patch.hunks; // => [DiffHunk, DiffHunk, ...]
copied to clipboard

Config files #
Some methods and getters of Config object:
// Open config file at provided path
final config = Config.open('path/to/config'); // => Config

// Open configuration file for repository
final config = repo.config; // => Config

// Get value of config variable
config['user.name'].value; // => 'Some Name'

// Set value of config variable
config['user.name'] = 'Another Name';

// Delete variable from the config
config.delete('user.name');
copied to clipboard

Checkout #
Perform different types of checkout:
// Update files in the index and the working directory to match the
// content of the commit pointed at by HEAD
Checkout.head(repo: repo);

// Update files in the working directory to match the content of the index
Checkout.index(repo: repo);

// Update files in the working directory to match the content of the tree
// pointed at by the reference target
Checkout.reference(repo: repo, name: 'refs/heads/master');

// Update files in the working directory to match the content of the tree
// pointed at by the commit
Checkout.commit(repo: repo, commit: commit);

// Perform checkout using various strategies
Checkout.head(repo: repo, strategy: {GitCheckout.force});

// Checkout only required files
Checkout.head(repo: repo, paths: ['some/file.txt']);
copied to clipboard

Merge #
Some API methods:
// Find a merge base between commits
final oid = Merge.base(
repo: repo,
commits: [commit1.oid, commit2.oid],
); // => Oid

// Merge commit into HEAD writing the results into the working directory
Merge.commit(repo: repo, commit: annotatedCommit);

// Cherry-pick the provided commit, producing changes in the index and
// working directory.
Merge.cherryPick(repo: repo, commit: commit);
copied to clipboard

Stashes #
// Get the list of all stashed states (first being the most recent)
repo.stashes; // => [Stash, Stash, ...]

// Save local modifications to a new stash
Stash.create(repo: repo, stasher: signature, message: 'WIP'); // => Oid

// Apply stash (defaults to last saved if index is not provided)
Stash.apply(repo: repo);

// Apply only specific paths from stash
Stash.apply(repo: repo, paths: ['file.txt']);

// Drop stash (defaults to last saved if index is not provided)
Stash.drop(repo: repo);

// Pop stash (apply and drop if successful, defaults to last saved
// if index is not provided)
Stash.pop(repo: repo);
copied to clipboard

Worktrees #
// Get list of names of linked worktrees
repo.worktrees; // => ['worktree1', 'worktree2'];

// Lookup existing worktree
Worktree.lookup(repo: repo, name: 'worktree1'); // => Worktree

// Create new worktree
final worktree = Worktree.create(
repo: repo,
name: 'worktree3',
path: '/worktree3/path/',
); // => Worktree

// Get name of worktree
worktree.name; // => 'worktree3'

// Get path for the worktree
worktree.path; // => '/worktree3/path/';

// Lock and unlock worktree
worktree.lock();
worktree.unlock();

// Prune the worktree (remove the git data structures on disk)
worktree.prune();
copied to clipboard

Submodules #
Some API methods for submodule management:
// Get list with all tracked submodules paths
repo.submodules; // => ['Submodule1', 'Submodule2'];

// Lookup submodule
Submodule.lookup(repo: repo, name: 'Submodule'); // => Submodule

// Init and update
Submodule.init(repo: repo, name: 'Submodule');
Submodule.update(repo: repo, name: 'Submodule');

// Add submodule
Submodule.add(repo: repo, url: 'https://some.url', path: 'submodule'); // => Submodule
copied to clipboard
Some methods for inspecting Submodule object:
// Get name of the submodule
submodule.name; // => 'Submodule'

// Get path to the submodule
submodule.path; // => 'Submodule'

// Get URL for the submodule
submodule.url; // => 'https://some.url'

// Set URL for the submodule in the configuration
submodule.url = 'https://updated.url';
submodule.sync();
copied to clipboard

Contributing #
Fork git2dart, improve git2dart, send a pull request.

Development #
Troubleshooting #
Linux
If you are developing on Linux using non-Debian based distrib you might encounter these errors:

Failed to load dynamic library: libpcre.so.3: cannot open shared object file: No such file or directory
Failed to load dynamic library: libpcreposix.so.3: cannot open shared object file: No such file or directory

That happens because dynamic library is precompiled on Ubuntu and Arch/Fedora/RedHat names for those libraries are libpcre.so and libpcreposix.so.
To fix these errors create symlinks:
sudo ln -s /usr/lib64/libpcre.so /usr/lib64/libpcre.so.3
sudo ln -s /usr/lib64/libpcreposix.so /usr/lib64/libpcreposix.so.3
copied to clipboard
Running Tests #
To run all tests and generate coverage report make sure to have activated packages and lcov installed:
dart pub global activate coverage
copied to clipboard
And run:
./coverage.sh
open coverage/index.html
copied to clipboard

Licence #
MIT. See LICENSE file for more information.