feat(annotated)!: add more bindings and API methods (#26)

lib/libgit2dart.dart

@@ -1,3 +1,4 @@
+export 'src/annotated.dart';
 export 'src/blame.dart';
 export 'src/blob.dart';
 export 'src/branch.dart';

lib/src/annotated.dart

@@ -0,0 +1,102 @@
+import 'dart:ffi';
+
+import 'package:libgit2dart/libgit2dart.dart';
+import 'package:libgit2dart/src/bindings/annotated.dart' as bindings;
+import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
+
+/// An annotated commit contains information about how it was looked up, which
+/// may be useful for functions like merge or rebase to provide context to the
+/// operation. For example, conflict files will include the name of the source
+/// or target branches being merged.
+class AnnotatedCommit {
+  /// Lookups an annotated commit from the given commit [oid].
+  ///
+  /// It is preferable to use [AnnotatedCommit.fromReference] instead of this
+  /// one, for commit to contain more information about how it was looked up.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  AnnotatedCommit.lookup({required Repository repo, required Oid oid}) {
+    _annotatedCommitPointer = bindings.lookup(
+      repoPointer: repo.pointer,
+      oidPointer: oid.pointer,
+    );
+  }
+
+  /// Creates an annotated commit from the given [reference].
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  AnnotatedCommit.fromReference({
+    required Repository repo,
+    required Reference reference,
+  }) {
+    _annotatedCommitPointer = bindings.fromRef(
+      repoPointer: repo.pointer,
+      referencePointer: reference.pointer,
+    );
+  }
+
+  /// Creates an annotated commit from a revision string.
+  ///
+  /// See `man gitrevisions`, or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
+  /// for information on the syntax accepted.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  AnnotatedCommit.fromRevSpec({
+    required Repository repo,
+    required String spec,
+  }) {
+    _annotatedCommitPointer = bindings.fromRevSpec(
+      repoPointer: repo.pointer,
+      revspec: spec,
+    );
+  }
+
+  /// Creates an annotated commit from the given fetch head data.
+  ///
+  /// [repo] is repository that contains the given commit.
+  ///
+  /// [branchName] is name of the (remote) branch.
+  ///
+  /// [remoteUrl] is url of the remote.
+  ///
+  /// [oid] is the commit object id of the remote branch.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  AnnotatedCommit.fromFetchHead({
+    required Repository repo,
+    required String branchName,
+    required String remoteUrl,
+    required Oid oid,
+  }) {
+    _annotatedCommitPointer = bindings.fromFetchHead(
+      repoPointer: repo.pointer,
+      branchName: branchName,
+      remoteUrl: remoteUrl,
+      oid: oid.pointer,
+    );
+  }
+
+  late final Pointer<git_annotated_commit> _annotatedCommitPointer;
+
+  /// Pointer to pointer to memory address for allocated commit object.
+  Pointer<git_annotated_commit> get pointer => _annotatedCommitPointer;
+
+  /// Commit oid that the given annotated commit refers to.
+  Oid get oid => Oid.fromRaw(bindings.oid(_annotatedCommitPointer).ref);
+
+  /// Reference name that the annotated commit refers to.
+  ///
+  /// Returns empty string if no information found.
+  String get refName => bindings.refName(_annotatedCommitPointer);
+
+  /// Releases memory allocated for commit object.
+  void free() => bindings.free(_annotatedCommitPointer);
+}

lib/src/bindings/annotated.dart

