feat(tag)!: add bindings and API methods (#36)

- add binding and API method for git_tag_create_lightweight
- add API method that returns tag target type

BREAKING CHANGE: add specific methods `createAnnotated` and `createLightweight`.

lib/src/bindings/tag.dart

@@ -84,7 +84,7 @@ String message(Pointer<git_tag> tag) =>
 Pointer<git_signature> tagger(Pointer<git_tag> tag) =>
     libgit2.git_tag_tagger(tag);
 
-/// Create a new tag in the repository from an object.
+/// Create a new annotated tag in the repository from an object.
 ///
 /// A new reference will also be created pointing to this tag object. If force
 /// is true and a reference already exists with the given name, it'll be
@@ -97,7 +97,7 @@ Pointer<git_signature> tagger(Pointer<git_tag> tag) =>
 /// special meaning to revparse.
 ///
 /// Throws a [LibGit2Error] if error occured.
-Pointer<git_oid> create({
+Pointer<git_oid> createAnnotated({
   required Pointer<git_repository> repoPointer,
   required String tagName,
   required Pointer<git_object> targetPointer,
@@ -108,7 +108,6 @@ Pointer<git_oid> create({
   final out = calloc<git_oid>();
   final tagNameC = tagName.toNativeUtf8().cast<Int8>();
   final messageC = message.toNativeUtf8().cast<Int8>();
-  final forceC = force ? 1 : 0;
   final error = libgit2.git_tag_create(
     out,
     repoPointer,
@@ -116,7 +115,7 @@ Pointer<git_oid> create({
     targetPointer,
     taggerPointer,
     messageC,
-    forceC,
+    force ? 1 : 0,
   );
 
   calloc.free(tagNameC);
@@ -130,6 +129,42 @@ Pointer<git_oid> create({
   }
 }
 
+/// Create a new lightweight tag pointing at a target object.
+///
+/// A new direct reference will be created pointing to this target object. If
+/// force is true and a reference already exists with the given name, it'll be
+/// replaced.
+///
+/// The tag name will be checked for validity. See [createAnnotated] for rules
+/// about valid names.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_oid> createLightweight({
+  required Pointer<git_repository> repoPointer,
+  required String tagName,
+  required Pointer<git_object> targetPointer,
+  required bool force,
+}) {
+  final out = calloc<git_oid>();
+  final tagNameC = tagName.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_tag_create_lightweight(
+    out,
+    repoPointer,
+    tagNameC,
+    targetPointer,
+    force ? 1 : 0,
+  );
+
+  calloc.free(tagNameC);
+
+  if (error < 0) {
+    calloc.free(out);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out;
+  }
+}
+
 /// Delete an existing tag reference.
 ///
 /// The tag name will be checked for validity.

lib/src/repository.dart

@@ -746,13 +746,12 @@ class Repository {
   /// **IMPORTANT**: Should be freed to release allocated memory.
   Tag lookupTag(Oid oid) => Tag.lookup(repo: this, oid: oid);
 
-  /// Creates a new tag in the repository for provided [target] object.
+  /// Creates a new annotated tag in the repository for provided [target]
+  /// object.
   ///
-  /// A new reference will also be created pointing to this tag object. If
-  /// [force] is true and a reference already exists with the given name, it'll
-  /// be replaced.
-  ///
-  /// The [message] will not be cleaned up.
+  /// A new reference will also be created in the `/refs/tags` folder pointing
+  /// to this tag object. If [force] is true and a reference already exists
+  /// with the given name, it'll be replaced.
   ///
   /// The [tagName] will be checked for validity. You must avoid the characters
   /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
@@ -777,7 +776,7 @@ class Repository {
   /// should be replaced.
   ///
   /// Throws a [LibGit2Error] if error occured.
-  Oid createTag({
+  Oid createAnnotatedTag({
     required String tagName,
     required Oid target,
     required GitObject targetType,
@@ -785,7 +784,7 @@ class Repository {
     required String message,
     bool force = false,
   }) {
-    return Tag.create(
+    return Tag.createAnnotated(
       repo: this,
       tagName: tagName,
       target: target,
@@ -796,6 +795,46 @@ class Repository {
     );
   }
 
+  /// Creates a new lightweight tag in the repository for provided [target]
+  /// object.
+  ///
+  /// A new reference will also be created in the `/refs/tags` folder pointing
+  /// to this tag object. If [force] is true and a reference already exists
+  /// with the given name, it'll be replaced.
+  ///
+  /// The [tagName] will be checked for validity. You must avoid the characters
+  /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
+  /// special meaning to revparse.
+  ///
+  /// [tagName] is the name for the tag. This name is validated for
+  /// consistency. It should also not conflict with an already existing tag
+  /// name.
+  ///
+  /// [target] is the object to which this tag points. This object must belong
+  /// to the given [repo].
+  ///
+  /// [targetType] is one of the [GitObject] basic types: commit, tree, blob or
+  /// tag.
+  ///
+  /// [force] determines whether existing reference with the same [tagName]
+  /// should be replaced.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void createLightweightTag({
+    required String tagName,
+    required Oid target,
+    required GitObject targetType,
+    bool force = false,
+  }) {
+    Tag.createLightweight(
+      repo: this,
+      tagName: tagName,
+      target: target,
+      targetType: targetType,
+      force: force,
+    );
+  }
+
   /// Deletes an existing tag reference with provided [name].
   ///
   /// The tag [name] will be checked for validity.

lib/src/tag.dart

@@ -25,13 +25,12 @@ class Tag {
   /// Pointer to memory address for allocated tag object.
   late final Pointer<git_tag> _tagPointer;
 
-  /// Creates a new tag in the repository for provided [target] object.
+  /// Creates a new annotated tag in the repository for provided [target]
+  /// object.
   ///
-  /// A new reference will also be created pointing to this tag object. If
-  /// [force] is true and a reference already exists with the given name, it'll
-  /// be replaced.
-  ///
-  /// The [message] will not be cleaned up.
+  /// A new reference will also be created in the `/refs/tags` folder pointing
+  /// to this tag object. If [force] is true and a reference already exists
+  /// with the given name, it'll be replaced.
   ///
   /// The [tagName] will be checked for validity. You must avoid the characters
   /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
@@ -58,7 +57,7 @@ class Tag {
   /// should be replaced.
   ///
   /// Throws a [LibGit2Error] if error occured.
-  static Oid create({
+  static Oid createAnnotated({
     required Repository repo,
     required String tagName,
     required Oid target,
@@ -73,7 +72,7 @@ class Tag {
       type: targetType.value,
     );
 
-    final result = bindings.create(
+    final result = bindings.createAnnotated(
       repoPointer: repo.pointer,
       tagName: tagName,
       targetPointer: object,
@@ -87,6 +86,56 @@ class Tag {
     return Oid(result);
   }
 
+  /// Creates a new lightweight tag in the repository for provided [target]
+  /// object.
+  ///
+  /// A new reference will also be created in the `/refs/tags` folder pointing
+  /// to this tag object. If [force] is true and a reference already exists
+  /// with the given name, it'll be replaced.
+  ///
+  /// The [tagName] will be checked for validity. You must avoid the characters
+  /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
+  /// special meaning to revparse.
+  ///
+  /// [repo] is the repository where to store the tag.
+  ///
+  /// [tagName] is the name for the tag. This name is validated for
+  /// consistency. It should also not conflict with an already existing tag
+  /// name.
+  ///
+  /// [target] is the object to which this tag points. This object must belong
+  /// to the given [repo].
+  ///
+  /// [targetType] is one of the [GitObject] basic types: commit, tree, blob or
+  /// tag.
+  ///
+  /// [force] determines whether existing reference with the same [tagName]
+  /// should be replaced.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static void createLightweight({
+    required Repository repo,
+    required String tagName,
+    required Oid target,
+    required GitObject targetType,
+    bool force = false,
+  }) {
+    final object = object_bindings.lookup(
+      repoPointer: repo.pointer,
+      oidPointer: target.pointer,
+      type: targetType.value,
+    );
+
+    bindings.createLightweight(
+      repoPointer: repo.pointer,
+      tagName: tagName,
+      targetPointer: object,
+      force: force,
+    );
+
+    object_bindings.free(object);
+  }
+
   /// Deletes an existing tag reference with provided [name] in a [repo]sitory.
   ///
   /// The tag [name] will be checked for validity.
@@ -137,6 +186,12 @@ class Tag {
     }
   }
 
+  /// The type of a tag's tagged object.
+  GitObject get targetType {
+    final type = bindings.targetType(_tagPointer);
+    return GitObject.values.firstWhere((e) => type & e.value == e.value);
+  }
+
   /// [Oid] of the tagged object of a tag.
   Oid get targetOid => Oid(bindings.targetOid(_tagPointer));