Libgit2dart
Dart bindings to libgit2
Install / Use
/learn @SkinnyMind/Libgit2dartREADME
libgit2dart
Dart bindings to libgit2
libgit2dart package provides ability to use libgit2 in Dart/Flutter.
Currently supported platforms are 64-bit Linux, MacOS and Windows on both Flutter and Dart VM.
Getting Started
- Add package as a dependency in your
pubspec.yaml - Import:
import 'package:libgit2dart/libgit2dart.dart';
- Verify installation (should return string with version of libgit2 shipped with package):
...
print(Libgit2.version);
...
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:
dart run libgit2dart:setup
That'll copy the prebuilt libgit2 library for your platform into .dart_tool/libgit2/<platform>/ which you'll need to add to the same folder as your executable after compilation.
If you upgrade the version of libgit2dart package in your dependencies you should run the following commands to have the latest libgit2 library for your platform to provide with your application:
dart run libgit2dart:setup clean
dart run libgit2dart:setup
Usage
libgit2dart 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
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
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
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/'
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'
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
Git Objects
There are four kinds of base object types in Git: commits, trees, tags, and blobs. libgit2dart 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');
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
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
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
...
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'
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
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, ...]
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');
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
Branches
// Get all the branches that can be found in repository
final branches = repo.branches; // =>
