Siklos/libgit2dart
1
0
Fork 0
mirror of https://github.com/SkinnyMind/libgit2dart.git synced 2025-05-04 12:19:09 -04:00
Code Issues Projects Releases Wiki Activity

docs: update docs for bindings and api

Browse source
This commit is contained in:
Aleksey Kulikov 2022-04-28 16:04:30 +03:00
parent a3213a88a2
commit 9d61584165
52 changed files with 352 additions and 209 deletions
Download patch file Download diff file Expand all files Collapse all files

2
lib/src/annotated.dart
View file

@ -83,6 +83,8 @@ class AnnotatedCommit {
late final Pointer<git_annotated_commit> _annotatedCommitPointer;
/// Pointer to pointer to memory address for allocated commit object.
///
/// Note: For internal use.
Pointer<git_annotated_commit> get pointer => _annotatedCommitPointer;
/// Commit oid that the given annotated commit refers to.

11
lib/src/bindings/annotated.dart
View file

@ -5,7 +5,7 @@ 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
/// Creates an annotated commit from the given commit id. The returned
/// annotated commit must be freed with [annotatedFree].
///
/// An annotated commit contains information about how it was looked up, which
@ -38,7 +38,8 @@ Pointer<git_annotated_commit> lookup({
}
}
/// Creates an annotated commit from the given reference.
/// Creates an annotated commit from the given reference. The returned
/// annotated commit must be freed with [annotatedFree].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_annotated_commit> fromRef({
@ -63,7 +64,8 @@ Pointer<git_annotated_commit> fromRef({
}
}
/// Creates an annotated commit from a revision string.
/// Creates an annotated commit from a revision string. The returned
/// annotated commit must be freed with [annotatedFree].
///
/// See `man gitrevisions`, or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
/// for information on the syntax accepted.
@ -93,7 +95,8 @@ Pointer<git_annotated_commit> fromRevSpec({
}
}
/// Creates an annotated commit from the given fetch head data.
/// Creates an annotated commit from the given fetch head data. The returned
/// annotated commit must be freed with [annotatedFree].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_annotated_commit> fromFetchHead({

5
lib/src/bindings/blame.dart
View file

@ -5,7 +5,8 @@ import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/oid.dart';
import 'package:libgit2dart/src/util.dart';
/// Get the blame for a single file.
/// Get the blame for a single file. The returned blame must be freed with
/// [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_blame> file({
@ -68,6 +69,8 @@ Pointer<git_blame> file({
/// Lines that differ between the buffer and the committed version are marked
/// as having a zero OID for their finalCommitOid.
///
/// The returned blame must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_blame> buffer({
required Pointer<git_blame> reference,

11
lib/src/bindings/blob.dart
View file

@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Lookup a blob object from a repository.
/// Lookup a blob object from a repository. The returned blob must be freed
/// with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_blob> lookup({
@ -40,10 +41,6 @@ bool isBinary(Pointer<git_blob> blob) {
}
/// Get a read-only buffer with the raw content of a blob.
///
/// A pointer to the raw content of a blob is returned; this pointer is owned
/// internally by the object and shall not be free'd. The pointer may be
/// invalidated at a later time.
String content(Pointer<git_blob> blob) {
return libgit2.git_blob_rawcontent(blob).cast<Utf8>().toDartString();
}
@ -126,8 +123,8 @@ Pointer<git_oid> createFromDisk({
}
}
/// Create an in-memory copy of a blob. The copy must be explicitly free'd or
/// it will leak.
/// Create an in-memory copy of a blob. The returned copy must be freed with
/// [free].
Pointer<git_blob> duplicate(Pointer<git_blob> source) {
final out = calloc<Pointer<git_blob>>();
libgit2.git_blob_dup(out, source);

29
lib/src/bindings/branch.dart
View file

@ -7,7 +7,8 @@ import 'package:libgit2dart/src/bindings/reference.dart' as reference_bindings;
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Return a list of branches.
/// Return a list of branches. The returned references must be freed with
/// [free].
///
/// Throws a [LibGit2Error] if error occured.
List<Pointer<git_reference>> list({
@ -47,10 +48,10 @@ List<Pointer<git_reference>> list({
return result;
}
/// Lookup a branch by its name in a repository.
/// Lookup a branch by its name in a repository. The returned reference must be
/// freed with [free].
///
/// The generated reference must be freed by the user. The branch name will be
/// checked for validity.
/// The branch name will be checked for validity.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_reference> lookup({
@ -79,14 +80,13 @@ Pointer<git_reference> lookup({
}
}
/// Create a new branch pointing at a target commit.
/// Create a new branch pointing at a target commit. The returned reference
/// must be freed with [free].
///
/// A new direct reference will be created pointing to this target commit.
/// If force is true and a reference already exists with the given name, it'll
/// be replaced.
///
/// The returned reference must be freed by the user.
///
/// The branch name will be checked for validity.
///
/// Throws a [LibGit2Error] if error occured.
@ -121,6 +121,9 @@ Pointer<git_reference> create({
/// Delete an existing branch reference.
///
/// Note that if the deletion succeeds, the reference object will not be valid
/// anymore, and should be freed immediately with [free].
///
/// Throws a [LibGit2Error] if error occured.
void delete(Pointer<git_reference> branch) {
final error = libgit2.git_branch_delete(branch);
@ -134,6 +137,9 @@ void delete(Pointer<git_reference> branch) {
///
/// The new branch name will be checked for validity.
///
/// Note that if the move succeeds, the old reference object will not be valid
/// anymore, and should be freed immediately with [free].
///
/// Throws a [LibGit2Error] if error occured.
void rename({
required Pointer<git_reference> branchPointer,
@ -191,7 +197,8 @@ bool isCheckedOut(Pointer<git_reference> branch) {
/// Get the branch name.
///
/// Given a reference object, this will check that it really is a branch
/// (ie. it lives under "refs/heads/" or "refs/remotes/"), and return the branch part of it.
/// (ie. it lives under "refs/heads/" or "refs/remotes/"), and return the
/// branch part of it.
///
/// Throws a [LibGit2Error] if error occured.
String name(Pointer<git_reference> ref) {
@ -238,7 +245,8 @@ String remoteName({
}
}
/// Get the upstream of a branch.
/// Get the upstream of a branch. The returned reference must be freed with
/// [free].
///
/// Given a reference, this will return a new reference object corresponding to
/// its remote tracking branch. The reference must be a local branch.
@ -262,7 +270,8 @@ Pointer<git_reference> getUpstream(Pointer<git_reference> branch) {
/// Set a branch's upstream branch.
///
/// This will update the configuration to set the branch named [branchName] as
/// the upstream of branch. Pass a null name to unset the upstream information.
/// the upstream of branch. Pass a null [branchName] to unset the upstream
/// information.
///
/// **Note**: The actual tracking reference must have been already created for
/// the operation to succeed.

27
lib/src/bindings/commit.dart
View file

@ -5,9 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Lookup a commit object from a repository.
///
/// The returned object should be released with `free()` when no longer needed.
/// Lookup a commit object from a repository. The returned commit must be
/// freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_commit> lookup({
@ -30,6 +29,9 @@ Pointer<git_commit> lookup({
/// Create new commit in the repository.
///
/// The [message] will not be cleaned up automatically. I.e. excess whitespace
/// will not be removed and no trailing newline will be added.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_oid> create({
required Pointer<git_repository> repoPointer,
@ -195,8 +197,8 @@ Pointer<git_oid> amend({
}
}
/// Create an in-memory copy of a commit. The copy must be explicitly free'd or
/// it will leak.
/// Create an in-memory copy of a commit. The returned copy must be
/// freed with [free].
Pointer<git_commit> duplicate(Pointer<git_commit> source) {
final out = calloc<Pointer<git_commit>>();
libgit2.git_commit_dup(out, source);
@ -211,8 +213,7 @@ Pointer<git_commit> duplicate(Pointer<git_commit> source) {
/// Get the encoding for the message of a commit, as a string representing a
/// standard encoding name.
///
/// The encoding may be NULL if the encoding header in the commit is missing;
/// in that case UTF-8 is assumed.
/// If the encoding header in the commit is missing UTF-8 is assumed.
String messageEncoding(Pointer<git_commit> commit) {
final result = libgit2.git_commit_message_encoding(commit);
return result == nullptr ? 'utf-8' : result.cast<Utf8>().toDartString();
@ -313,9 +314,9 @@ Pointer<git_commit> parent({
}
}
/// Get the commit object that is the th generation ancestor of the named
/// commit object, following only the first parents. The returned commit has to
/// be freed by the caller.
/// Get the commit object that is the nth generation ancestor of the named
/// commit object, following only the first parents. The returned commit must
/// be freed with [free].
///
/// Passing 0 as the generation number returns another instance of the base
/// commit itself.
@ -353,6 +354,8 @@ Pointer<git_signature> committer(Pointer<git_commit> commit) {
}
/// Get the author of a commit.
///
/// The returned signature must be freed.
Pointer<git_signature> author(Pointer<git_commit> commit) {
return libgit2.git_commit_author(commit);
}
@ -363,6 +366,8 @@ Pointer<git_oid> treeOid(Pointer<git_commit> commit) {
}
/// Get the tree pointed to by a commit.
///
/// The returned tree must be freed.
Pointer<git_tree> tree(Pointer<git_commit> commit) {
final out = calloc<Pointer<git_tree>>();
libgit2.git_commit_tree(out, commit);
@ -392,7 +397,7 @@ void revert({
/// Reverts the given commit against the given "our" commit, producing an index
/// that reflects the result of the revert.
///
/// The returned index must be freed explicitly with [free].
/// The returned index must be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_index> revertCommit({

44
lib/src/bindings/config.dart
View file

@ -7,7 +7,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Create a new config instance containing a single on-disk file
/// Create a new config instance containing a single on-disk file. The returned
/// config must be freed with [free].
Pointer<git_config> open(String path) {
final out = calloc<Pointer<git_config>>();
final pathC = path.toNativeUtf8().cast<Int8>();
@ -18,12 +19,14 @@ Pointer<git_config> open(String path) {
return out.value;
}
/// Open the global, XDG and system configuration files
/// Open the global, XDG and system configuration files.
///
/// Utility wrapper that finds the global, XDG and system configuration
/// files and opens them into a single prioritized config object that can
/// be used when accessing default config data outside a repository.
///
/// The returned config must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_config> openDefault() {
final out = calloc<Pointer<git_config>>();
@ -40,14 +43,13 @@ Pointer<git_config> openDefault() {
}
}
/// Locate the path to the global configuration file
/// Locate the path to the global configuration file.
///
/// The user or global configuration file is usually located in
/// `$HOME/.gitconfig`.
///
/// This method will try to guess the full path to that file, if the file
/// exists. The returned path may be used on any method call to load
/// the global configuration file.
/// exists. The returned path may be used to load the global configuration file.
///
/// This method will not guess the path to the xdg compatible config file
/// (`.config/git/config`).
@ -69,9 +71,10 @@ String findGlobal() {
}
}
/// Locate the path to the system configuration file
/// Locate the path to the system configuration file.
///
/// If /etc/gitconfig doesn't exist, it will look for %PROGRAMFILES%\Git\etc\gitconfig
/// If `/etc/gitconfig` doesn't exist, it will look for
/// `%PROGRAMFILES%\Git\etc\gitconfig`
///
/// Throws a [LibGit2Error] if error occured.
String findSystem() {
@ -90,11 +93,15 @@ String findSystem() {
}
}
/// Locate the path to the global xdg compatible configuration file
/// Locate the path to the global xdg compatible configuration file.
///
/// The xdg compatible configuration file is usually located in
/// `$HOME/.config/git/config`.
///
/// This method will try to guess the full path to that file, if the file
/// exists. The returned path may be used to load the xdg compatible
/// configuration file.
///
/// Throws a [LibGit2Error] if error occured.
String findXdg() {
final out = calloc<git_buf>();
@ -112,7 +119,8 @@ String findXdg() {
}
}
/// Create a snapshot of the configuration.
/// Create a snapshot of the configuration. The returned config must be freed
/// with [free].
///
/// Create a snapshot of the current state of a configuration, which allows you
/// to look into a consistent view of the configuration for looking up complex
@ -128,7 +136,8 @@ Pointer<git_config> snapshot(Pointer<git_config> config) {
return result;
}
/// Get the config entry of a config variable.
/// Get the config entry of a config variable. The returned config entry must
/// be freed with [freeEntry].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_config_entry> getEntry({
@ -190,7 +199,8 @@ void setString({
calloc.free(valueC);
}
/// Iterate over all the config variables.
/// Iterate over all the config variables. The returned iterator must be freed
/// with [freeIterator].
Pointer<git_config_iterator> iterator(Pointer<git_config> cfg) {
final out = calloc<Pointer<git_config_iterator>>();
libgit2.git_config_iterator_new(out, cfg);
@ -220,10 +230,14 @@ void delete({
}
}
/// Iterate over the values of a multivar
/// Iterate over the values of a multivar.
///
/// If regexp is present, then the iterator will only iterate over all
/// If [regexp] is present, then the iterator will only iterate over all
/// values which match the pattern.
///
/// The regular expression is applied case-sensitively on the normalized form
/// of the variable name: the section and variable parts are lower-cased. The
/// subsection is left unchanged.
List<String> multivarValues({
required Pointer<git_config> configPointer,
required String variable,
@ -265,7 +279,7 @@ List<String> multivarValues({
/// Set the value of a multivar config variable in the config file with the
/// highest level (usually the local one).
///
/// The regexp is applied case-sensitively on the value.
/// The [regexp] is applied case-sensitively on the value.
void setMultivar({
required Pointer<git_config> configPointer,
required String variable,
@ -286,7 +300,7 @@ void setMultivar({
/// Deletes one or several values from a multivar in the config file
/// with the highest level (usually the local one).
///
/// The regexp is applied case-sensitively on the value.
/// The [regexp] is applied case-sensitively on the value.
void deleteMultivar({
required Pointer<git_config> configPointer,
required String variable,

9
lib/src/bindings/describe.dart
View file

@ -5,13 +5,10 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Describe a commit.
/// Describe a commit. The returned describe result must be freed with [free].
///
/// Perform the describe operation on the given committish object.
///
/// Returned object should be freed with `describeResultFree()` once no longer
/// needed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_describe_result> commit({
required Pointer<git_commit> commitPointer,
@ -44,7 +41,7 @@ Pointer<git_describe_result> commit({
}
}
/// Describe a commit.
/// Describe a commit. The returned describe result must be freed with [free].
///
/// Perform the describe operation on the current commit and the worktree.
/// After peforming describe on HEAD, a status is run and the description is
@ -118,7 +115,7 @@ String format({
}
/// Free the describe result.
void describeResultFree(Pointer<git_describe_result> result) {
void free(Pointer<git_describe_result> result) {
libgit2.git_describe_result_free(result);
}

29
lib/src/bindings/diff.dart
View file

@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Create a diff with the difference between two index objects.
/// Create a diff with the difference between two index objects. The returned
/// diff must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_diff> indexToIndex({
@ -43,7 +44,8 @@ Pointer<git_diff> indexToIndex({
}
}
/// Create a diff between the repository index and the workdir directory.
/// Create a diff between the repository index and the workdir directory. The
/// returned diff must be freed with [free].
Pointer<git_diff> indexToWorkdir({
required Pointer<git_repository> repoPointer,
required Pointer<git_index> indexPointer,
@ -68,7 +70,8 @@ Pointer<git_diff> indexToWorkdir({
return result;
}
/// Create a diff between a tree and repository index.
/// Create a diff between a tree and repository index. The returned diff must
/// be freed with [free].
Pointer<git_diff> treeToIndex({
required Pointer<git_repository> repoPointer,
required Pointer<git_tree>? treePointer,
@ -100,7 +103,8 @@ Pointer<git_diff> treeToIndex({
return result;
}
/// Create a diff between a tree and the working directory.
/// Create a diff between a tree and the working directory. The returned
/// diff must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_diff> treeToWorkdir({
@ -137,7 +141,8 @@ Pointer<git_diff> treeToWorkdir({
}
/// Create a diff between a tree and the working directory using index data to
/// account for staged deletes, tracked files, etc.
/// account for staged deletes, tracked files, etc. The returned diff must be
/// freed with [free].
///
/// This emulates `git diff <tree>` by diffing the tree to the index and the
/// index to the working directory and blending the results into a single diff
@ -177,7 +182,8 @@ Pointer<git_diff> treeToWorkdirWithIndex({
}
}
/// Create a diff with the difference between two tree objects.
/// Create a diff with the difference between two tree objects. The returned
/// diff must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_diff> treeToTree({
@ -233,7 +239,8 @@ void merge({
libgit2.git_diff_merge(ontoPointer, fromPointer);
}
/// Read the contents of a git patch file into a git diff object.
/// Read the contents of a git patch file into a git diff object. The returned
/// diff must be freed with [free].
///
/// The diff object produced is similar to the one that would be produced if
/// you actually produced it computationally by comparing two trees, however
@ -334,7 +341,8 @@ String statusChar(int status) {
return String.fromCharCode(libgit2.git_diff_status_char(status));
}
/// Accumulate diff statistics for all patches.
/// Accumulate diff statistics for all patches. The returned diff stats must be
/// freed with [freeStats].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_diff_stats> stats(Pointer<git_diff> diff) {
@ -458,7 +466,8 @@ bool apply({
}
}
/// Apply a diff to a tree, and return the resulting image as an index.
/// Apply a diff to a tree, and return the resulting image as an index. The
/// returned index must be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_index> applyToTree({
@ -502,7 +511,7 @@ Pointer<git_index> applyToTree({
}
/// Free a previously allocated diff stats.
void statsFree(Pointer<git_diff_stats> stats) =>
void freeStats(Pointer<git_diff_stats> stats) =>
libgit2.git_diff_stats_free(stats);
/// Free a previously allocated diff.

14
lib/src/bindings/index.dart
View file

@ -10,7 +10,7 @@ import 'package:libgit2dart/src/util.dart';
/// This index object cannot be read/written to the filesystem, but may be
/// used to perform in-memory index operations.
///
/// The index must be freed once it's no longer in use.
/// The returned index must be freed with [free].
Pointer<git_index> newInMemory() {
final out = calloc<Pointer<git_index>>();
libgit2.git_index_new(out);
@ -51,12 +51,12 @@ String path(Pointer<git_index> index) {
/// Update the contents of an existing index object in memory by reading from
/// the hard disk.
///
/// If force is true, this performs a "hard" read that discards in-memory
/// If [force] is true, this performs a "hard" read that discards in-memory
/// changes and always reloads the on-disk index data. If there is no on-disk
/// version, the index will be cleared.
///
/// If force is false, this does a "soft" read that reloads the index data from
/// disk only if it has changed since the last time it was loaded. Purely
/// If [force] is false, this does a "soft" read that reloads the index data
/// from disk only if it has changed since the last time it was loaded. Purely
/// in-memory index data will be untouched. Be aware: if there are changes on
/// disk, unwritten in-memory changes are discarded.
void read({required Pointer<git_index> indexPointer, required bool force}) {
@ -156,7 +156,7 @@ Pointer<git_index_entry> getByIndex({
/// Get a pointer to one of the entries in the index based on path.
///
///The entry is not modifiable and should not be freed.
/// The entry is not modifiable and should not be freed.
///
/// Throws [ArgumentError] if nothing found for provided path.
Pointer<git_index_entry> getByPath({
@ -214,7 +214,7 @@ void add({
/// Add or update an index entry from a file on disk.
///
/// The file path must be relative to the repository's working folder and must
/// The file [path] must be relative to the repository's working folder and must
/// be readable.
///
/// This method will fail in bare index instances.
@ -282,7 +282,7 @@ void addFromBuffer({
///
/// This method will fail in bare index instances.
///
/// The `pathspec` is a list of file names or shell glob patterns that will be
/// The [pathspec] is a list of file names or shell glob patterns that will be
/// matched against files in the repository's working directory. Each file that
/// matches will be added to the index (either updating an existing entry or
/// adding a new entry).

14
lib/src/bindings/mailmap.dart
View file

@ -5,10 +5,11 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Allocate a new mailmap object.
/// Allocate a new mailmap object. The returned mailmap must be freed with
/// [free].
///
/// This object is empty, so you'll have to add a mailmap file before you can
/// do anything with it. The mailmap must be freed with `free()`.
/// do anything with it.
Pointer<git_mailmap> init() {
final out = calloc<Pointer<git_mailmap>>();
libgit2.git_mailmap_new(out);
@ -20,7 +21,8 @@ Pointer<git_mailmap> init() {
return result;
}
/// Create a new mailmap instance containing a single mailmap file.
/// Create a new mailmap instance containing a single mailmap file. The
/// returned mailmap must be freed with [free].
Pointer<git_mailmap> fromBuffer(String buffer) {
final out = calloc<Pointer<git_mailmap>>();
final bufferC = buffer.toNativeUtf8().cast<Int8>();
@ -36,7 +38,8 @@ Pointer<git_mailmap> fromBuffer(String buffer) {
}
/// Create a new mailmap instance from a repository, loading mailmap files based
/// on the repository's configuration.
/// on the repository's configuration. The returned mailmap must be freed with
/// [free].
///
/// Mailmaps are loaded in the following order:
///
@ -89,7 +92,8 @@ List<String> resolve({
return [realName, realEmail];
}
/// Resolve a signature to use real names and emails with a mailmap.
/// Resolve a signature to use real names and emails with a mailmap. The
/// returned signature must be freed.
Pointer<git_signature> resolveSignature({
required Pointer<git_mailmap> mailmapPointer,
required Pointer<git_signature> signaturePointer,

10
lib/src/bindings/merge.dart
View file

@ -119,6 +119,10 @@ List<int> analysis({
/// 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.
///
/// For compatibility with git, the repository is put into a merging state.
/// Once the commit is done (or if the user wishes to abort), that state should
/// be cleared by calling relative method.
void merge({
required Pointer<git_repository> repoPointer,
required Pointer<git_annotated_commit> theirHeadPointer,
@ -248,12 +252,12 @@ String mergeFileFromIndex({
}
}
/// Merge two commits, producing a git_index that reflects the result of the
/// Merge two commits, producing a git index that reflects the result of the
/// merge. The index may be written as-is to the working directory or checked
/// out. If the index is to be converted to a tree, the caller should resolve
/// any conflicts that arose as part of the merge.
///
/// The returned index must be freed explicitly.
/// The returned index must be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_index> mergeCommits({
@ -296,7 +300,7 @@ Pointer<git_index> mergeCommits({
/// out. If the index is to be converted to a tree, the caller should resolve
/// any conflicts that arose as part of the merge.
///
/// The returned index must be freed explicitly.
/// The returned index must be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_index> mergeTrees({

13
lib/src/bindings/note.dart
View file

@ -5,9 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Returns list of notes for repository.
///
/// Notes must be freed manually by the user.
/// Returns list of notes for repository. The returned notes must be freed with
/// [free].
///
/// Throws a [LibGit2Error] if error occured.
List<Map<String, Pointer>> list(Pointer<git_repository> repo) {
@ -49,9 +48,7 @@ List<Map<String, Pointer>> list(Pointer<git_repository> repo) {
return result;
}
/// Read the note for an object.
///
/// The note must be freed manually by the user.
/// Read the note for an object. The returned note must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_note> lookup({
@ -80,7 +77,7 @@ Pointer<git_note> lookup({
/// Throws a [LibGit2Error] if error occured.
Pointer<git_oid> create({
required Pointer<git_repository> repoPointer,
String notesRef = 'refs/notes/commits',
required String notesRef,
required Pointer<git_signature> authorPointer,
required Pointer<git_signature> committerPointer,
required Pointer<git_oid> oidPointer,
@ -118,7 +115,7 @@ Pointer<git_oid> create({
/// Throws a [LibGit2Error] if error occured.
void delete({
required Pointer<git_repository> repoPointer,
String notesRef = 'refs/notes/commits',
required String notesRef,
required Pointer<git_signature> authorPointer,
required Pointer<git_signature> committerPointer,
required Pointer<git_oid> oidPointer,

6
lib/src/bindings/object.dart
View file

@ -8,10 +8,8 @@ import 'package:libgit2dart/src/util.dart';
/// Get the object type of an object.
int type(Pointer<git_object> obj) => libgit2.git_object_type(obj);
/// Lookup a reference to one of the objects in a repository.
///
/// The generated reference is owned by the repository and should be closed with
/// the `free()` method instead of free'd manually.
/// Lookup a reference to one of the objects in a repository. The returned
/// reference must be freed with [free].
///
/// The 'type' parameter must match the type of the object in the odb; the
/// method will fail otherwise. The special value 'GIT_OBJECT_ANY' may be

25
lib/src/bindings/odb.dart
View file

@ -7,7 +7,8 @@ import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/oid.dart';
import 'package:libgit2dart/src/util.dart';
/// Create a new object database with no backends.
/// Create a new object database with no backends. The returned odb must be
/// freed with [free].
///
/// Before the ODB can be used for read/writing, a custom database backend must be
/// manually added.
@ -110,13 +111,11 @@ List<Oid> objects(Pointer<git_odb> odb) {
return result;
}
/// Read an object from the database.
/// Read an object from the database. The returned object must be freed with
/// [freeObject].
///
/// This method queries all available ODB backends trying to read the given OID.
///
/// The returned object is reference counted and internally cached, so it
/// should be closed by the user once it's no longer in use.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_odb_object> read({
required Pointer<git_odb> odbPointer,
@ -164,14 +163,6 @@ int objectSize(Pointer<git_odb_object> object) {
return libgit2.git_odb_object_size(object);
}
/// Close an ODB object.
///
/// This method must always be called once a odb object is no longer needed,
/// otherwise memory will leak.
void objectFree(Pointer<git_odb_object> object) {
libgit2.git_odb_object_free(object);
}
/// Write raw data into the object database.
///
/// Throws a [LibGit2Error] if error occured.
@ -208,3 +199,11 @@ Pointer<git_oid> write({
/// Close an open object database.
void free(Pointer<git_odb> db) => libgit2.git_odb_free(db);
/// Close an ODB object.
///
/// This method must always be called once a odb object is no longer needed,
/// otherwise memory will leak.
void freeObject(Pointer<git_odb_object> object) {
libgit2.git_odb_object_free(object);
}

3
lib/src/bindings/packbuilder.dart
View file

@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Initialize a new packbuilder.
/// Initialize a new packbuilder. The returned packbuilder must be freed with
/// [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_packbuilder> init(Pointer<git_repository> repo) {

23
lib/src/bindings/patch.dart
View file

@ -5,10 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Directly generate a patch from the difference between two buffers.
///
/// You can use the standard patch accessor functions to read the patch data,
/// and you must free the patch when done.
/// Directly generate a patch from the difference between two buffers. The
/// returned patch must be freed with [free].
Pointer<git_patch> fromBuffers({
String? oldBuffer,
String? oldAsPath,
@ -55,10 +53,8 @@ Pointer<git_patch> fromBuffers({
return result;
}
/// Directly generate a patch from the difference between two blobs.
///
/// You can use the standard patch accessor functions to read the patch data,
/// and you must free the patch when done.
/// Directly generate a patch from the difference between two blobs. The
/// returned patch must be freed with [free].
Pointer<git_patch> fromBlobs({
required Pointer<git_blob>? oldBlobPointer,
String? oldAsPath,
@ -97,9 +93,7 @@ Pointer<git_patch> fromBlobs({
}
/// Directly generate a patch from the difference between a blob and a buffer.
///
/// You can use the standard patch accessor functions to read the patch data,
/// and you must free the patch when done.
/// The returned patch must be freed with [free].
Pointer<git_patch> fromBlobAndBuffer({
Pointer<git_blob>? oldBlobPointer,
String? oldAsPath,
@ -143,11 +137,8 @@ Pointer<git_patch> fromBlobAndBuffer({
return result;
}
/// Return a patch for an entry in the diff list.
///
/// The newly created patch object contains the text diffs for the delta. You
/// have to call [free] when you are done with it. You can use the patch object
/// to loop over all the hunks and lines in the diff of the one delta.
/// Return a patch for an entry in the diff list. The returned patch must be
/// freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_patch> fromDiff({

7
lib/src/bindings/rebase.dart
View file

@ -7,8 +7,8 @@ import 'package:libgit2dart/src/util.dart';
/// Initializes a rebase operation to rebase the changes in [branchPointer]
/// relative to [upstreamPointer] onto [ontoPointer] another branch. To begin
/// the rebase process, call [next]. When you have finished with this object,
/// call [free].
/// the rebase process, call [next]. The returned rebase must be freed with
/// [free].
///
/// [branchPointer] is the terminal commit to rebase, or null to rebase the
/// current branch.
@ -53,7 +53,8 @@ Pointer<git_rebase> init({
}
/// Opens an existing rebase that was previously started by either an
/// invocation of [init] or by another client.
/// invocation of [init] or by another client. The returned rebase must be
/// freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_rebase> open(Pointer<git_repository> repo) {

31
lib/src/bindings/reference.dart
View file

@ -23,10 +23,10 @@ Pointer<git_oid> target(Pointer<git_reference> ref) =>
/// This method iteratively peels a symbolic reference until it resolves
/// to a direct reference to an OID.
///
/// The peeled reference must be freed manually once it's no longer needed.
///
/// If a direct reference is passed as an argument, a copy of that reference is
/// returned. This copy must be manually freed too.
/// returned.
///
/// The returned reference must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_reference> resolve(Pointer<git_reference> ref) {
@ -44,9 +44,8 @@ Pointer<git_reference> resolve(Pointer<git_reference> ref) {
}
}
/// Lookup a reference by name in a repository.
///
/// The returned reference must be freed by the user.
/// Lookup a reference by name in a repository. The returned reference must be
/// freed with [free].
///
/// The name will be checked for validity.
///
@ -84,7 +83,8 @@ String shorthand(Pointer<git_reference> ref) {
return libgit2.git_reference_shorthand(ref).cast<Utf8>().toDartString();
}
/// Rename an existing reference.
/// Rename an existing reference. The returned reference must be freed with
/// [free].
///
/// This method works for both direct and symbolic references.
///
@ -203,7 +203,8 @@ bool isTag(Pointer<git_reference> ref) {
return libgit2.git_reference_is_tag(ref) == 1 || false;
}
/// Create a new direct reference.
/// Create a new direct reference and write it to the disk. The returned
/// reference must be freed with [free].
///
/// A direct reference (also called an object id reference) refers directly to a
/// specific object id (a.k.a. OID or SHA) in the repository. The id
@ -211,9 +212,6 @@ bool isTag(Pointer<git_reference> ref) {
/// moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" refers
/// to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
///
/// The direct reference will be created in the repository and written to the
/// disk. The generated reference object must be freed by the user.
///
/// Valid reference names must follow one of two patterns:
///
/// Top-level names must contain only capital letters and underscores, and
@ -264,16 +262,14 @@ Pointer<git_reference> createDirect({
}
}
/// Create a new symbolic reference.
/// Create a new symbolic reference and write it to the disk. The returned
/// reference must be freed with [free].
///
/// A symbolic reference is a reference name that refers to another reference
/// name. If the other name moves, the symbolic name will move, too. As a
/// simple example, the "HEAD" reference might refer to "refs/heads/master"
/// while on the "master" branch of a repository.
///
/// The symbolic reference will be created in the repository and written to the
/// disk. The generated reference object must be freed by the user.
///
/// Valid reference names must follow one of two patterns:
///
/// Top-level names must contain only capital letters and underscores, and must
@ -343,6 +339,7 @@ Pointer<git_repository> owner(Pointer<git_reference> ref) {
/// reference, otherwise this will fail.
///
/// The new reference will be written to disk, overwriting the given reference.
/// The returned reference must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_reference> setTarget({
@ -376,6 +373,7 @@ Pointer<git_reference> setTarget({
/// otherwise this will fail.
///
/// The new reference will be written to disk, overwriting the given reference.
/// The returned reference must be freed with [free].
///
/// The target name will be checked for validity.
///
@ -447,7 +445,8 @@ Pointer<git_object> peel({
}
}
/// Create a copy of an existing reference.
/// Create a copy of an existing reference. The returned reference must be
/// freed with [free].
Pointer<git_reference> duplicate(Pointer<git_reference> source) {
final out = calloc<Pointer<git_reference>>();
libgit2.git_reference_dup(out, source);

9
lib/src/bindings/reflog.dart
View file

@ -5,12 +5,11 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Read the reflog for the given reference.
/// Read the reflog for the given reference. The returned reflog must be
/// freed with [free].
///
/// If there is no reflog file for the given reference yet, an empty reflog
/// object will be returned.
///
/// The reflog must be freed manually.
Pointer<git_reflog> read({
required Pointer<git_repository> repoPointer,
required String name,
@ -29,6 +28,8 @@ Pointer<git_reflog> read({
/// Write an existing in-memory reflog object back to disk using an atomic file
/// lock.
///
/// Throws a [LibGit2Error] if error occured.
void write(Pointer<git_reflog> reflog) {
final error = libgit2.git_reflog_write(reflog);
@ -132,7 +133,7 @@ String entryMessage(Pointer<git_reflog_entry> entry) {
return result == nullptr ? '' : result.cast<Utf8>().toDartString();
}
/// Get the committer of this entry.
/// Get the committer of this entry. The returned signature must be freed.
Pointer<git_signature> entryCommiter(Pointer<git_reflog_entry> entry) {
return libgit2.git_reflog_entry_committer(entry);
}

9
lib/src/bindings/remote.dart
View file

@ -23,7 +23,8 @@ List<String> list(Pointer<git_repository> repo) {
return result;
}
/// Get the information for a particular remote.
/// Get the information for a particular remote. The returned remote must be
/// freed with [free].
///
/// The name will be checked for validity.
///
@ -49,7 +50,7 @@ Pointer<git_remote> lookup({
}
/// Add a remote with the default fetch refspec to the repository's
/// configuration.
/// configuration. The returned remote must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_remote> create({
@ -76,7 +77,7 @@ Pointer<git_remote> create({
}
/// Add a remote with the provided fetch refspec to the repository's
/// configuration.
/// configuration. The returned remote must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_remote> createWithFetchSpec({
@ -551,7 +552,7 @@ void prune({
/// Free the memory associated with a remote.
///
/// This also disconnects from the remote, if the connection has not been closed
/// yet (using `disconnect()`).
/// yet (using [disconnect]).
void free(Pointer<git_remote> remote) => libgit2.git_remote_free(remote);
/// Initializes git_proxy_options structure.

40
lib/src/bindings/repository.dart
View file

@ -9,7 +9,8 @@ import 'package:libgit2dart/src/remote.dart';
import 'package:libgit2dart/src/repository.dart';
import 'package:libgit2dart/src/util.dart';
/// Attempt to open an already-existing repository at [path].
/// Attempt to open an already-existing repository at [path]. The returned
/// repository must be freed with [free].
///
/// The [path] can point to either a normal or bare repository.
///
@ -59,7 +60,8 @@ String discover({
return result;
}
/// Creates a new Git repository in the given folder.
/// Creates a new Git repository in the given folder. The returned repository
/// must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_repository> init({
@ -113,7 +115,8 @@ Pointer<git_repository> init({
}
}
/// Clone a remote repository.
/// Clone a remote repository. The returned repository must be freed with
/// [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_repository> clone({
@ -247,10 +250,8 @@ bool isEmpty(Pointer<git_repository> repo) {
}
}
/// Retrieve and resolve the reference pointed at by HEAD.
///
/// The returned `git_reference` will be owned by caller and must be freed
/// to release the allocated memory and prevent a leak.
/// Retrieve and resolve the reference pointed at by HEAD. The returned
/// reference must be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_reference> head(Pointer<git_repository> repo) {
@ -339,14 +340,12 @@ Map<String, String> identity(Pointer<git_repository> repo) {
return identity;
}
/// Get the configuration file for this repository.
/// Get the configuration file for this repository. The returned config must be
/// freed.
///
/// If a configuration file has not been set, the default config set for the
/// repository will be returned, including global and system configurations (if
/// they are available).
///
/// The configuration file must be freed once it's no longer being used by the
/// user.
Pointer<git_config> config(Pointer<git_repository> repo) {
final out = calloc<Pointer<git_config>>();
libgit2.git_repository_config(out, repo);
@ -358,14 +357,12 @@ Pointer<git_config> config(Pointer<git_repository> repo) {
return result;
}
/// Get a snapshot of the repository's configuration.
/// Get a snapshot of the repository's configuration. The returned config must
/// be freed.
///
/// Convenience function to take a snapshot from the repository's configuration.
/// The contents of this snapshot will not change, even if the underlying
/// config files are modified.
///
/// The configuration file must be freed once it's no longer being used by the
/// user.
Pointer<git_config> configSnapshot(Pointer<git_repository> repo) {
final out = calloc<Pointer<git_config>>();
libgit2.git_repository_config_snapshot(out, repo);
@ -377,12 +374,10 @@ Pointer<git_config> configSnapshot(Pointer<git_repository> repo) {
return result;
}
/// Get the Index file for this repository.
/// Get the Index file for this repository. The returned index must be freed.
///
/// If a custom index has not been set, the default index for the repository
/// will be returned (the one located in `.git/index`).
///
/// The index must be freed once it's no longer being used.
Pointer<git_index> index(Pointer<git_repository> repo) {
final out = calloc<Pointer<git_index>>();
libgit2.git_repository_index(out, repo);
@ -437,13 +432,11 @@ void removeMessage(Pointer<git_repository> repo) {
libgit2.git_repository_message_remove(repo);
}
/// Get the Object Database for this repository.
/// Get the Object Database for this repository. The returned odb must be freed.
///
/// If a custom ODB has not been set, the default database for the repository
/// will be returned (the one located in `.git/objects`).
///
/// The ODB must be freed once it's no longer being used.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_odb> odb(Pointer<git_repository> repo) {
final out = calloc<Pointer<git_odb>>();
@ -460,14 +453,13 @@ Pointer<git_odb> odb(Pointer<git_repository> repo) {
}
}
/// Get the Reference Database Backend for this repository.
/// Get the Reference Database Backend for this repository. The returned refdb
/// must be freed.
///
/// If a custom refsdb has not been set, the default database for the repository
/// will be returned (the one that manipulates loose and packed references in
/// the `.git` directory).
///
/// The refdb must be freed once it's no longer being used.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_refdb> refdb(Pointer<git_repository> repo) {
final out = calloc<Pointer<git_refdb>>();

4
lib/src/bindings/revparse.dart
View file

@ -34,7 +34,7 @@ Pointer<git_revspec> revParse({
/// See `man gitrevisions`, or https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
/// for information on the syntax accepted.
///
/// The returned object should be released when no longer needed.
/// The returned object should be freed.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_object> revParseSingle({
@ -67,7 +67,7 @@ Pointer<git_object> revParseSingle({
/// point to an intermediate reference. When such expressions are being passed
/// in, reference_out will be valued as well.
///
/// The returned object and reference should be released when no longer needed.
/// The returned object and reference should be freed.
///
/// Throws a [LibGit2Error] if error occured.
List<Pointer> revParseExt({

6
lib/src/bindings/revwalk.dart
View file

@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Allocate a new revision walker to iterate through a repo.
/// Allocate a new revision walker to iterate through a repo. The returned
/// revision walker must be freed with [free].
///
/// This revision walker uses a custom memory pool and an internal commit cache,
/// so it is relatively expensive to allocate.
@ -128,7 +129,8 @@ void pushRange({
}
}
/// Get the list of commits from the revision walk.
/// Get the list of commits from the revision walk. The returned commits must
/// be freed.
///
/// The initial call to this method is not blocking when iterating through a
/// repo with a time-sorting mode.

12
lib/src/bindings/signature.dart
View file

@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Create a new action signature.
/// Create a new action signature. The returned signature must be freed with
/// [free].
///
/// Note: angle brackets ('<' and '>') characters are not allowed to be used in
/// either the name or the email parameter.
@ -35,7 +36,8 @@ Pointer<git_signature> create({
}
}
/// Create a new action signature with a timestamp of 'now'.
/// Create a new action signature with a timestamp of 'now'. The returned
/// signature must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_signature> now({required String name, required String email}) {
@ -57,7 +59,8 @@ Pointer<git_signature> now({required String name, required String email}) {
}
}
/// Create a new action signature with default user and now timestamp.
/// Create a new action signature with default user and now timestamp. The
/// returned signature must be freed with [free].
///
/// This looks up the user.name and user.email from the configuration and uses
/// the current time as the timestamp, and creates a new signature based on
@ -73,7 +76,8 @@ Pointer<git_signature> defaultSignature(Pointer<git_repository> repo) {
return result;
}
/// Create a copy of an existing signature.
/// Create a copy of an existing signature. The returned signature must be
/// freed with [free].
Pointer<git_signature> duplicate(Pointer<git_signature> sig) {
final out = calloc<Pointer<git_signature>>();
libgit2.git_signature_dup(out, sig);

3
lib/src/bindings/status.dart
View file

@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Gather file status information and populate the git_status_list.
/// Gather file status information and populate the git_status_list. The
/// returned list must be freed with [listFree].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_status_list> listNew(Pointer<git_repository> repo) {

10
lib/src/bindings/submodule.dart
View file

@ -38,13 +38,12 @@ List<String> list(Pointer<git_repository> repo) {
return result;
}
/// Lookup submodule information by name or path.
/// Lookup submodule information by name or path. The returned submodule must
/// be freed with [free].
///
/// Given either the submodule name or path (they are usually the same), this
/// returns a structure describing the submodule.
///
/// You must call [free] when done with the submodule.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_submodule> lookup({
required Pointer<git_repository> repoPointer,
@ -67,7 +66,7 @@ Pointer<git_submodule> lookup({
}
}
/// Copy submodule info into ".git/config" file.
/// Copy submodule info into `.git/config` file.
///
/// Just like `git submodule init`, this copies information about the
/// submodule into `.git/config`.
@ -143,7 +142,8 @@ Pointer<git_repository> open(Pointer<git_submodule> submodule) {
}
}
/// Set up a new git submodule for checkout.
/// Set up a new git submodule for checkout. The returned submodule must be
/// freed with [free].
///
/// This does `git submodule add` up to the fetch and checkout of the submodule
/// contents. It preps a new submodule, creates an entry in `.gitmodules` and

5
lib/src/bindings/tag.dart
View file

@ -26,7 +26,8 @@ List<String> list(Pointer<git_repository> repo) {
}
}
/// Lookup a tag object from the repository.
/// Lookup a tag object from the repository. The returned tag must be freed
/// with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_tag> lookup({
@ -88,7 +89,7 @@ String message(Pointer<git_tag> tag) {
return result == nullptr ? '' : result.cast<Utf8>().toDartString();
}
/// Get the tagger (author) of a tag.
/// Get the tagger (author) of a tag. The returned signature must be freed.
Pointer<git_signature> tagger(Pointer<git_tag> tag) =>
libgit2.git_tag_tagger(tag);

7
lib/src/bindings/tree.dart
View file

@ -8,7 +8,8 @@ import 'package:libgit2dart/src/util.dart';
/// Get the id of a tree.
Pointer<git_oid> id(Pointer<git_tree> tree) => libgit2.git_tree_id(tree);
/// Lookup a tree object from the repository.
/// Lookup a tree object from the repository. The returned tree must be freed
/// with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_tree> lookup({
@ -74,7 +75,7 @@ Pointer<git_tree_entry> getByName({
/// its relative path.
///
/// Unlike the other lookup functions, the returned tree entry is owned by the
/// user and must be freed explicitly with [entryFree].
/// user and must be freed explicitly with [freeEntry].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_tree_entry> getByPath({
@ -116,7 +117,7 @@ int entryFilemode(Pointer<git_tree_entry> entry) =>
///
/// IMPORTANT: This function is only needed for tree entries owned by the user,
/// such as [getByPath].
void entryFree(Pointer<git_tree_entry> entry) =>
void freeEntry(Pointer<git_tree_entry> entry) =>
libgit2.git_tree_entry_free(entry);
/// Close an open tree to release memory.

9
lib/src/bindings/treebuilder.dart
View file

@ -5,17 +5,12 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Create a new tree builder.
/// Create a new tree builder. The returned tree builder must be freed with
/// [free].
///
/// The tree builder can be used to create or modify trees in memory and write
/// them as tree objects to the database.
///
/// If the source parameter is not null, the tree builder will be initialized
/// with the entries of the given tree.
///
/// If the source parameter is null, the tree builder will start with no entries
/// and will have to be filled manually.
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_treebuilder> create({
required Pointer<git_repository> repoPointer,

5
lib/src/bindings/worktree.dart
View file

@ -6,7 +6,7 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
import 'package:libgit2dart/src/error.dart';
import 'package:libgit2dart/src/util.dart';
/// Add a new working tree.
/// Add a new working tree. The returned worktree must be freed with [free].
///
/// Add a new working tree for the repository, that is create the required
/// data structures inside the repository and check out the current HEAD at
@ -47,7 +47,8 @@ Pointer<git_worktree> create({
}
}
/// Lookup a working tree by its name for a given repository.
/// Lookup a working tree by its name for a given repository. The returned
/// worktree must be freed with [free].
///
/// Throws a [LibGit2Error] if error occured.
Pointer<git_worktree> lookup({

4
lib/src/blob.dart
View file

@ -7,6 +7,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
class Blob {
/// Initializes a new instance of [Blob] class from provided pointer to
/// blob object in memory.
///
/// Note: For internal use. Use [Blob.lookup] instead.
Blob(this._blobPointer) {
_finalizer.attach(this, _blobPointer, detach: this);
}
@ -23,6 +25,8 @@ class Blob {
late final Pointer<git_blob> _blobPointer;
/// Pointer to memory address for allocated blob object.
///
/// Note: For internal use.
Pointer<git_blob> get pointer => _blobPointer;
/// Creates a new blob from a [content] string and writes it to ODB.

6
lib/src/branch.dart
View file

@ -8,6 +8,10 @@ import 'package:libgit2dart/src/bindings/reference.dart' as reference_bindings;
class Branch {
/// Initializes a new instance of [Branch] class from provided pointer to
/// branch object in memory.
///
/// Note: For internal use. Instead, use one of:
/// - [Branch.create]
/// - [Branch.lookup]
Branch(this._branchPointer) {
_finalizer.attach(this, _branchPointer, detach: this);
}
@ -65,6 +69,8 @@ class Branch {
late final Pointer<git_reference> _branchPointer;
/// Pointer to memory address for allocated branch object.
///
/// Note: For internal use.
Pointer<git_reference> get pointer => _branchPointer;
/// Returns a list of branches that can be found in a [repo]sitory for

12
lib/src/commit.dart
View file

@ -8,6 +8,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
class Commit {
/// Initializes a new instance of [Commit] class from provided pointer to
/// commit object in memory.
///
/// Note: For internal use. Use [Commit.lookup] instead.
Commit(this._commitPointer) {
_finalizer.attach(this, _commitPointer, detach: this);
}
@ -24,6 +26,8 @@ class Commit {
late final Pointer<git_commit> _commitPointer;
/// Pointer to memory address for allocated commit object.
///
/// Note: For internal use.
Pointer<git_commit> get pointer => _commitPointer;
/// Creates new commit in the [repo]sitory.
@ -45,7 +49,9 @@ class Commit {
/// represented with a standard encoding name. E.g. "UTF-8". If null, no
/// encoding header is written and UTF-8 is assumed.
///
/// [message] is the full message for this commit.
/// [message] is the full message for this commit. It will not be cleaned up
/// automatically. I.e. excess whitespace will not be removed and no trailing
/// newline will be added.
///
/// [tree] is an instance of a [Tree] object that will be used as the tree
/// for the commit. This tree object must also be owned by the given [repo].
@ -208,8 +214,10 @@ class Commit {
);
}
/// Wncoding for the message of a commit, as a string representing a standard
/// Encoding for the message of a commit, as a string representing a standard
/// encoding name.
///
/// If the encoding header in the commit is missing UTF-8 is assumed.
String get messageEncoding => bindings.messageEncoding(_commitPointer);
/// Full message of a commit.

10
lib/src/config.dart
View file

@ -11,6 +11,12 @@ import 'package:libgit2dart/src/util.dart';
class Config with IterableMixin<ConfigEntry> {
/// Initializes a new instance of [Config] class from provided
/// pointer to config object in memory.
///
/// Note: For internal use. Instead, use one of:
/// - [Config.open]
/// - [Config.system]
/// - [Config.global]
/// - [Config.xdg]
Config(this._configPointer) {
_finalizer.attach(this, _configPointer, detach: this);
}
@ -145,6 +151,10 @@ class Config with IterableMixin<ConfigEntry> {
///
/// If [regexp] is present, then the iterator will only iterate over all
/// values which match the pattern.
///
/// The regular expression is applied case-sensitively on the normalized form
/// of the variable name: the section and variable parts are lower-cased. The
/// subsection is left unchanged.
List<String> multivar({required String variable, String? regexp}) {
return bindings.multivarValues(
configPointer: _configPointer,

17
lib/src/diff.dart
View file

@ -9,6 +9,15 @@ import 'package:libgit2dart/src/util.dart';
class Diff {
/// Initializes a new instance of [Diff] class from provided
/// pointer to diff object in memory.
///
/// Note: For internal use. Instead, use one of:
/// - [Diff.indexToWorkdir]
/// - [Diff.indexToIndex]
/// - [Diff.treeToIndex]
/// - [Diff.treeToWorkdir]
/// - [Diff.treeToWorkdirWithIndex]
/// - [Diff.treeToTree]
/// - [Diff.parse]
Diff(this._diffPointer) {
_finalizer.attach(this, _diffPointer, detach: this);
}
@ -262,6 +271,8 @@ class Diff {
late final Pointer<git_diff> _diffPointer;
/// Pointer to memory address for allocated diff object.
///
/// Note: For internal use.
Pointer<git_diff> get pointer => _diffPointer;
/// How many diff records are there in a diff.
@ -554,6 +565,8 @@ class DiffFile {
class DiffStats {
/// Initializes a new instance of [DiffStats] class from provided
/// pointer to diff stats object in memory.
///
/// Note: For internal use.
DiffStats(this._diffStatsPointer) {
_statsFinalizer.attach(this, _diffStatsPointer, detach: this);
}
@ -585,7 +598,7 @@ class DiffStats {
/// Releases memory allocated for diff stats object.
void free() {
bindings.statsFree(_diffStatsPointer);
bindings.freeStats(_diffStatsPointer);
_statsFinalizer.detach(this);
}
@ -598,6 +611,6 @@ class DiffStats {
// coverage:ignore-start
final _statsFinalizer = Finalizer<Pointer<git_diff_stats>>(
(pointer) => bindings.statsFree(pointer),
(pointer) => bindings.freeStats(pointer),
);
// coverage:ignore-end

10
lib/src/index.dart
View file

@ -9,6 +9,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
class Index with IterableMixin<IndexEntry> {
/// Initializes a new instance of [Index] class from provided
/// pointer to index object in memory.
///
/// Note: For internal use.
Index(this._indexPointer) {
_finalizer.attach(this, _indexPointer, detach: this);
}
@ -25,6 +27,8 @@ class Index with IterableMixin<IndexEntry> {
late final Pointer<git_index> _indexPointer;
/// Pointer to memory address for allocated index object.
///
/// Note: For internal use.
Pointer<git_index> get pointer => _indexPointer;
/// Full path to the index file on disk.
@ -321,11 +325,15 @@ final _finalizer = Finalizer<Pointer<git_index>>(
class IndexEntry {
/// Initializes a new instance of [IndexEntry] class.
///
/// Note: For internal use.
const IndexEntry(this._indexEntryPointer);
final Pointer<git_index_entry> _indexEntryPointer;
/// Pointer to memory address for allocated index entry object.
///
/// Note: For internal use.
Pointer<git_index_entry> get pointer => _indexEntryPointer;
/// [Oid] of the index entry.
@ -363,6 +371,8 @@ class IndexEntry {
class ConflictEntry {
/// Initializes a new instance of [ConflictEntry] class.
///
/// Note: For internal use.
const ConflictEntry(
this._indexPointer,
this._path,

4
lib/src/merge.dart
View file

@ -82,6 +82,10 @@ class Merge {
/// are written to the index. Callers should inspect the repository's index
/// after this completes, resolve any conflicts and prepare a commit.
///
/// For compatibility with git, the repository is put into a merging state.
/// Once the commit is done (or if the user wishes to abort), that state
/// should be cleared by calling [stateCleanup] method of [Repository] object.
///
/// [repo] is the repository to merge.
///
/// [commit] is the commit to merge.

3
lib/src/note.dart
View file

@ -6,6 +6,8 @@ import 'package:libgit2dart/src/bindings/note.dart' as bindings;
class Note {
/// Initializes a new instance of the [Note] class from provided
/// pointer to note and annotatedOid objects in memory.
///
/// Note: For internal use. Use [Note.lookup] instead.
Note(this._notePointer, this._annotatedOidPointer) {
_finalizer.attach(this, _notePointer, detach: this);
}
@ -100,6 +102,7 @@ class Note {
}) {
bindings.delete(
repoPointer: repo.pointer,
notesRef: notesRef,
authorPointer: author.pointer,
committerPointer: committer.pointer,
oidPointer: annotatedOid.pointer,

8
lib/src/odb.dart
View file

@ -7,6 +7,8 @@ import 'package:libgit2dart/src/util.dart';
class Odb {
/// Initializes a new instance of [Odb] class from provided
/// pointer to Odb object in memory.
///
/// Note: For internal use.
Odb(this._odbPointer) {
_finalizer.attach(this, _odbPointer, detach: this);
}
@ -25,6 +27,8 @@ class Odb {
late final Pointer<git_odb> _odbPointer;
/// Pointer to memory address for allocated oid object.
///
/// Note: For internal use.
Pointer<git_odb> get pointer => _odbPointer;
/// Adds an on-disk alternate to an existing Object DB.
@ -132,7 +136,7 @@ class OdbObject {
/// Releases memory allocated for odbObject object.
void free() {
bindings.objectFree(_odbObjectPointer);
bindings.freeObject(_odbObjectPointer);
_objectfinalizer.detach(this);
}
@ -144,6 +148,6 @@ class OdbObject {
// coverage:ignore-start
final _objectfinalizer = Finalizer<Pointer<git_odb_object>>(
(pointer) => bindings.objectFree(pointer),
(pointer) => bindings.freeObject(pointer),
);
// coverage:ignore-end

4
lib/src/oid.dart
View file

@ -11,6 +11,8 @@ import 'package:meta/meta.dart';
class Oid {
/// Initializes a new instance of [Oid] class from provided
/// pointer to Oid object in memory.
///
/// Note: For internal use. Use [Oid.fromSHA] instead.
Oid(this._oidPointer);
/// Initializes a new instance of [Oid] class by determining if an object can
@ -45,6 +47,8 @@ class Oid {
late final Pointer<git_oid> _oidPointer;
/// Pointer to memory address for allocated oid object.
///
/// Note: For internal use.
Pointer<git_oid> get pointer => _oidPointer;
/// Hexadecimal SHA string.

2
lib/src/packbuilder.dart
View file

@ -7,6 +7,8 @@ class PackBuilder {
/// Initializes a new instance of [PackBuilder] class.
///
/// Throws a [LibGit2Error] if error occured.
///
/// Note: For internal use.
PackBuilder(Repository repo) {
_packbuilderPointer = bindings.init(repo.pointer);
_finalizer.attach(this, _packbuilderPointer, detach: this);

8
lib/src/patch.dart
View file

@ -9,6 +9,12 @@ import 'package:libgit2dart/src/util.dart';
class Patch {
/// Initializes a new instance of [Patch] class from provided
/// pointer to patch object in memory and pointers to old and new blobs/buffers.
///
/// Note: For internal use. Instead, use one of:
/// - [Patch.fromBlobs]
/// - [Patch.fromBlobAndBuffer]
/// - [Patch.fromBuffers]
/// - [Patch.fromDiff]
Patch(this._patchPointer) {
_finalizer.attach(this, _patchPointer, detach: this);
}
@ -151,6 +157,8 @@ class Patch {
late final Pointer<git_patch> _patchPointer;
/// Line counts of each type in a patch.
///
/// This helps imitate a `diff --numstat` type of output.
PatchStats get stats {
final result = bindings.lineStats(_patchPointer);

6
lib/src/reference.dart
View file

@ -10,6 +10,10 @@ import 'package:libgit2dart/src/bindings/repository.dart'
class Reference {
/// Initializes a new instance of the [Reference] class.
///
/// Note: For internal use. Instead, use one of:
/// - [Reference.create]
/// - [Reference.lookup]
Reference(this._refPointer) {
_finalizer.attach(this, _refPointer, detach: this);
}
@ -78,6 +82,8 @@ class Reference {
late Pointer<git_reference> _refPointer;
/// Pointer to memory address for allocated reference object.
///
/// Note: For internal use.
Pointer<git_reference> get pointer => _refPointer;
/// Deletes an existing reference with provided [name].

2
lib/src/reflog.dart
View file

@ -85,6 +85,8 @@ class RefLog with IterableMixin<RefLogEntry> {
/// Writes an existing in-memory reflog object back to disk using an atomic
/// file lock.
///
/// Throws a [LibGit2Error] if error occured.
void write() => bindings.write(_reflogPointer);
/// Releases memory allocated for reflog object.

2
lib/src/refspec.dart
View file

@ -6,6 +6,8 @@ import 'package:libgit2dart/src/bindings/refspec.dart' as bindings;
class Refspec {
/// Initializes a new instance of the [Refspec] class
/// from provided pointer to refspec object in memory.
///
/// Note: For internal use.
const Refspec(this._refspecPointer);
/// Pointer to memory address for allocated refspec object.

2
lib/src/remote.dart
View file

@ -317,6 +317,8 @@ final _finalizer = Finalizer<Pointer<git_remote>>(
class TransferProgress {
/// Initializes a new instance of [TransferProgress] class from provided
/// pointer to transfer progress object in memory.
///
/// Note: For internal use.
const TransferProgress(this._transferProgressPointer);
/// Pointer to memory address for allocated transfer progress object.

9
lib/src/repository.dart
View file

@ -18,6 +18,11 @@ class Repository {
/// pointer to repository object in memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Note: For internal use. Instead, use one of:
/// - [Repository.init]
/// - [Repository.open]
/// - [Repository.clone]
Repository(this._repoPointer);
/// Creates new git repository at the provided [path].
@ -151,6 +156,8 @@ class Repository {
late final Pointer<git_repository> _repoPointer;
/// Pointer to memory address for allocated repository object.
///
/// Note: For internal use.
Pointer<git_repository> get pointer => _repoPointer;
/// Looks for a git repository and return its path. The lookup start from
@ -686,7 +693,7 @@ class Repository {
dirtySuffix: dirtySuffix,
);
describe_bindings.describeResultFree(describeResult);
describe_bindings.free(describeResult);
return result;
}

2
lib/src/revwalk.dart
View file

@ -13,6 +13,8 @@ class RevWalk {
late final Pointer<git_revwalk> _revWalkPointer;
/// Pointer to memory address for allocated [RevWalk] object.
///
/// Note: For internal use.
Pointer<git_revwalk> get pointer => _revWalkPointer;
/// Returns the list of commits from the revision walk.

6
lib/src/signature.dart
View file

@ -10,6 +10,10 @@ import 'package:meta/meta.dart';
class Signature {
/// Initializes a new instance of [Signature] class from provided pointer to
/// signature object in memory.
///
/// Note: For internal use. Instead, use one of:
/// - [Signature.create]
/// - [Signature.defaultSignature]
Signature(Pointer<git_signature> pointer) {
_signaturePointer = bindings.duplicate(pointer);
_finalizer.attach(this, _signaturePointer, detach: this);
@ -54,6 +58,8 @@ class Signature {
late final Pointer<git_signature> _signaturePointer;
/// Pointer to memory address for allocated signature object.
///
/// Note: For internal use.
Pointer<git_signature> get pointer => _signaturePointer;
/// Full name of the author.

2
lib/src/tag.dart
View file

@ -8,6 +8,8 @@ import 'package:libgit2dart/src/bindings/tag.dart' as bindings;
class Tag {
/// Initializes a new instance of [Tag] class from provided pointer to
/// tag object in memory.
///
/// Note: For internal use. Use [Tag.lookup] instead.
Tag(this._tagPointer) {
_finalizer.attach(this, _tagPointer, detach: this);
}

10
lib/src/tree.dart
View file

@ -7,6 +7,8 @@ import 'package:libgit2dart/src/bindings/tree.dart' as bindings;
class Tree {
/// Initializes a new instance of [Tree] class from provided pointer to
/// tree object in memory.
///
/// Note: For internal use. Use [Tree.lookup] instead.
Tree(this._treePointer) {
_finalizer.attach(this, _treePointer, detach: this);
}
@ -23,6 +25,8 @@ class Tree {
late final Pointer<git_tree> _treePointer;
/// Pointer to memory address for allocated tree object.
///
/// Note: For internal use.
Pointer<git_tree> get pointer => _treePointer;
/// List with tree entries of a tree.
@ -109,6 +113,8 @@ final _finalizer = Finalizer<Pointer<git_tree>>(
class TreeEntry {
/// Initializes a new instance of [TreeEntry] class from provided pointer to
/// tree entry object in memory.
///
/// Note: For internal use.
TreeEntry(this._treeEntryPointer);
/// Initializes a new instance of [TreeEntry] class from provided pointer to
@ -138,7 +144,7 @@ class TreeEntry {
///
/// **IMPORTANT**: Only tree entries looked up by path should be freed.
void free() {
bindings.entryFree(_treeEntryPointer);
bindings.freeEntry(_treeEntryPointer);
_entryFinalizer.detach(this);
}
@ -148,6 +154,6 @@ class TreeEntry {
// coverage:ignore-start
final _entryFinalizer = Finalizer<Pointer<git_tree_entry>>(
(pointer) => bindings.entryFree(pointer),
(pointer) => bindings.freeEntry(pointer),
);
// coverage:ignore-end