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

docs: improve api documentation

Browse source
This commit is contained in:
Aleksey Kulikov 2021-10-22 14:41:15 +03:00
parent 199dce111a
commit a24070c44c
32 changed files with 1008 additions and 518 deletions
Download patch file Download diff file Expand all files Collapse all files

40
lib/src/blame.dart
View file

@ -6,10 +6,13 @@ import 'bindings/libgit2_bindings.dart';
import 'bindings/blame.dart' as bindings;
class Blame with IterableMixin<BlameHunk> {
/// Initializes a new instance of the [Blame] class by getting
/// the blame for a single file.
/// Returns the blame for a single file.
///
/// [flags] is a combination of [GitBlameFlag]s.
/// [repo] is the repository whose history is to be walked.
///
/// [path] is the path to file to consider.
///
/// [flags] is a combination of [GitBlameFlag]s. Defaults to [GitBlameFlag.normal].
///
/// [minMatchCharacters] is the lower bound on the number of alphanumeric
/// characters that must be detected as moving/copying within a file for
@ -28,6 +31,8 @@ class Blame with IterableMixin<BlameHunk> {
/// [maxLine] is the last line in the file to blame. The default is the last
/// line of the file.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Blame.file({
required Repository repo,
@ -64,7 +69,7 @@ class Blame with IterableMixin<BlameHunk> {
));
}
/// Gets the hunk that relates to the given line number (1-based) in the newest commit.
/// Returns the hunk that relates to the given line number (1-based) in the newest commit.
///
/// Throws [RangeError] if [lineNumber] is out of range.
BlameHunk forLine(int lineNumber) {
@ -89,43 +94,42 @@ class BlameHunk {
/// Pointer to memory address for allocated blame hunk object.
final Pointer<git_blame_hunk> _blameHunkPointer;
/// Returns the number of lines in this hunk.
/// Number of lines in this hunk.
int get linesCount => _blameHunkPointer.ref.lines_in_hunk;
/// Checks if the hunk has been tracked to a boundary commit
/// (the root, or the commit specified in [oldestCommit] argument)
/// Whether the hunk has been tracked to a boundary commit
/// (the root, or the commit specified in [oldestCommit] argument).
bool get isBoundary {
return _blameHunkPointer.ref.boundary == 1 ? true : false;
}
/// Returns the 1-based line number where this hunk begins, in the final
/// version of the file.
/// 1-based line number where this hunk begins, in the final version of the file.
int get finalStartLineNumber => _blameHunkPointer.ref.final_start_line_number;
/// Returns the author of [finalCommitOid]. If [GitBlameFlag.useMailmap] has been
/// Author of [finalCommitOid]. If [GitBlameFlag.useMailmap] has been
/// specified, it will contain the canonical real name and email address.
Signature get finalCommitter =>
Signature(_blameHunkPointer.ref.final_signature);
/// Returns the [Oid] of the commit where this line was last changed.
/// [Oid] of the commit where this line was last changed.
Oid get finalCommitOid => Oid.fromRaw(_blameHunkPointer.ref.final_commit_id);
/// Returns the 1-based line number where this hunk begins, in the file
/// named by [originPath] in the commit specified by [originCommitId].
/// 1-based line number where this hunk begins, in the file named by [originPath]
/// in the commit specified by [originCommitId].
int get originStartLineNumber => _blameHunkPointer.ref.orig_start_line_number;
/// Returns the author of [originCommitOid]. If [GitBlameFlag.useMailmap] has been
/// Author of [originCommitOid]. If [GitBlameFlag.useMailmap] has been
/// specified, it will contain the canonical real name and email address.
Signature get originCommitter =>
Signature(_blameHunkPointer.ref.orig_signature);
/// Returns the [Oid] of the commit where this hunk was found. This will usually be
/// the same as [finalCommitOid], except when [GitBlameFlag.trackCopiesAnyCommitCopies]
/// [Oid] of the commit where this hunk was found. This will usually be the same
/// as [finalCommitOid], except when [GitBlameFlag.trackCopiesAnyCommitCopies]
/// been specified.
Oid get originCommitOid => Oid.fromRaw(_blameHunkPointer.ref.orig_commit_id);
/// Returns the path to the file where this hunk originated, as of the commit
/// specified by [originCommitOid].
/// Path to the file where this hunk originated, as of the commit specified by
/// [originCommitOid].
String get originPath =>
_blameHunkPointer.ref.orig_path.cast<Utf8>().toDartString();

48
lib/src/blob.dart
View file

@ -8,12 +8,12 @@ class Blob {
/// Initializes a new instance of [Blob] class from provided pointer to
/// blob object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Blob(this._blobPointer);
/// Lookups a blob object for provided [oid] in a [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Blob.lookup({required Repository repo, required Oid oid}) {
_blobPointer = bindings.lookup(
repoPointer: repo.pointer,
@ -58,25 +58,39 @@ class Blob {
return Oid(bindings.createFromDisk(repoPointer: repo.pointer, path: path));
}
/// Returns the [Oid] of the blob.
/// [Oid] of the blob.
Oid get oid => Oid(bindings.id(_blobPointer));
/// Determines if the blob content is most certainly binary or not.
/// Whether the blob content is most certainly binary or not.
///
/// The heuristic used to guess if a file is binary is taken from core git:
/// Searching for NUL bytes and looking for a reasonable ratio of printable to
/// non-printable characters among the first 8000 bytes.
bool get isBinary => bindings.isBinary(_blobPointer);
/// Returns a read-only buffer with the raw content of a blob.
/// Read-only buffer with the raw content of a blob.
String get content => bindings.content(_blobPointer);
/// Returns the size in bytes of the contents of a blob.
/// Size in bytes of the contents of a blob.
int get size => bindings.size(_blobPointer);
/// Directly generate a [Patch] from the difference between two blobs.
/// Directly generates a [Patch] from the difference between two blobs.
///
/// Should be freed with `free()` to release allocated memory.
/// [newBlob] is the blob for new side of diff, or null for empty blob.
///
/// [oldAsPath] treat old blob as if it had this filename, can be null.
///
/// [newAsPath] treat new blob as if it had this filename, can be null.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Patch diff({
@ -104,9 +118,23 @@ class Blob {
);
}
/// Directly generate a [Patch] from the difference between the blob and a buffer.
/// Directly generates a [Patch] from the difference between the blob and a buffer.
///
/// Should be freed with `free()` to release allocated memory.
/// [buffer] is the raw data for new side of diff, or null for empty.
///
/// [oldAsPath] treat old blob as if it had this filename, can be null.
///
/// [bufferAsPath] treat buffer as if it had this filename, can be null.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Patch diffToBuffer({

37
lib/src/branch.dart
View file

@ -8,19 +8,22 @@ class Branch {
/// Initializes a new instance of [Branch] class from provided pointer to
/// branch object in memory.
///
/// Should be freed with [free] to release allocated memory when no longer
/// needed.
/// **IMPORTANT**: Should be freed to release allocated memory.
Branch(this._branchPointer);
/// Creates a new branch pointing at a [target] commit.
///
/// 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.
/// If [force] is true and a reference already exists with the given name,
/// it'll be replaced.
///
/// Should be freed with [free] to release allocated memory when no longer
/// needed.
/// [name] is the name for the branch, this name is validated for consistency.
/// It should also not conflict with an already existing branch name.
///
/// The branch name will be checked for validity.
/// [target] is the commit to which this branch should point. This object must
/// belong to the given [repo].
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Branch.create({
@ -44,7 +47,7 @@ class Branch {
/// If branch [type] is [GitBranch.remote] you must include the remote name
/// in the [name] (e.g. "origin/master").
///
/// Should be freed to release allocated memory when no longer needed.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Branch.lookup({
@ -67,7 +70,7 @@ class Branch {
/// Returns a list of branches that can be found in a [repo]sitory for provided [type].
/// Default is all branches (local and remote).
///
/// IMPORTANT: Branches must be freed manually when no longer needed to prevent
/// **IMPORTANT**: Branches must be freed manually when no longer needed to prevent
/// memory leak.
///
/// Throws a [LibGit2Error] if error occured.
@ -83,7 +86,7 @@ class Branch {
return pointers.map((e) => Branch(e)).toList();
}
/// Deletes an existing branch reference.
/// Deletes an existing branch reference with provided [name].
///
/// Throws a [LibGit2Error] if error occured.
static void delete({required Repository repo, required String name}) {
@ -92,9 +95,9 @@ class Branch {
branch.free();
}
/// Renames an existing local branch reference.
/// Renames an existing local branch reference with provided [oldName].
///
/// The new branch name will be checked for validity.
/// The new branch name [newName] will be checked for validity.
///
/// If [force] is true, existing branch will be overwritten.
///
@ -116,17 +119,17 @@ class Branch {
branch.free();
}
/// Returns the [Oid] pointed to by a branch.
/// [Oid] pointed to by a branch.
///
/// Throws an exception if error occured.
/// Throws an [Exception] if error occured.
Oid get target => Oid(reference_bindings.target(_branchPointer));
/// Checks if HEAD points to the given branch.
/// Whether HEAD points to the given branch.
///
/// Throws a [LibGit2Error] if error occured.
bool get isHead => bindings.isHead(_branchPointer);
/// Checks if any HEAD points to the current branch.
/// Whether any HEAD points to the current branch.
///
/// This will iterate over all known linked repositories (usually in the form of worktrees)
/// and report whether any HEAD is pointing at the current branch.
@ -134,10 +137,10 @@ class Branch {
/// Throws a [LibGit2Error] if error occured.
bool get isCheckedOut => bindings.isCheckedOut(_branchPointer);
/// Returns the branch name.
/// 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.
/// (i.e. it lives under "refs/heads/" or "refs/remotes/"), and return the branch part of it.
///
/// Throws a [LibGit2Error] if error occured.
String get name => bindings.name(_branchPointer);

14
lib/src/callbacks.dart
View file

@ -1,6 +1,20 @@
import 'package:libgit2dart/libgit2dart.dart';
class Callbacks {
/// Callback functions used in various methods of [Remote] and with [Repository.clone].
///
/// [credentials] is the [Credentials] object used for authentication.
///
/// [transferProgress] is the callback function that reports transfer progress.
///
/// [sidebandProgress] is the callback function that reports textual progress from the remote.
///
/// [updateTips] is the callback function matching the
/// `void Function(String refname, Oid old, Oid new)` that report reference updates.
///
/// [pushUpdateReference] is the callback function matching the
/// `void Function(String refname, String message)` used to inform of the update status
/// from the remote.
const Callbacks({
this.credentials,
this.transferProgress,

71
lib/src/commit.dart
View file

@ -8,12 +8,12 @@ class Commit {
/// Initializes a new instance of [Commit] class from provided pointer to
/// commit object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit(this._commitPointer);
/// Lookups commit object for provided [oid] in a [repo]sitory.
/// Lookups commit object for provided [oid] in the [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit.lookup({required Repository repo, required Oid oid}) {
_commitPointer = bindings.lookup(
repoPointer: repo.pointer,
@ -26,30 +26,49 @@ class Commit {
/// Pointer to memory address for allocated commit object.
Pointer<git_commit> get pointer => _commitPointer;
/// Creates new commit in the repository.
/// Creates new commit in the [repo]sitory.
///
/// [updateRef] is name of the reference that will be updated to point to this commit.
/// [repo] is the repository where to store the commit.
///
/// [updateRef] is the name of the reference that will be updated to point to this commit.
/// If the reference is not direct, it will be resolved to a direct reference. Use "HEAD"
/// to update the HEAD of the current branch and make it point to this commit. If the
/// reference doesn't exist yet, it will be created. If it does exist, the first parent
/// must be the tip of this branch.
///
/// [author] is the signature with author and author time of commit.
///
/// [committer] is the signature with committer and commit time of commit.
///
/// [messageEncoding] is the encoding for the message in the 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.
///
/// [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].
///
/// [parents] is a list of [Commit] objects that will be used as the parents for this commit.
/// This array may be empty if parent count is 0 (root commit). All the given commits must
/// be owned by the [repo].
///
/// Throws a [LibGit2Error] if error occured.
static Oid create({
required Repository repo,
required String message,
String? updateRef,
required Signature author,
required Signature commiter,
required Signature committer,
String? messageEncoding,
required String message,
required Tree tree,
required List<Commit> parents,
String? updateRef,
String? messageEncoding,
}) {
return Oid(bindings.create(
repoPointer: repo.pointer,
updateRef: updateRef,
authorPointer: author.pointer,
committerPointer: commiter.pointer,
committerPointer: committer.pointer,
messageEncoding: messageEncoding,
message: message,
treePointer: tree.pointer,
@ -68,6 +87,12 @@ class Commit {
/// the tip of the branch and then rewrite the following commits to reach a ref, pass
/// this as null and update the rest of the commit chain and ref separately.
///
/// Unlike [create], the [author], [committer], [message], [messageEncoding], and
/// [tree] arguments can be null in which case this will use the values from the original
/// [commit].
///
/// All arguments have the same meanings as in [create].
///
/// Throws a [LibGit2Error] if error occured.
static Oid amend({
required Repository repo,
@ -91,28 +116,29 @@ class Commit {
));
}
/// Returns the encoding for the message of a commit, as a string
/// representing a standard encoding name.
/// Wncoding for the message of a commit, as a string representing a standard
/// encoding name.
String get messageEncoding => bindings.messageEncoding(_commitPointer);
/// Returns the full message of a commit.
/// Full message of a commit.
///
/// The returned message will be slightly prettified by removing any potential leading newlines.
/// The returned message will be slightly prettified by removing any potential
/// leading newlines.
String get message => bindings.message(_commitPointer);
/// Returns the [Oid] of a commit.
/// [Oid] of a commit.
Oid get oid => Oid(bindings.id(_commitPointer));
/// Returns the commit time (i.e. committer time) of a commit.
/// Commit time (i.e. committer time) of a commit.
int get time => bindings.time(_commitPointer);
/// Returns the committer of a commit.
/// Committer of a commit.
Signature get committer => Signature(bindings.committer(_commitPointer));
/// Returns the author of a commit.
/// Author of a commit.
Signature get author => Signature(bindings.author(_commitPointer));
/// Returns list of parent commits [Oid]s.
/// List of parent commits [Oid]s.
List<Oid> get parents {
var parents = <Oid>[];
final parentCount = bindings.parentCount(_commitPointer);
@ -128,7 +154,7 @@ class Commit {
return parents;
}
/// Get the tree pointed to by a commit.
/// Tree pointed to by a commit.
Tree get tree {
return Tree(tree_bindings.lookup(
repoPointer: bindings.owner(_commitPointer),
@ -152,8 +178,9 @@ class Commit {
///
/// Note: for internal use.
class AnnotatedCommit {
/// Lookups an annotated commit from the given commit [oid]. The resulting annotated commit
/// must be freed to release allocated memory.
/// 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}) {

34
lib/src/config.dart
View file

@ -11,17 +11,17 @@ class Config with IterableMixin<ConfigEntry> {
/// Initializes a new instance of [Config] class from provided
/// pointer to config object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Config(this._configPointer);
/// Initializes a new instance of [Config] class from provided [path].
/// Opens config file at provided [path].
///
/// If [path] isn't provided, opens global, XDG and system config files.
///
/// [path] should point to single on-disk file; it's expected to be a native
/// Git config file following the default Git config syntax (see man git-config).
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws an [Exception] if file not found at provided path.
Config.open([String? path]) {
@ -38,11 +38,9 @@ class Config with IterableMixin<ConfigEntry> {
}
}
/// Initializes a new instance of [Config] class.
///
/// Opens the system configuration file.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Config.system() {
@ -51,11 +49,9 @@ class Config with IterableMixin<ConfigEntry> {
_configPointer = bindings.open(bindings.findSystem());
}
/// Initializes a new instance of [Config] class.
///
/// Opens the global configuration file.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Config.global() {
@ -64,11 +60,9 @@ class Config with IterableMixin<ConfigEntry> {
_configPointer = bindings.open(bindings.findGlobal());
}
/// Initializes a new instance of [Config] class.
///
/// Opens the global XDG configuration file.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Config.xdg() {
@ -80,9 +74,7 @@ class Config with IterableMixin<ConfigEntry> {
/// Pointer to memory address for allocated config object.
late final Pointer<git_config> _configPointer;
/// Create a snapshot of the configuration.
///
/// Create a snapshot of the current state of a configuration, which allows you to look
/// The snapshot of the current state of a configuration, which allows you to look
/// into a consistent view of the configuration for looking up complex values
/// (e.g. a remote, submodule).
Config get snapshot => Config(bindings.snapshot(_configPointer));
@ -181,21 +173,25 @@ class Config with IterableMixin<ConfigEntry> {
}
class ConfigEntry {
/// Initializes a new instance of [ConfigEntry] class from provided
/// pointer to config entry object in memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
const ConfigEntry(this._configEntryPointer);
/// Pointer to memory address for allocated config entry object.
final Pointer<git_config_entry> _configEntryPointer;
/// Returns name of the entry (normalised).
/// Name of the entry (normalised).
String get name => _configEntryPointer.ref.name.cast<Utf8>().toDartString();
/// Returns value of the entry.
/// Value of the entry.
String get value => _configEntryPointer.ref.value.cast<Utf8>().toDartString();
/// Returns depth of includes where this variable was found
/// Depth of includes where this variable was found
int get includeDepth => _configEntryPointer.ref.include_depth;
/// Returns which config file this was found in.
/// Which config file this was found in.
GitConfigLevel get level {
return GitConfigLevel.values.singleWhere(
(e) => _configEntryPointer.ref.level == e.value,

90
lib/src/diff.dart
View file

@ -10,10 +10,10 @@ class Diff {
/// Initializes a new instance of [Diff] class from provided
/// pointer to diff object in memory.
///
/// Should be freed with `free()` to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Diff(this._diffPointer);
/// Reads the contents of a git patch file into a git diff object.
/// Reads the [content]s of a git patch file into a git diff object.
///
/// The diff object produced is similar to the one that would be produced if you actually
/// produced it computationally by comparing two trees, however there may be subtle differences.
@ -32,7 +32,7 @@ class Diff {
/// Pointer to memory address for allocated diff object.
Pointer<git_diff> get pointer => _diffPointer;
/// Queries how many diff records are there in a diff.
/// How many diff records are there in a diff.
int get length => bindings.length(_diffPointer);
/// Returns a list of [DiffDelta]s containing file pairs with and old and new revisions.
@ -48,7 +48,7 @@ class Diff {
return deltas;
}
/// Returns a list of [Patch]es.
/// A List of [Patch]es.
List<Patch> get patches {
final length = bindings.length(_diffPointer);
var patches = <Patch>[];
@ -58,7 +58,7 @@ class Diff {
return patches;
}
/// Returns a patch diff string.
/// The patch diff string.
String get patch {
final length = bindings.length(_diffPointer);
var buffer = calloc<git_buf>(sizeOf<git_buf>());
@ -98,6 +98,25 @@ class Diff {
/// with new entries reflecting those changes. This also will, if requested, break modified
/// files into add/remove pairs if the amount of change is above a threshold.
///
/// [flags] is a combination of [GitDiffFind] flags. Defaults to [GitDiffFind.byConfig].
///
/// [renameThreshold] is the threshold above which similar files will be considered renames.
/// This is equivalent to the -M option. Defaults to 50.
///
/// [copyThreshold] is the threshold above which similar files will be considered copies.
/// This is equivalent to the -C option. Defaults to 50.
///
/// [renameFromRewriteThreshold] is the threshold below which similar files will be
/// eligible to be a rename source. This is equivalent to the first part of the -B option.
/// Defaults to 50.
///
/// [breakRewriteThreshold] is the treshold below which similar files will be split into
/// a delete/add pair. This is equivalent to the last part of the -B option. Defaults to 60.
///
/// [renameLimit] is the maximum number of matches to consider for a particular file.
/// This is a little different from the -l option from Git because we will still process
/// up to this many matches before abandoning the search. Defaults to 200.
///
/// Throws a [LibGit2Error] if error occured.
void findSimilar({
Set<GitDiffFind> flags = const {GitDiffFind.byConfig},
@ -145,14 +164,14 @@ class DiffDelta {
/// Pointer to memory address for allocated diff delta object.
final Pointer<git_diff_delta> _diffDeltaPointer;
/// Returns type of change.
/// Type of change.
GitDelta get status {
return GitDelta.values.singleWhere(
(e) => _diffDeltaPointer.ref.status == e.value,
);
}
/// Looks up the single character abbreviation for a delta status code.
/// Single character abbreviation for a delta status code.
///
/// When you run `git diff --name-status` it uses single letter codes in the output such as
/// 'A' for added, 'D' for deleted, 'M' for modified, etc. This function converts a [GitDelta]
@ -160,21 +179,18 @@ class DiffDelta {
/// a space (i.e. ' ').
String get statusChar => bindings.statusChar(_diffDeltaPointer.ref.status);
/// Returns flags for the delta object.
/// Flags for the delta object.
Set<GitDiffFlag> get flags {
return GitDiffFlag.values
.where((e) => _diffDeltaPointer.ref.flags & e.value == e.value)
.toSet();
}
/// Returns a similarity score for renamed or copied files between 0 and 100
/// Similarity score for renamed or copied files between 0 and 100
/// indicating how similar the old and new sides are.
///
/// The similarity score is zero unless you call `find_similar()` which does
/// a similarity analysis of files in the diff.
int get similarity => _diffDeltaPointer.ref.similarity;
/// Returns number of files in this delta.
/// Number of files in this delta.
int get numberOfFiles => _diffDeltaPointer.ref.nfiles;
/// Represents the "from" side of the diff.
@ -201,24 +217,24 @@ class DiffFile {
final git_diff_file _diffFile;
/// Returns [Oid] of the item. If the entry represents an absent side of a diff
/// [Oid] of the item. If the entry represents an absent side of a diff
/// then the oid will be zeroes.
Oid get oid => Oid.fromRaw(_diffFile.id);
/// Returns path to the entry relative to the working directory of the repository.
/// Path to the entry relative to the working directory of the repository.
String get path => _diffFile.path.cast<Utf8>().toDartString();
/// Returns the size of the entry in bytes.
/// Size of the entry in bytes.
int get size => _diffFile.size;
/// Returns flags for the diff file object.
/// Flags for the diff file object.
Set<GitDiffFlag> get flags {
return GitDiffFlag.values
.where((e) => _diffFile.flags & e.value == e.value)
.toSet();
}
/// Returns one of the [GitFilemode] values.
/// One of the [GitFilemode] values.
GitFilemode get mode {
return GitFilemode.values.singleWhere((e) => _diffFile.mode == e.value);
}
@ -232,21 +248,23 @@ class DiffFile {
class DiffStats {
/// Initializes a new instance of [DiffStats] class from provided
/// pointer to diff stats object in memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
const DiffStats(this._diffStatsPointer);
/// Pointer to memory address for allocated diff delta object.
final Pointer<git_diff_stats> _diffStatsPointer;
/// Returns the total number of insertions.
/// Total number of insertions.
int get insertions => bindings.statsInsertions(_diffStatsPointer);
/// Returns the total number of deletions.
/// Total number of deletions.
int get deletions => bindings.statsDeletions(_diffStatsPointer);
/// Returns the total number of files changed.
/// Total number of files changed.
int get filesChanged => bindings.statsFilesChanged(_diffStatsPointer);
/// Print diff statistics.
/// Prints diff statistics.
///
/// Width for output only affects formatting of [GitDiffStats.full].
///
@ -284,25 +302,25 @@ class DiffHunk {
/// Pointer to memory address for allocated patch object.
final Pointer<git_patch> _patchPointer;
/// Returns count of total lines in this hunk.
/// Number of total lines in this hunk.
final int linesCount;
/// Returns index of this hunk in the patch.
/// Index of this hunk in the patch.
final int index;
/// Returns starting line number in 'old file'.
/// Starting line number in 'old file'.
int get oldStart => _diffHunkPointer.ref.old_start;
/// Returns number of lines in 'old file'.
/// Number of lines in 'old file'.
int get oldLines => _diffHunkPointer.ref.old_lines;
/// Returns starting line number in 'new file'.
/// Starting line number in 'new file'.
int get newStart => _diffHunkPointer.ref.new_start;
/// Returns number of lines in 'new file'.
/// Number of lines in 'new file'.
int get newLines => _diffHunkPointer.ref.new_lines;
/// Returns header of a hunk.
/// Header of a hunk.
String get header {
var list = <int>[];
for (var i = 0; i < _diffHunkPointer.ref.header_len; i++) {
@ -311,7 +329,7 @@ class DiffHunk {
return String.fromCharCodes(list);
}
/// Returns list of lines in a hunk of a patch.
/// List of lines in a hunk of a patch.
List<DiffLine> get lines {
var lines = <DiffLine>[];
for (var i = 0; i < linesCount; i++) {
@ -339,26 +357,26 @@ class DiffLine {
/// Pointer to memory address for allocated diff line object.
final Pointer<git_diff_line> _diffLinePointer;
/// Returns type of the line.
/// Type of the line.
GitDiffLine get origin {
return GitDiffLine.values.singleWhere(
(e) => _diffLinePointer.ref.origin == e.value,
);
}
/// Returns line number in old file or -1 for added line.
/// Line number in old file or -1 for added line.
int get oldLineNumber => _diffLinePointer.ref.old_lineno;
/// Returns line number in new file or -1 for deleted line.
/// Line number in new file or -1 for deleted line.
int get newLineNumber => _diffLinePointer.ref.new_lineno;
/// Returns number of newline characters in content.
/// Number of newline characters in content.
int get numLines => _diffLinePointer.ref.num_lines;
/// Returns offset in the original file to the content.
/// Offset in the original file to the content.
int get contentOffset => _diffLinePointer.ref.content_offset;
/// Returns content of the diff line.
/// Content of the diff line.
String get content =>
_diffLinePointer.ref.content.cast<Utf8>().toDartString();

63
lib/src/index.dart
View file

@ -10,7 +10,7 @@ class Index with IterableMixin<IndexEntry> {
/// Initializes a new instance of [Index] class from provided
/// pointer to index object in memory.
///
/// Should be freed with `free()` to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
const Index(this._indexPointer);
final Pointer<git_index> _indexPointer;
@ -20,7 +20,8 @@ class Index with IterableMixin<IndexEntry> {
/// Returns index entry located at provided 0-based position or string path.
///
/// Throws error if position is out of bounds or entry isn't found at path.
/// Throws [RangeError] when provided [value] is outside of valid range or
/// [ArgumentError] if nothing found for provided path.
IndexEntry operator [](Object value) {
if (value is int) {
return IndexEntry(bindings.getByIndex(
@ -36,7 +37,7 @@ class Index with IterableMixin<IndexEntry> {
}
}
/// Checks whether entry at provided [path] is in the git index or not.
/// Whether entry at provided [path] is in the git index or not.
bool find(String path) {
return bindings.find(
indexPointer: _indexPointer,
@ -44,7 +45,7 @@ class Index with IterableMixin<IndexEntry> {
);
}
/// Checks if the index contains entries representing file conflicts.
/// Whether index contains entries representing file conflicts.
bool get hasConflicts => bindings.hasConflicts(_indexPointer);
/// Returns map of conflicts in the index with key as conflicted file path and
@ -112,7 +113,7 @@ class Index with IterableMixin<IndexEntry> {
///
/// This method will fail in bare index instances.
///
/// The `pathspec` is a list of file names or shell glob patterns that will be matched
/// 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).
///
@ -123,11 +124,11 @@ class Index with IterableMixin<IndexEntry> {
/// Updates the contents of an existing index object in memory by reading from the hard disk.
///
/// If force is true (default), this performs a "hard" read that discards in-memory changes and
/// If [force] is true (default), 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 [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.
@ -147,11 +148,12 @@ class Index with IterableMixin<IndexEntry> {
///
/// This method will scan the index and write a representation of its current state back to disk;
/// it recursively creates tree objects for each of the subtrees stored in the index, but only
/// returns the [Oid] of the root tree. This is the OID that can be used e.g. to create a commit.
/// returns the [Oid] of the root tree. This is the oid that can be used e.g. to create a commit.
///
/// The index must not contain any file in conflict.
///
/// Throws a [LibGit2Error] if error occured or there is no associated repository and no [repo] passed.
/// Throws a [LibGit2Error] if error occured or there is no associated repository
/// and no [repo] passed.
Oid writeTree([Repository? repo]) {
if (repo == null) {
return Oid(bindings.writeTree(_indexPointer));
@ -163,19 +165,29 @@ class Index with IterableMixin<IndexEntry> {
}
}
/// Removes an entry from the index.
/// Removes an entry from the index at provided [path] relative to repository working
/// directory with optional [stage].
///
/// Throws a [LibGit2Error] if error occured.
void remove(String path, [int stage = 0]) =>
bindings.remove(indexPointer: _indexPointer, path: path, stage: stage);
/// Removes all matching index entries.
/// Removes all matching index entries at provided list of [path]s relative to repository
/// working directory.
///
/// Throws a [LibGit2Error] if error occured.
void removeAll(List<String> path) =>
bindings.removeAll(indexPointer: _indexPointer, pathspec: path);
/// Creates a diff between the repository index and the workdir directory.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
Diff diffToWorkdir({
Set<GitDiff> flags = const {GitDiff.normal},
int contextLines = 3,
@ -191,6 +203,16 @@ class Index with IterableMixin<IndexEntry> {
}
/// Creates a diff between a tree and repository index.
///
/// [tree] is the [Tree] object to diff from.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
Diff diffToTree({
required Tree tree,
Set<GitDiff> flags = const {GitDiff.normal},
@ -226,23 +248,18 @@ class IndexEntry {
/// Pointer to memory address for allocated index entry object.
Pointer<git_index_entry> get pointer => _indexEntryPointer;
/// Returns inique identity of the index entry.
/// [Oid] of the index entry.
Oid get oid => Oid.fromRaw(_indexEntryPointer.ref.id);
/// Sets inique identity of the index entry.
set oid(Oid oid) => _indexEntryPointer.ref.id = oid.pointer.ref;
/// Returns path of the index entry.
/// Path of the index entry.
String get path => _indexEntryPointer.ref.path.cast<Utf8>().toDartString();
/// Sets path of the index entry.
set path(String path) =>
_indexEntryPointer.ref.path = path.toNativeUtf8().cast<Int8>();
/// Returns id of the index entry as sha hex.
String get sha => _oidToHex(_indexEntryPointer.ref.id);
/// Returns the UNIX file attributes of a index entry.
/// UNIX file attributes of a index entry.
GitFilemode get mode {
return GitFilemode.values.singleWhere(
(mode) => _indexEntryPointer.ref.mode == mode.value,
@ -256,14 +273,6 @@ class IndexEntry {
String toString() {
return 'IndexEntry{oid: $oid, path: $path, mode: $mode}';
}
String _oidToHex(git_oid oid) {
var hex = StringBuffer();
for (var i = 0; i < 20; i++) {
hex.write(oid.id[i].toRadixString(16));
}
return hex.toString();
}
}
class ConflictEntry {

12
lib/src/mailmap.dart
View file

@ -8,7 +8,9 @@ class Mailmap {
/// Initializes a new instance of [Mailmap] class.
///
/// This object is empty, so you'll have to add a mailmap file before you can
/// do anything with it. Must be freed with `free()`.
/// do anything with it.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Mailmap.empty() {
libgit2.git_libgit2_init();
@ -17,14 +19,14 @@ class Mailmap {
/// Initializes a new instance of [Mailmap] class from provided buffer.
///
/// Must be freed with `free()`.
/// **IMPORTANT**: Should be freed to release allocated memory.
Mailmap.fromBuffer(String buffer) {
libgit2.git_libgit2_init();
_mailmapPointer = bindings.fromBuffer(buffer);
}
/// Initializes a new instance of [Mailmap] class from a repository, loading
/// Initializes a new instance of [Mailmap] class from a [repo]sitory, loading
/// mailmap files based on the repository's configuration.
///
/// Mailmaps are loaded in the following order:
@ -34,7 +36,7 @@ class Mailmap {
/// NOTE: `mailmap.blob` defaults to `HEAD:.mailmap` in bare repositories
/// 3. The path in the `mailmap.file` config entry, if set.
///
/// Must be freed with `free()`.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Mailmap.fromRepository(Repository repo) {
@ -57,7 +59,7 @@ class Mailmap {
);
}
/// Resolves a signature to use real names and emails with a mailmap.
/// Resolves a [signature] to use real names and emails with a mailmap.
Signature resolveSignature(Signature signature) {
return Signature(bindings.resolveSignature(
mailmapPointer: _mailmapPointer,

48
lib/src/note.dart
View file

@ -8,10 +8,15 @@ class Note {
/// pointer to note and annotatedOid objects in memory.
Note(this._notePointer, this._annotatedOidPointer);
/// Reads the note for an [annotatedOid].
/// Lookups the note for an [annotatedOid].
///
/// IMPORTANT: Notes must be freed manually when no longer needed to prevent
/// memory leak.
/// [repo] is the repository where to look up the note.
///
/// [annotatedOid] is the [Oid] of the git object to read the note from.
///
/// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
///
/// **IMPORTANT**: Notes must be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Note.lookup({
@ -33,7 +38,21 @@ class Note {
/// Pointer to memory address for allocated annotetedOid object.
late final Pointer<git_oid> _annotatedOidPointer;
/// Adds a note for an [annotatedOid].
/// Creates a note for an [annotatedOid].
///
/// [repo] is the repository where to store the note.
///
/// [author] is the signature of the note's commit author.
///
/// [committer] is the signature of the note's commit committer.
///
/// [annotatedOid] is the [Oid] of the git object to decorate.
///
/// [note] is the content of the note to add.
///
/// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
///
/// [force] determines whether existing note should be overwritten.
///
/// Throws a [LibGit2Error] if error occured.
static Oid create({
@ -58,6 +77,16 @@ class Note {
/// Deletes the note for an [annotatedOid].
///
/// [repo] is the repository where the note lives.
///
/// [annotatedOid] is the [Oid] of the git object to remove the note from.
///
/// [author] is the signature of the note's commit author.
///
/// [committer] is the signature of the note's commit committer.
///
/// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
///
/// Throws a [LibGit2Error] if error occured.
static void delete({
required Repository repo,
@ -74,10 +103,9 @@ class Note {
);
}
/// Returns list of notes for repository.
/// Returns list of notes for [repo]sitory.
///
/// IMPORTANT: Notes must be freed manually when no longer needed to prevent
/// memory leak.
/// **IMPORTANT**: Notes must be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
static List<Note> list(Repository repo) {
@ -90,13 +118,13 @@ class Note {
.toList();
}
/// Returns the note object's [Oid].
/// Note object's [Oid].
Oid get oid => Oid(bindings.id(_notePointer));
/// Returns the note message.
/// Note message.
String get message => bindings.message(_notePointer);
/// Returns the [Oid] of the git object being annotated.
/// [Oid] of the git object being annotated.
Oid get annotatedOid => Oid(_annotatedOidPointer);
/// Releases memory allocated for note object.

29
lib/src/odb.dart
View file

@ -7,13 +7,16 @@ import 'util.dart';
class Odb {
/// Initializes a new instance of [Odb] class from provided
/// pointer to Odb object in memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Odb(this._odbPointer);
/// Initializes a new instance of [Odb] class by creating a new object database with
/// no backends.
/// Creates a new object database with no backends.
///
/// Before the ODB can be used for read/writing, a custom database backend must be
/// manually added.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Odb.create() {
libgit2.git_libgit2_init();
@ -41,12 +44,12 @@ class Odb {
);
}
/// Returns list of all objects [Oid]s available in the database.
/// List of all objects [Oid]s available in the database.
///
/// Throws a [LibGit2Error] if error occured.
List<Oid> get objects => bindings.objects(_odbPointer);
/// Checks if the given object can be found in the object database.
/// Whether given object [oid] can be found in the object database.
bool contains(Oid oid) {
return bindings.exists(odbPointer: _odbPointer, oidPointer: oid.pointer);
}
@ -55,7 +58,7 @@ class Odb {
///
/// This method queries all available ODB backends trying to read the given [oid].
///
/// The returned object should be freed by the user once it's no longer in use.
/// **IMPORTANT**: Returned object should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
OdbObject read(Oid oid) {
@ -67,7 +70,7 @@ class Odb {
/// Writes raw [data] to into the object database.
///
/// [type] should be one of [GitObject.blob], [GitObject.commit], [GitObject.tag],
/// [type] should be one of [GitObject.blob], [GitObject.commit], [GitObject.tag] or
/// [GitObject.tree].
///
/// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided type is invalid.
@ -98,25 +101,19 @@ class OdbObject {
/// Pointer to memory address for allocated odbObject object.
final Pointer<git_odb_object> _odbObjectPointer;
/// Returns the [Oid] of an ODB object.
///
/// This is the [Oid] from which the object was read from.
/// [Oid] of an ODB object.
Oid get oid => Oid(bindings.objectId(_odbObjectPointer));
/// Returns the type of an ODB object.
/// Type of an ODB object.
GitObject get type {
final typeInt = bindings.objectType(_odbObjectPointer);
return GitObject.values.singleWhere((e) => typeInt == e.value);
}
/// Returns the data of an ODB object.
///
/// This is the uncompressed, raw data as read from the ODB, without the leading header.
/// Uncompressed, raw data as read from the ODB, without the leading header.
String get data => bindings.objectData(_odbObjectPointer);
/// Returns the size of an ODB object.
///
/// This is the real size of the `data` buffer, not the actual size of the object.
/// Real size of the `data` buffer, not the actual size of the object.
int get size => bindings.objectSize(_odbObjectPointer);
/// Releases memory allocated for odbObject object.

4
lib/src/oid.dart
View file

@ -35,7 +35,7 @@ class Oid {
}
}
/// Initializes a new instance of [Oid] class from provided raw git_oid.
/// Initializes a new instance of [Oid] class from provided raw git_oid structure.
Oid.fromRaw(git_oid raw) {
_oidPointer = bindings.fromRaw(raw.id);
}
@ -45,7 +45,7 @@ class Oid {
/// Pointer to memory address for allocated oid object.
Pointer<git_oid> get pointer => _oidPointer;
/// Returns hexadecimal SHA string.
/// Hexadecimal SHA string.
String get sha => bindings.toSHA(_oidPointer);
@override

8
lib/src/packbuilder.dart
View file

@ -6,7 +6,7 @@ import 'bindings/packbuilder.dart' as bindings;
class PackBuilder {
/// Initializes a new instance of [PackBuilder] class.
///
/// Should be freed with `free()`.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
PackBuilder(Repository repo) {
@ -49,15 +49,15 @@ class PackBuilder {
bindings.write(packbuilderPointer: _packbuilderPointer, path: path);
}
/// Returns the total number of objects the packbuilder will write out.
/// Total number of objects the packbuilder will write out.
int get length => bindings.length(_packbuilderPointer);
/// Returns the number of objects the packbuilder has already written out.
/// Number of objects the packbuilder has already written out.
int get writtenLength => bindings.writtenCount(_packbuilderPointer);
/// Sets and returns the number of threads to spawn.
///
/// By default, libgit2 won't spawn any threads at all; when set to 0,
/// By default, libgit2 won't spawn any threads at all. When set to 0,
/// libgit2 will autodetect the number of CPUs.
int setThreads(int number) {
return bindings.setThreads(

35
lib/src/patch.dart
View file

@ -9,7 +9,7 @@ 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.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Patch(this._patchPointer, this._aPointer, this._bPointer);
/// Directly generates a patch from the difference between two blobs, buffers or
@ -17,7 +17,19 @@ class Patch {
///
/// [a] and [b] can be [Blob], [String] or null.
///
/// Should be freed to release allocated memory.
/// [aPath] treat [a] as if it had this filename, can be null.
///
/// [bPath] treat [b] as if it had this filename, can be null.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Patch.create({
required Object? a,
required Object? b,
@ -75,9 +87,13 @@ class Patch {
_bPointer = result['b'];
}
/// Returns a patch for an entry in the diff list.
/// Creates a patch for an entry in the diff list.
///
/// Should be freed with `free()` to release allocated memory.
/// [diff] is the [Diff] list object.
///
/// [index] is the position of an entry in diff list.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Patch.fromDiff({required Diff diff, required int index}) {
@ -94,12 +110,12 @@ class Patch {
/// Pointer to memory address for allocated patch object.
Pointer<git_patch> get pointer => _patchPointer;
/// Returns the content of a patch as a single diff text.
/// Content of a patch as a single diff text.
///
/// Throws a [LibGit2Error] if error occured.
String get text => bindings.text(_patchPointer);
/// Looks up size of patch diff data in bytes.
/// Size of patch diff data in bytes.
///
/// This returns the raw size of the patch data. This only includes the actual data from
/// the lines of the diff, not the file or hunk headers.
@ -107,6 +123,9 @@ class Patch {
/// If you pass `includeContext` as true, this will be the size of all of the diff output;
/// if you pass it as false, this will only include the actual changed lines (as if
/// contextLines was 0).
///
/// If [includeHunkHeaders] and [includeFileHeaders] are set to true, they will be included
/// in the total size.
int size({
bool includeContext = false,
bool includeHunkHeaders = false,
@ -120,10 +139,10 @@ class Patch {
);
}
/// Returns the delta associated with a patch.
/// Delta associated with a patch.
DiffDelta get delta => DiffDelta(bindings.delta(_patchPointer));
/// Returns the list of hunks in a patch.
/// List of hunks in a patch.
List<DiffHunk> get hunks {
final length = bindings.numHunks(_patchPointer);
final hunks = <DiffHunk>[];

22
lib/src/rebase.dart
View file

@ -4,10 +4,8 @@ import 'bindings/libgit2_bindings.dart';
import 'bindings/rebase.dart' as bindings;
class Rebase {
/// Initializes a new instance of the [Rebase] class by initializing a
/// rebase operation to rebase the changes in [branch] relative to [upstream]
/// [onto] another branch. To begin the rebase process, call `next()`.
/// When you have finished with this object, call `free()`.
/// Initializes a rebase operation to rebase the changes in [branch] relative to [upstream]
/// [onto] another branch. To begin the rebase process, call [next].
///
/// [branch] is the terminal commit to rebase, default is to rebase the current branch.
///
@ -17,6 +15,8 @@ class Rebase {
/// [onto] is the branch to rebase onto, default is to rebase onto the given [upstream]
/// (throws if [upstream] is not provided).
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Rebase.init({
required Repository repo,
@ -56,7 +56,7 @@ class Rebase {
/// Pointer to memory address for allocated rebase object.
late final Pointer<git_rebase> _rebasePointer;
/// The count of rebase operations that are to be applied.
/// Number of rebase operations that are to be applied.
int get operationsCount {
return bindings.operationsCount(_rebasePointer);
}
@ -75,6 +75,14 @@ class Rebase {
/// Commits the current patch. You must have resolved any conflicts that were
/// introduced during the patch application from the [next] invocation.
///
/// [committer] is the committer of the rebase.
///
/// [message] the message for this commit, can be null to use the message from the
/// original commit.
///
/// [author] is the author of the updated commit, can be null to keep the author from
/// the original commit.
///
/// Throws a [LibGit2Error] if error occured.
void commit({
required Signature committer,
@ -108,14 +116,14 @@ class RebaseOperation {
/// Pointer to memory address for allocated rebase operation object.
final Pointer<git_rebase_operation> _rebaseOperationPointer;
/// Returns the type of rebase operation.
/// Type of rebase operation.
GitRebaseOperation get type {
return GitRebaseOperation.values.singleWhere(
(e) => _rebaseOperationPointer.ref.type == e.value,
);
}
/// Returns the commit [Oid] being cherry-picked.
/// [Oid] of commit being cherry-picked.
Oid get oid => Oid.fromRaw(_rebaseOperationPointer.ref.id);
@override

48
lib/src/reference.dart
View file

@ -8,19 +8,21 @@ import 'bindings/repository.dart' as repository_bindings;
class Reference {
/// Initializes a new instance of the [Reference] class.
/// Should be freed to release allocated memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Reference(this._refPointer);
/// Creates a new reference.
/// Creates a new reference for provided [target].
///
/// The reference will be created in the [repo]sitory and written to the disk.
/// The generated [Reference] object must be freed by the user.
///
/// **IMPORTANT**: The generated [Reference] object should be freed to release
/// allocated memory.
///
/// Valid reference [name]s must follow one of two patterns:
///
/// Top-level names must contain only capital letters and underscores, and must begin and end
/// - Top-level names must contain only capital letters and underscores, and must begin and end
/// with a letter. (e.g. "HEAD", "ORIG_HEAD").
/// Names prefixed with "refs/" can be almost anything. You must avoid the characters
/// - Names prefixed with "refs/" can be almost anything. You must avoid the characters
/// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
/// special meaning to revparse.
///
@ -63,7 +65,7 @@ class Reference {
/// Lookups reference [name] in a [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// The [name] will be checked for validity.
///
@ -86,7 +88,7 @@ class Reference {
ref.free();
}
/// Renames an existing reference.
/// Renames an existing reference with provided [oldName].
///
/// This method works for both direct and symbolic references.
///
@ -116,7 +118,7 @@ class Reference {
ref.free();
}
/// Returns a list of all the references that can be found in a [repo]sitory.
/// List of all the references that can be found in a [repo]sitory.
///
/// Throws a [LibGit2Error] if error occured.
static List<String> list(Repository repo) => bindings.list(repo.pointer);
@ -132,14 +134,14 @@ class Reference {
refdb_bindings.free(refdb);
}
/// Returns the type of the reference.
/// Type of the reference.
ReferenceType get type {
return bindings.referenceType(_refPointer) == 1
? ReferenceType.direct
: ReferenceType.symbolic;
}
/// Returns the [Oid] pointed to by a reference.
/// [Oid] pointed to by a reference.
///
/// Throws an [Exception] if error occured.
Oid get target {
@ -155,11 +157,11 @@ class Reference {
/// Updates the [target] of this reference.
///
/// [target] being either Oid for direct reference or String reference name for symbolic
/// [target] being either Oid for direct reference or string reference name for symbolic
/// reference.
///
/// Throws a [LibGit2Error] if error occured or [ArgumentError] if [target] is not
/// [Oid] or String.
/// [Oid] or string.
void setTarget({required Object target, String? logMessage}) {
if (target is Oid) {
final newPointer = bindings.setTarget(
@ -214,16 +216,16 @@ class Reference {
}
}
/// Returns the full name of a reference.
/// Full name of a reference.
String get name => bindings.name(_refPointer);
/// Returns the reference's short name.
/// Reference's short name.
///
/// This will transform the reference name into a name "human-readable" version.
/// If no shortname is appropriate, it will return the full name.
String get shorthand => bindings.shorthand(_refPointer);
/// Checks if a reflog exists for the specified reference [name].
/// Whether reflog exists for the specified reference [name].
bool get hasLog {
return bindings.hasLog(
repoPointer: bindings.owner(_refPointer),
@ -231,24 +233,24 @@ class Reference {
);
}
/// Returns a [RefLog] object.
/// [RefLog] object.
///
/// Should be freed when no longer needed.
/// **IMPORTANT**: Should be freed to release allocated memory.
RefLog get log => RefLog(this);
/// Checks if a reference is a local branch.
/// Whether reference is a local branch.
bool get isBranch => bindings.isBranch(_refPointer);
/// Checks if a reference is a note.
/// Whether reference is a note.
bool get isNote => bindings.isNote(_refPointer);
/// Check if a reference is a remote tracking branch.
/// Whether reference is a remote tracking branch.
bool get isRemote => bindings.isRemote(_refPointer);
/// Check if a reference is a tag.
/// Whether reference is a tag.
bool get isTag => bindings.isTag(_refPointer);
/// Returns the repository where a reference resides.
/// Repository where a reference resides.
Repository get owner => Repository(bindings.owner(_refPointer));
@override

15
lib/src/reflog.dart
View file

@ -6,6 +6,8 @@ import 'bindings/reflog.dart' as bindings;
class RefLog with IterableMixin<RefLogEntry> {
/// Initializes a new instance of [RefLog] class from provided [Reference].
///
/// **IMPORTANT**: Should be freed to release allocated memory.
RefLog(Reference ref) {
_reflogPointer = bindings.read(
repoPointer: ref.owner.pointer,
@ -16,10 +18,10 @@ class RefLog with IterableMixin<RefLogEntry> {
/// Pointer to memory address for allocated reflog object.
late final Pointer<git_reflog> _reflogPointer;
/// Lookup an entry by its index.
/// Lookups an entry by its index.
///
/// Requesting the reflog entry with an index of 0 (zero) will return
/// the most recently created entry.
/// Requesting the reflog entry with an index of 0 will return the most
/// recently created entry.
RefLogEntry operator [](int index) {
return RefLogEntry(bindings.getByIndex(
reflogPointer: _reflogPointer,
@ -35,16 +37,17 @@ class RefLog with IterableMixin<RefLogEntry> {
}
class RefLogEntry {
/// Initializes a new instance of [RefLogEntry] class.
/// Initializes a new instance of [RefLogEntry] class from provided
/// pointer to RefLogEntry object in memory.
const RefLogEntry(this._entryPointer);
/// Pointer to memory address for allocated reflog entry object.
final Pointer<git_reflog_entry> _entryPointer;
/// Returns the log message.
/// Log message.
String get message => bindings.entryMessage(_entryPointer);
/// Returns the committer of this entry.
/// Committer of this entry.
Signature get committer => Signature(bindings.entryCommiter(_entryPointer));
@override

14
lib/src/refspec.dart
View file

@ -11,26 +11,26 @@ class Refspec {
/// Pointer to memory address for allocated refspec object.
final Pointer<git_refspec> _refspecPointer;
/// Returns the source specifier.
/// Source specifier.
String get source => bindings.source(_refspecPointer);
/// Returns the destination specifier.
/// Destination specifier.
String get destination => bindings.destination(_refspecPointer);
/// Returns the force update setting.
/// Force update setting.
bool get force => bindings.force(_refspecPointer);
/// Returns the refspec's string.
/// Refspec's string.
String get string => bindings.string(_refspecPointer);
/// Returns the refspec's direction (fetch or push).
/// Refspec's direction (fetch or push).
GitDirection get direction {
return bindings.direction(_refspecPointer) == 0
? GitDirection.fetch
: GitDirection.push;
}
/// Checks if a refspec's source descriptor matches a reference.
/// Whether refspec's source descriptor matches a reference.
bool matchesSource(String refname) {
return bindings.matchesSource(
refspecPointer: _refspecPointer,
@ -38,7 +38,7 @@ class Refspec {
);
}
/// Checks if a refspec's destination descriptor matches a reference.
/// Whether refspec's destination descriptor matches a reference.
bool matchesDestination(String refname) {
return bindings.matchesDestination(
refspecPointer: _refspecPointer,

77
lib/src/remote.dart
View file

@ -4,19 +4,21 @@ import 'bindings/libgit2_bindings.dart';
import 'bindings/remote.dart' as bindings;
class Remote {
/// Initializes a new instance of [Remote] class by looking up remote with
/// provided [name] in a [repo]sitory.
/// Lookups remote with provided [name] in a [repo]sitory.
///
/// The name will be checked for validity.
/// The [name] will be checked for validity.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Remote.lookup({required Repository repo, required String name}) {
_remotePointer = bindings.lookup(repoPointer: repo.pointer, name: name);
}
/// Initializes a new instance of [Remote] class by adding a remote with
/// provided [name] and [url] to the [repo]sitory's configuration with the
/// default [fetch] refspec if none provided .
/// Adds remote with provided [name] and [url] to the [repo]sitory's
/// configuration with the default [fetch] refspec if none provided.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Remote.create({
@ -46,7 +48,7 @@ class Remote {
/// Pointer to memory address for allocated remote object.
Pointer<git_remote> get pointer => _remotePointer;
/// Deletes an existing persisted remote.
/// Deletes an existing persisted remote with provided [name].
///
/// All remote-tracking branches and configuration settings for the remote will be removed.
///
@ -55,13 +57,13 @@ class Remote {
bindings.delete(repoPointer: repo.pointer, name: name);
}
/// Gives the remote a new name.
/// Renames remote with provided [oldName].
///
/// Returns list of non-default refspecs that cannot be renamed.
///
/// All remote-tracking branches and configuration settings for the remote are updated.
///
/// The new name will be checked for validity.
/// The [newName] will be checked for validity.
///
/// No loaded instances of a the remote with the old name will change their name or
/// their list of refspecs.
@ -84,7 +86,7 @@ class Remote {
return bindings.list(repo.pointer);
}
/// Sets the remote's url in the configuration.
/// Sets the [remote]'s [url] in the configuration.
///
/// Remote objects already in memory will not be affected. This assumes the common
/// case of a single-url remote and will otherwise return an error.
@ -102,7 +104,7 @@ class Remote {
);
}
/// Sets the remote's url for pushing in the configuration.
/// Sets the [remote]'s [url] for pushing in the configuration.
///
/// Remote objects already in memory will not be affected. This assumes the common
/// case of a single-url remote and will otherwise return an error.
@ -120,7 +122,7 @@ class Remote {
);
}
/// Adds a fetch refspec to the remote's configuration.
/// Adds a fetch [refspec] to the [remote]'s configuration.
///
/// No loaded remote instances will be affected.
///
@ -137,7 +139,7 @@ class Remote {
);
}
/// Adds a push refspec to the remote's configuration.
/// Adds a push [refspec] to the [remote]'s configuration.
///
/// No loaded remote instances will be affected.
///
@ -154,21 +156,21 @@ class Remote {
);
}
/// Returns the remote's name.
/// Remote's name.
String get name => bindings.name(_remotePointer);
/// Returns the remote's url.
/// Remote's url.
String get url => bindings.url(_remotePointer);
/// Returns the remote's url for pushing.
/// Remote's url for pushing.
///
/// Returns empty string if no special url for pushing is set.
String get pushUrl => bindings.pushUrl(_remotePointer);
/// Returns the number of refspecs for a remote.
/// Number of refspecs for a remote.
int get refspecCount => bindings.refspecCount(_remotePointer);
/// Returns a [Refspec] object from the remote at provided position.
/// [Refspec] object from the remote at provided position.
Refspec getRefspec(int index) {
return Refspec(bindings.getRefspec(
remotePointer: _remotePointer,
@ -176,10 +178,10 @@ class Remote {
));
}
/// Returns the remote's list of fetch refspecs.
/// List of fetch refspecs.
List<String> get fetchRefspecs => bindings.fetchRefspecs(_remotePointer);
/// Get the remote's list of push refspecs.
/// List of push refspecs.
List<String> get pushRefspecs => bindings.pushRefspecs(_remotePointer);
/// Returns the remote repository's reference list and their associated commit ids.
@ -187,6 +189,8 @@ class Remote {
/// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
/// specified url. By default connection isn't done through proxy.
///
/// [callbacks] is the combination of callback functions from [Callbacks] object.
///
/// Returned map keys:
/// - `local` is true if remote head is available locally, false otherwise.
/// - `loid` is the oid of the object the local copy of the remote head is currently
@ -213,10 +217,16 @@ class Remote {
/// Downloads new data and updates tips.
///
/// [refspecs] is the list of refspecs to use for this fetch. Defaults to the base refspecs.
///
/// [reflogMessage] is the message to insert into the reflogs. Default is "fetch".
///
/// [prune] determines whether to perform a prune after the fetch.
///
/// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
/// specified url. By default connection isn't done through proxy.
///
/// [reflogMessage] is the message to insert into the reflogs. Default is "fetch".
/// [callbacks] is the combination of callback functions from [Callbacks] object.
///
/// Throws a [LibGit2Error] if error occured.
TransferProgress fetch({
@ -239,9 +249,16 @@ class Remote {
/// Performs a push.
///
/// [refspecs] is the list of refspecs to use for pushing. Defaults to the configured refspecs.
///
/// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
/// specified url. By default connection isn't done through proxy.
///
/// [callbacks] is the combination of callback functions from [Callbacks] object.
///
/// Throws a [LibGit2Error] if error occured.
void push({
required List<String> refspecs,
List<String> refspecs = const [],
String? proxy,
Callbacks callbacks = const Callbacks(),
}) {
@ -255,6 +272,8 @@ class Remote {
/// Prunes tracking refs that are no longer present on remote.
///
/// [callbacks] is the combination of callback functions from [Callbacks] object.
///
/// Throws a [LibGit2Error] if error occured.
void prune([Callbacks callbacks = const Callbacks()]) {
bindings.prune(
@ -282,25 +301,25 @@ class TransferProgress {
/// Pointer to memory address for allocated transfer progress object.
final Pointer<git_indexer_progress> _transferProgressPointer;
/// Returns total number of objects to download.
/// Total number of objects to download.
int get totalObjects => _transferProgressPointer.ref.total_objects;
/// Returns number of objects that have been indexed.
/// Number of objects that have been indexed.
int get indexedObjects => _transferProgressPointer.ref.indexed_objects;
/// Returns number of objects that have been downloaded.
/// Number of objects that have been downloaded.
int get receivedObjects => _transferProgressPointer.ref.received_objects;
/// Returns number of local objects that have been used to fix the thin pack.
/// Number of local objects that have been used to fix the thin pack.
int get localObjects => _transferProgressPointer.ref.local_objects;
/// Returns total number of deltas in the pack.
/// Total number of deltas in the pack.
int get totalDeltas => _transferProgressPointer.ref.total_deltas;
/// Returns number of deltas that have been indexed.
/// Number of deltas that have been indexed.
int get indexedDeltas => _transferProgressPointer.ref.indexed_deltas;
/// Returns number of bytes received up to now.
/// Number of bytes received up to now.
int get receivedBytes => _transferProgressPointer.ref.received_bytes;
@override

514
lib/src/repository.dart
View file

File diff suppressed because it is too large Load diff

10
lib/src/revparse.dart
View file

@ -13,7 +13,7 @@ class RevParse {
/// 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.
/// **IMPORTANT**: The returned object and reference should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
RevParse.ext({required Repository repo, required String spec}) {
@ -78,10 +78,14 @@ class RevSpec {
/// Pointer to memory address for allocated revspec object.
final Pointer<git_revspec> _revSpecPointer;
/// The left element of the revspec; must be freed by the user.
/// Left element of the revspec.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit get from => Commit(_revSpecPointer.ref.from.cast());
/// The right element of the revspec; must be freed by the user.
/// Right element of the revspec.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
Commit? get to {
return _revSpecPointer.ref.to == nullptr
? null

6
lib/src/revwalk.dart
View file

@ -5,7 +5,8 @@ import 'bindings/revwalk.dart' as bindings;
class RevWalk {
/// Initializes a new instance of the [RevWalk] class.
/// Should be freed with `free()` to release allocated memory.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
RevWalk(Repository repo) {
_revWalkPointer = bindings.create(repo.pointer);
}
@ -25,7 +26,8 @@ class RevWalk {
return pointers.map((e) => Commit(e)).toList();
}
/// Changes the sorting mode when iterating through the repository's contents.
/// Changes the sorting mode when iterating through the repository's contents
/// to provided [sorting] combination of [GitSort] modes.
///
/// Changing the sorting mode resets the walker.
void sorting(Set<GitSort> sorting) {

16
lib/src/signature.dart
View file

@ -9,15 +9,15 @@ class Signature {
/// Initializes a new instance of [Signature] class from provided pointer to
/// signature object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Signature(this._signaturePointer);
/// Initializes a new instance of [Signature] class from provided [name], [email],
/// and optional [time] in seconds from epoch and [offset] in minutes.
/// Creates new [Signature] from provided [name], [email], and optional [time]
/// in seconds from epoch and [offset] in minutes.
///
/// If [time] isn't provided [Signature] will be created with a timestamp of 'now'.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Signature.create({
required String name,
required String email,
@ -50,16 +50,16 @@ class Signature {
static Signature defaultSignature(Repository repo) =>
Signature(bindings.defaultSignature(repo.pointer));
/// Returns full name of the author.
/// Full name of the author.
String get name => _signaturePointer.ref.name.cast<Utf8>().toDartString();
/// Returns email of the author.
/// Email of the author.
String get email => _signaturePointer.ref.email.cast<Utf8>().toDartString();
/// Returns time in seconds from epoch.
/// Time in seconds from epoch.
int get time => _signaturePointer.ref.when.time;
/// Returns timezone offset in minutes.
/// Timezone offset in minutes.
int get offset => _signaturePointer.ref.when.offset;
@override

59
lib/src/stash.dart
View file

@ -2,20 +2,21 @@ import 'package:libgit2dart/libgit2dart.dart';
import 'bindings/stash.dart' as bindings;
class Stash {
/// Initializes a new instance of [Stash] class.
/// Initializes a new instance of [Stash] class from provided stash [index], [message]
/// and [oid].
const Stash({
required this.index,
required this.message,
required this.oid,
});
/// The position within the stash list.
/// Position within the stash list.
final int index;
/// The stash message.
/// Stash message.
final String message;
/// The commit oid of the stashed state.
/// Commit [Oid] of the stashed state.
final Oid oid;
/// Returns list of all the stashed states, first being the most recent.
@ -23,30 +24,47 @@ class Stash {
/// Saves the local modifications to a new stash.
///
/// [repo] is the owning repository.
///
/// [stasher] is the identity of the person performing the stashing.
///
/// [message] is optional description along with the stashed state.
///
/// [flags] is a combination of [GitStash] flags. Defaults to [GitStash.defaults].
///
/// Throws a [LibGit2Error] if error occured.
static Oid create({
required Repository repo,
required Signature stasher,
String? message,
bool keepIndex = false,
bool includeUntracked = false,
bool includeIgnored = false,
Set<GitStash> flags = const {GitStash.defaults},
}) {
int flags = 0;
if (keepIndex) flags |= GitStash.keepIndex.value;
if (includeUntracked) flags |= GitStash.includeUntracked.value;
if (includeIgnored) flags |= GitStash.includeIgnored.value;
final int flagsInt = flags.fold(0, (acc, e) => acc | e.value);
return Oid(bindings.save(
repoPointer: repo.pointer,
stasherPointer: stasher.pointer,
message: message,
flags: flags,
flags: flagsInt,
));
}
/// Applies a single stashed state from the stash list.
///
/// [index] is the position of the stashed state in the list. Defaults to last saved.
///
/// [reinstateIndex] whether to try to reinstate not only the working tree's changes,
/// but also the index's changes.
///
/// [strategy] is a combination of [GitCheckout] flags. Defaults to [GitCheckout.safe]
/// with [GitCheckout.recreateMissing].
///
/// [directory] is the alternative checkout path to workdir, can be null.
///
/// [paths] is a list of wildmatch patterns or paths. By default, all paths are processed.
/// If you pass a list of wildmatch patterns, those will be used to filter which paths
/// should be taken into account.
///
/// Throws a [LibGit2Error] if error occured.
static void apply({
required Repository repo,
@ -69,7 +87,8 @@ class Stash {
);
}
/// Removes a single stashed state from the stash list.
/// Removes a single stashed state from the stash list at provided [index]. Defaults to
/// the last saved stash.
///
/// Throws a [LibGit2Error] if error occured.
static void drop({required Repository repo, int index = 0}) {
@ -82,6 +101,20 @@ class Stash {
/// Applies a single stashed state from the stash list and remove it from
/// the list if successful.
///
/// [index] is the position of the stashed state in the list. Defaults to last saved.
///
/// [reinstateIndex] whether to try to reinstate not only the working tree's changes,
/// but also the index's changes.
///
/// [strategy] is a combination of [GitCheckout] flags. Defaults to [GitCheckout.safe]
/// with [GitCheckout.recreateMissing].
///
/// [directory] is the alternative checkout path to workdir, can be null.
///
/// [paths] is a list of wildmatch patterns or paths. By default, all paths are processed.
/// If you pass a list of wildmatch patterns, those will be used to filter which paths
/// should be taken into account.
///
/// Throws a [LibGit2Error] if error occured.
static void pop({
required Repository repo,

53
lib/src/submodule.dart
View file

@ -4,31 +4,31 @@ import 'bindings/libgit2_bindings.dart';
import 'bindings/submodule.dart' as bindings;
class Submodule {
/// Initializes a new instance of [Submodule] class by looking up
/// submodule information by name or path.
/// Lookups submodule information by [name] or path (they are usually the same).
///
/// 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.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Submodule.lookup({required Repository repo, required String submodule}) {
Submodule.lookup({required Repository repo, required String name}) {
_submodulePointer = bindings.lookup(
repoPointer: repo.pointer,
name: submodule,
name: name,
);
}
/// Adds a submodule to the index.
///
/// [url] is URL for the submodule's remote.
/// [url] is the URL for the submodule's remote.
///
/// [path] is path at which the submodule should be created.
/// [path] is the path at which the submodule should be created.
///
/// [link] determines if workdir should contain a gitlink to the repo in `.git/modules`
/// [useGitLink] determines if workdir should contain a gitlink to the repo in `.git/modules`
/// vs. repo directly in workdir. Default is true.
///
/// [callbacks] is the combination of callback functions from [Callbacks] object.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Submodule.add({
required Repository repo,
@ -55,7 +55,7 @@ class Submodule {
/// Copies submodule info into ".git/config" file.
///
/// Just like `git submodule init`, this copies information about the
/// submodule into `.git/config`.
/// submodule into ".git/config".
///
/// By default, existing entries will not be overwritten, but setting [overwrite]
/// to true forces them to be updated.
@ -112,10 +112,12 @@ class Submodule {
/// Opens the repository for a submodule.
///
/// This is a newly opened repository object. The caller is responsible for freeing it
/// when done. Multiple calls to this function will return distinct git repository objects.
/// Multiple calls to this function will return distinct git repository objects.
///
/// This will only work if the submodule is checked out into the working directory.
///
/// **IMPORTANT**: Returned [Repository] object should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Repository open() {
return Repository(bindings.open(_submodulePointer));
@ -158,16 +160,16 @@ class Submodule {
bindings.reload(submodulePointer: _submodulePointer, force: force);
}
/// Returns the name of submodule.
/// Name of submodule.
String get name => bindings.name(_submodulePointer);
/// Returns the path to the submodule.
/// Path to the submodule.
///
/// The path is almost always the same as the submodule name, but the two
/// are actually not required to match.
String get path => bindings.path(_submodulePointer);
/// Returns the URL for the submodule.
/// URL for the submodule.
String get url => bindings.url(_submodulePointer);
/// Sets the URL for the submodule in the configuration.
@ -182,7 +184,7 @@ class Submodule {
);
}
/// Returns the branch for the submodule.
/// Branch for the submodule.
String get branch => bindings.branch(_submodulePointer);
/// Sets the branch for the submodule in the configuration.
@ -197,22 +199,21 @@ class Submodule {
);
}
/// Returns the [Oid] for the submodule in the current HEAD tree or
/// null if submodule is not in the HEAD.
/// [Oid] for the submodule in the current HEAD tree or null if submodule is not
/// in the HEAD.
Oid? get headOid {
final result = bindings.headId(_submodulePointer);
return result == null ? null : Oid(result);
}
/// Returns the [Oid] for the submodule in the index or null if submodule
/// is not in the index.
/// [Oid] for the submodule in the index or null if submodule is not in the index.
Oid? get indexOid {
final result = bindings.indexId(_submodulePointer);
return result == null ? null : Oid(result);
}
/// Returns the [Oid] for the submodule in the current working directory or null if
/// submodule is not checked out.
/// [Oid] for the submodule in the current working directory or null if submodule
/// is not checked out.
///
/// This returns the [Oid] that corresponds to looking up `HEAD` in the checked out
/// submodule. If there are pending changes in the index or anything else, this
@ -223,7 +224,7 @@ class Submodule {
return result == null ? null : Oid(result);
}
/// Returns the ignore rule that will be used for the submodule.
/// Ignore rule that will be used for the submodule.
GitSubmoduleIgnore get ignore {
final ruleInt = bindings.ignore(_submodulePointer);
return GitSubmoduleIgnore.values.singleWhere((e) => ruleInt == e.value);
@ -237,7 +238,7 @@ class Submodule {
bindings.setIgnore(repoPointer: repo, name: name, ignore: ignore.value);
}
/// Returns the update rule that will be used for the submodule.
/// Update rule that will be used for the submodule.
///
/// This value controls the behavior of the `git submodule update` command.
GitSubmoduleUpdate get updateRule {

31
lib/src/tag.dart
View file

@ -8,12 +8,12 @@ class Tag {
/// Initializes a new instance of [Tag] class from provided pointer to
/// tag object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Tag(this._tagPointer);
/// Lookups tag object for provided [oid] in a [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Tag.lookup({required Repository repo, required Oid oid}) {
_tagPointer = bindings.lookup(
repoPointer: repo.pointer,
@ -31,10 +31,25 @@ class Tag {
///
/// The [message] will not be cleaned up.
///
/// The tag name will be checked for validity. You must avoid the characters
/// 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.
///
/// [tagger] is the signature of the tagger for this tag, and of the tagging time.
///
/// [message] is the full message for this tag.
///
/// [force] determines whether existing reference with the same [tagName] should be replaced.
///
/// Throws a [LibGit2Error] if error occured.
static Oid create({
required Repository repo,
@ -81,7 +96,7 @@ class Tag {
return bindings.list(repo.pointer);
}
/// Get the tagged object (commit, tree, blob, tag) of a tag.
/// Tagged object (commit, tree, blob, tag) of a tag.
///
/// This method performs a repository lookup for the given object and returns it.
///
@ -110,16 +125,16 @@ class Tag {
}
}
/// Returns the [Oid] of a tag.
/// [Oid] of a tag.
Oid get oid => Oid(bindings.id(_tagPointer));
/// Returns the name of a tag.
/// Name of a tag.
String get name => bindings.name(_tagPointer);
/// Returns the message of a tag.
/// Message of a tag.
String get message => bindings.message(_tagPointer);
/// Returns the tagger (author) of a tag if there is one.
/// Tagger (author) of a tag if there is one.
Signature? get tagger {
final sigPointer = bindings.tagger(_tagPointer);
if (sigPointer != nullptr) {

49
lib/src/tree.dart
View file

@ -8,12 +8,12 @@ class Tree {
/// Initializes a new instance of [Tree] class from provided pointer to
/// tree object in memory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Tree(this._treePointer);
/// Lookups a tree object for provided [oid] in a [repo]sitory.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
Tree.lookup({required Repository repo, required Oid oid}) {
_treePointer = bindings.lookup(
repoPointer: repo.pointer,
@ -26,7 +26,7 @@ class Tree {
/// Pointer to memory address for allocated tree object.
Pointer<git_tree> get pointer => _treePointer;
/// Returns a list with tree entries of a tree.
/// List with tree entries of a tree.
List<TreeEntry> get entries {
final entryCount = bindings.entryCount(_treePointer);
var result = <TreeEntry>[];
@ -47,6 +47,8 @@ class Tree {
/// If string [value] is provided, lookup is done by entry filename.
///
/// If provided string [value] is a path to file, lookup is done by path.
///
/// Throws [ArgumentError] if provided [value] is not int or string.
TreeEntry operator [](Object value) {
if (value is int) {
return TreeEntry(bindings.getByIndex(
@ -69,14 +71,22 @@ class Tree {
}
}
/// Returns the [Oid] of a tree.
/// [Oid] of a tree.
Oid get oid => Oid(bindings.id(_treePointer));
/// Get the number of entries listed in a tree.
/// Number of entries listed in a tree.
int get length => bindings.entryCount(_treePointer);
/// Creates a diff between a tree and the working directory.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
///
/// Throws a [LibGit2Error] if error occured.
Diff diffToWorkdir({
Set<GitDiff> flags = const {GitDiff.normal},
@ -93,6 +103,16 @@ class Tree {
}
/// Creates a diff between a tree and repository index.
///
/// [index] is the [Index] object to diff to.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
Diff diffToIndex({
required Index index,
Set<GitDiff> flags = const {GitDiff.normal},
@ -111,6 +131,16 @@ class Tree {
/// Creates a diff with the difference between two tree objects.
///
/// [tree] is the [Tree] object to diff to.
///
/// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
///
/// [contextLines] is the number of unchanged lines that define the boundary
/// of a hunk (and to display before and after). Defaults to 3.
///
/// [interhunkLines] is the maximum number of unchanged lines between hunk
/// boundaries before the hunks will be merged into one. Defaults to 0.
///
/// Throws a [LibGit2Error] if error occured.
Diff diffToTree({
required Tree tree,
@ -138,19 +168,20 @@ class Tree {
}
class TreeEntry {
/// Initializes a new instance of [TreeEntry] class.
/// Initializes a new instance of [TreeEntry] class from provided pointer to
/// tree entry object in memory.
const TreeEntry(this._treeEntryPointer);
/// Pointer to memory address for allocated tree entry object.
final Pointer<git_tree_entry> _treeEntryPointer;
/// Returns the [Oid] of the object pointed by the entry.
/// [Oid] of the object pointed by the entry.
Oid get oid => Oid(bindings.entryId(_treeEntryPointer));
/// Returns the filename of a tree entry.
/// Filename of a tree entry.
String get name => bindings.entryName(_treeEntryPointer);
/// Returns the UNIX file attributes of a tree entry.
/// UNIX file attributes of a tree entry.
GitFilemode get filemode {
final modeInt = bindings.entryFilemode(_treeEntryPointer);
return GitFilemode.values.singleWhere((mode) => modeInt == mode.value);

21
lib/src/treebuilder.dart
View file

@ -7,7 +7,7 @@ class TreeBuilder {
/// Initializes a new instance of [TreeBuilder] class from provided
/// [repo]sitory and optional [tree] objects.
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
TreeBuilder({required Repository repo, Tree? tree}) {
@ -20,7 +20,7 @@ class TreeBuilder {
/// Pointer to memory address for allocated tree builder object.
late final Pointer<git_treebuilder> _treeBuilderPointer;
/// Returns the number of entries listed in a tree builder.
/// Number of entries listed in a tree builder.
int get length => bindings.entryCount(_treeBuilderPointer);
/// Writes the contents of the tree builder as a tree object.
@ -29,11 +29,12 @@ class TreeBuilder {
/// Clears all the entires in the tree builder.
void clear() => bindings.clear(_treeBuilderPointer);
/// Returns an entry from the tree builder from its filename.
/// Returns an entry from the tree builder with provided [filename].
///
/// The returned entry is owned by the tree builder and should not be freed manually.
/// **IMPORTANT**: the returned entry is owned by the tree builder and
/// should not be freed manually.
///
/// Throws [ArgumentError] if nothing found for provided filename.
/// Throws [ArgumentError] if nothing found for provided [filename].
TreeEntry operator [](String filename) {
return TreeEntry(bindings.getByFilename(
builderPointer: _treeBuilderPointer,
@ -43,12 +44,18 @@ class TreeBuilder {
/// Adds or updates an entry to the tree builder with the given attributes.
///
/// If an entry named filename already exists, its attributes will be updated with
/// If an entry with [filename] already exists, its attributes will be updated with
/// the given ones.
///
/// By default the entry that you are inserting will be checked for validity;
/// that it exists in the object database and is of the correct type.
///
/// [filename] is the filename of the entry.
///
/// [oid] is [Oid] of the entry.
///
/// [filemode] is one of the [GitFilemode] folder attributes of the entry.
///
/// Throws a [LibGit2Error] if error occured.
void add({
required String filename,
@ -63,7 +70,7 @@ class TreeBuilder {
);
}
/// Removes an entry from the tree builder by its filename.
/// Removes an entry from the tree builder by its [filename].
///
/// Throws a [LibGit2Error] if error occured.
void remove(String filename) {

27
lib/src/worktree.dart
View file

@ -4,14 +4,18 @@ import 'bindings/libgit2_bindings.dart';
import 'bindings/worktree.dart' as bindings;
class Worktree {
/// Initializes a new instance of [Worktree] class by creating new worktree
/// with provided [Repository] object worktree [name], [path] and optional [ref]
/// [Reference] object.
/// Creates new worktree.
///
/// If [ref] is provided, no new branch will be created but specified [ref] will
/// be used instead.
///
/// Should be freed to release allocated memory.
/// [repo] is the repository to create working tree for.
///
/// [name] is the name of the working tree.
///
/// [path] is the path to create working tree at.
///
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Worktree.create({
@ -28,10 +32,9 @@ class Worktree {
);
}
/// Initializes a new instance of [Worktree] class by looking up existing worktree
/// with provided [Repository] object and worktree [name].
/// Lookups existing worktree in [repo] with provided [name].
///
/// Should be freed to release allocated memory.
/// **IMPORTANT**: Should be freed to release allocated memory.
///
/// Throws a [LibGit2Error] if error occured.
Worktree.lookup({required Repository repo, required String name}) {
@ -46,13 +49,13 @@ class Worktree {
/// Throws a [LibGit2Error] if error occured.
static List<String> list(Repository repo) => bindings.list(repo.pointer);
/// Returns the name of the worktree.
/// Name of the worktree.
String get name => bindings.name(_worktreePointer);
/// Returns the filesystem path for the worktree.
/// Filesystem path for the worktree.
String get path => bindings.path(_worktreePointer);
/// Checks if worktree is locked.
/// Whether worktree is locked.
///
/// A worktree may be locked if the linked working tree is stored on a portable
/// device which is not available.
@ -64,7 +67,7 @@ class Worktree {
/// Unlocks a locked worktree.
void unlock() => bindings.unlock(_worktreePointer);
/// Checks if the worktree prunable.
/// Whether worktree is prunable.
///
/// A worktree is not prunable in the following scenarios:
/// - the worktree is linking to a valid on-disk worktree.
@ -78,7 +81,7 @@ class Worktree {
/// Prune the working tree, that is remove the git data structures on disk.
void prune() => bindings.prune(_worktreePointer);
/// Checks if worktree is valid.
/// Whether worktree is valid.
///
/// A valid worktree requires both the git data structures inside the linked parent
/// repository and the linked working copy to be present.