@@ -0,0 +1,132 @@
+import 'dart:ffi';
+
+import 'package:ffi/ffi.dart';
+import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
+import 'package:libgit2dart/src/error.dart';
+import 'package:libgit2dart/src/util.dart';
+
+/// Creates an annotated commit from the given commit id. The resulting
+/// annotated commit must be freed with [annotatedFree].
+///
+/// An annotated commit contains information about how it was looked up, which
+/// may be useful for functions like merge or rebase to provide context to the
+/// operation. For example, conflict files will include the name of the source
+/// or target branches being merged. It is therefore preferable to use the most
+/// specific function (e.g. [annotatedFromRef]) instead of this one when that
+/// data is known.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_annotated_commit> lookup({
+  required Pointer<git_repository> repoPointer,
+  required Pointer<git_oid> oidPointer,
+}) {
+  final out = calloc<Pointer<git_annotated_commit>>();
+  final error = libgit2.git_annotated_commit_lookup(
+    out,
+    repoPointer,
+    oidPointer,
+  );
+
+  if (error < 0) {
+    calloc.free(out);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Creates an annotated commit from the given reference.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_annotated_commit> fromRef({
+  required Pointer<git_repository> repoPointer,
+  required Pointer<git_reference> referencePointer,
+}) {
+  final out = calloc<Pointer<git_annotated_commit>>();
+  final error = libgit2.git_annotated_commit_from_ref(
+    out,
+    repoPointer,
+    referencePointer,
+  );
+
+  if (error < 0) {
+    calloc.free(out);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Creates an annotated commit from a revision string.
+///
+/// See `man gitrevisions`, or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
+/// for information on the syntax accepted.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_annotated_commit> fromRevSpec({
+  required Pointer<git_repository> repoPointer,
+  required String revspec,
+}) {
+  final out = calloc<Pointer<git_annotated_commit>>();
+  final revspecC = revspec.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_annotated_commit_from_revspec(
+    out,
+    repoPointer,
+    revspecC,
+  );
+
+  calloc.free(revspecC);
+
+  if (error < 0) {
+    calloc.free(out);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Creates an annotated commit from the given fetch head data.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_annotated_commit> fromFetchHead({
+  required Pointer<git_repository> repoPointer,
+  required String branchName,
+  required String remoteUrl,
+  required Pointer<git_oid> oid,
+}) {
+  final out = calloc<Pointer<git_annotated_commit>>();
+  final branchNameC = branchName.toNativeUtf8().cast<Int8>();
+  final remoteUrlC = remoteUrl.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_annotated_commit_from_fetchhead(
+    out,
+    repoPointer,
+    branchNameC,
+    remoteUrlC,
+    oid,
+  );
+
+  calloc.free(branchNameC);
+  calloc.free(remoteUrlC);
+
+  if (error < 0) {
+    calloc.free(out);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Gets the commit ID that the given annotated commit refers to.
+Pointer<git_oid> oid(Pointer<git_annotated_commit> commit) =>
+    libgit2.git_annotated_commit_id(commit);
+
+/// Get the refname that the given annotated commit refers to.
+String refName(Pointer<git_annotated_commit> commit) {
+  final result = libgit2.git_annotated_commit_ref(commit);
+  return result == nullptr ? '' : result.cast<Utf8>().toDartString();
+}
+
+/// Frees an annotated commit.
+void free(Pointer<git_annotated_commit> commit) {
+  libgit2.git_annotated_commit_free(commit);
+}

lib/src/bindings/commit.dart

@@ -25,41 +25,6 @@ Pointer<git_commit> lookup({
   }
 }
 
-/// Creates an annotated commit from the given commit id. The resulting
-/// annotated commit must be freed with [annotatedFree].
-///
-/// An annotated commit contains information about how it was looked up, which
-/// may be useful for functions like merge or rebase to provide context to the
-/// operation. For example, conflict files will include the name of the source
-/// or target branches being merged. It is therefore preferable to use the most
-/// specific function (eg git_annotated_commit_from_ref) instead of this one
-/// when that data is known.
-///
-/// Throws a [LibGit2Error] if error occured.
-Pointer<Pointer<git_annotated_commit>> annotatedLookup({
-  required Pointer<git_repository> repoPointer,
-  required Pointer<git_oid> oidPointer,
-}) {
-  final out = calloc<Pointer<git_annotated_commit>>();
-  final error = libgit2.git_annotated_commit_lookup(
-    out,
-    repoPointer,
-    oidPointer,
-  );
-
-  if (error < 0) {
-    calloc.free(out);
-    throw LibGit2Error(libgit2.git_error_last());
-  } else {
-    return out;
-  }
-}
-
-/// Frees an annotated commit.
-void annotatedFree(Pointer<git_annotated_commit> commit) {
-  libgit2.git_annotated_commit_free(commit);
-}
-
 /// Create new commit in the repository.
 ///
 /// Throws a [LibGit2Error] if error occured.

lib/src/bindings/merge.dart

@@ -89,17 +89,20 @@ Pointer<git_oid> mergeBaseOctopus({
 List<int> analysis({
   required Pointer<git_repository> repoPointer,
   required Pointer<git_reference> ourRefPointer,
-  required Pointer<Pointer<git_annotated_commit>> theirHeadPointer,
+  required Pointer<git_annotated_commit> theirHeadPointer,
   required int theirHeadsLen,
 }) {
   final analysisOut = calloc<Int32>();
   final preferenceOut = calloc<Int32>();
+  final theirHead = calloc<Pointer<git_annotated_commit>>();
+  theirHead[0] = theirHeadPointer;
+
   libgit2.git_merge_analysis_for_ref(
     analysisOut,
     preferenceOut,
     repoPointer,
     ourRefPointer,
-    theirHeadPointer,
+    theirHead,
     theirHeadsLen,
   );
 
@@ -107,6 +110,7 @@ List<int> analysis({
 
   calloc.free(analysisOut);
   calloc.free(preferenceOut);
+  calloc.free(theirHead);
 
   return result;
 }
@@ -117,12 +121,15 @@ List<int> analysis({
 /// completes, resolve any conflicts and prepare a commit.
 void merge({
   required Pointer<git_repository> repoPointer,
-  required Pointer<Pointer<git_annotated_commit>> theirHeadsPointer,
+  required Pointer<git_annotated_commit> theirHeadPointer,
   required int theirHeadsLen,
   required int favor,
   required int mergeFlags,
   required int fileFlags,
 }) {
+  final theirHead = calloc<Pointer<git_annotated_commit>>();
+  theirHead[0] = theirHeadPointer;
+
   final mergeOpts = _initMergeOptions(
     favor: favor,
     mergeFlags: mergeFlags,
@@ -138,7 +145,7 @@ void merge({
 
   libgit2.git_merge(
     repoPointer,
-    theirHeadsPointer,
+    theirHead,
     theirHeadsLen,
     mergeOpts,
     checkoutOpts,
@@ -146,6 +153,7 @@ void merge({
 
   calloc.free(mergeOpts);
   calloc.free(checkoutOpts);
+  calloc.free(theirHead);
 }
 
 /// Merge two files as they exist in the in-memory data structures, using the

lib/src/commit.dart

@@ -292,31 +292,3 @@ class Commit {
         ' author: $author}';
   }
 }
-
-/// An annotated commit contains information about how it was looked up, which
-/// may be useful for functions like merge or rebase to provide context to the
-/// operation. For example, conflict files will include the name of the source
-/// or target branches being merged.
-///
-/// Note: for internal use.
-class AnnotatedCommit {
-  /// Lookups an annotated commit from the given commit [oid].
-  ///
-  /// **IMPORTANT**: Should be freed to release allocated memory.
-  ///
-  /// Throws a [LibGit2Error] if error occured.
-  AnnotatedCommit.lookup({required Repository repo, required Oid oid}) {
-    _annotatedCommitPointer = bindings.annotatedLookup(
-      repoPointer: repo.pointer,
-      oidPointer: oid.pointer,
-    );
-  }
-
-  late final Pointer<Pointer<git_annotated_commit>> _annotatedCommitPointer;
-
-  /// Pointer to pointer to memory address for allocated commit object.
-  Pointer<Pointer<git_annotated_commit>> get pointer => _annotatedCommitPointer;
-
-  /// Releases memory allocated for commit object.
-  void free() => bindings.annotatedFree(_annotatedCommitPointer.value);
-}

lib/src/rebase.dart

@@ -15,44 +15,23 @@ class Rebase {
   /// reachable commits.
   ///
   /// [onto] is the branch to rebase onto, default is to rebase onto the given
-  /// [upstream] (throws if [upstream] is not provided).
+  /// [upstream].
   ///
   /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Rebase.init({
     required Repository repo,
-    Oid? branch,
-    Oid? upstream,
-    Oid? onto,
+    AnnotatedCommit? branch,
+    AnnotatedCommit? upstream,
+    AnnotatedCommit? onto,
   }) {
-    AnnotatedCommit? _branch, _upstream, _onto;
-    if (branch != null) {
-      _branch = AnnotatedCommit.lookup(repo: repo, oid: branch);
-    }
-    if (upstream != null) {
-      _upstream = AnnotatedCommit.lookup(repo: repo, oid: upstream);
-    }
-    if (onto != null) {
-      _onto = AnnotatedCommit.lookup(repo: repo, oid: onto);
-    }
-
     _rebasePointer = bindings.init(
       repoPointer: repo.pointer,
-      branchPointer: _branch?.pointer.value,
-      upstreamPointer: _upstream?.pointer.value,
-      ontoPointer: _onto?.pointer.value,
+      branchPointer: branch?.pointer,
+      upstreamPointer: upstream?.pointer,
+      ontoPointer: onto?.pointer,
     );
-
-    if (branch != null) {
-      _branch!.free();
-    }
-    if (upstream != null) {
-      _upstream!.free();
-    }
-    if (onto != null) {
-      _onto!.free();
-    }
   }
 
   /// Pointer to memory address for allocated rebase object.

lib/src/repository.dart

@@ -1018,7 +1018,7 @@ class Repository {
     return <Object>[analysisSet, mergePreference];
   }
 
-  /// Merges the given commit [oid] into HEAD, writing the results into the
+  /// Merges the given [commit] into HEAD, writing the results into the
   /// working directory. Any changes are staged for commit and any conflicts
   /// are written to the index. Callers should inspect the repository's index
   /// after this completes, resolve any conflicts and prepare a commit.
@@ -1036,26 +1036,19 @@ class Repository {
   ///
   /// Throws a [LibGit2Error] if error occured.
   void merge({
-    required Oid oid,
+    required AnnotatedCommit commit,
     GitMergeFileFavor favor = GitMergeFileFavor.normal,
     Set<GitMergeFlag> mergeFlags = const {GitMergeFlag.findRenames},
     Set<GitMergeFileFlag> fileFlags = const {GitMergeFileFlag.defaults},
   }) {
-    final theirHead = AnnotatedCommit.lookup(
-      repo: this,
-      oid: oid,
-    );
-
     merge_bindings.merge(
       repoPointer: _repoPointer,
-      theirHeadsPointer: theirHead.pointer,
+      theirHeadPointer: commit.pointer,
       theirHeadsLen: 1,
       favor: favor.value,
       mergeFlags: mergeFlags.fold(0, (acc, e) => acc | e.value),
       fileFlags: fileFlags.fold(0, (acc, e) => acc | e.value),
     );
-
-    theirHead.free();
   }
 
   /// Merges two files as they exist in the in-memory data structures, using the