From a24070c44cac15a92769e308dd3d904dc407b306 Mon Sep 17 00:00:00 2001 From: Aleksey Kulikov Date: Fri, 22 Oct 2021 14:41:15 +0300 Subject: [PATCH] docs: improve api documentation --- lib/src/blame.dart | 40 +-- lib/src/blob.dart | 48 +++- lib/src/branch.dart | 37 +-- lib/src/callbacks.dart | 14 ++ lib/src/commit.dart | 71 ++++-- lib/src/config.dart | 34 ++- lib/src/diff.dart | 90 ++++--- lib/src/index.dart | 63 +++-- lib/src/mailmap.dart | 12 +- lib/src/note.dart | 48 +++- lib/src/odb.dart | 29 +-- lib/src/oid.dart | 4 +- lib/src/packbuilder.dart | 8 +- lib/src/patch.dart | 35 ++- lib/src/rebase.dart | 22 +- lib/src/reference.dart | 48 ++-- lib/src/reflog.dart | 15 +- lib/src/refspec.dart | 14 +- lib/src/remote.dart | 77 +++--- lib/src/repository.dart | 514 ++++++++++++++++++++++++++++----------- lib/src/revparse.dart | 10 +- lib/src/revwalk.dart | 6 +- lib/src/signature.dart | 16 +- lib/src/stash.dart | 59 ++++- lib/src/submodule.dart | 53 ++-- lib/src/tag.dart | 31 ++- lib/src/tree.dart | 49 +++- lib/src/treebuilder.dart | 21 +- lib/src/worktree.dart | 27 +- test/commit_test.dart | 2 +- test/index_test.dart | 18 +- test/stash_test.dart | 11 +- 32 files changed, 1008 insertions(+), 518 deletions(-) diff --git a/lib/src/blame.dart b/lib/src/blame.dart index 4bf48cc..4bfbb5f 100644 --- a/lib/src/blame.dart +++ b/lib/src/blame.dart @@ -6,10 +6,13 @@ import 'bindings/libgit2_bindings.dart'; import 'bindings/blame.dart' as bindings; class Blame with IterableMixin { - /// 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 { /// [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 { )); } - /// 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 _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().toDartString(); diff --git a/lib/src/blob.dart b/lib/src/blob.dart index de4d07b..a1f9f18 100644 --- a/lib/src/blob.dart +++ b/lib/src/blob.dart @@ -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({ diff --git a/lib/src/branch.dart b/lib/src/branch.dart index d0bc570..63cf282 100644 --- a/lib/src/branch.dart +++ b/lib/src/branch.dart @@ -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); diff --git a/lib/src/callbacks.dart b/lib/src/callbacks.dart index 353c5de..e76d478 100644 --- a/lib/src/callbacks.dart +++ b/lib/src/callbacks.dart @@ -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, diff --git a/lib/src/commit.dart b/lib/src/commit.dart index 1b23329..621fb76 100644 --- a/lib/src/commit.dart +++ b/lib/src/commit.dart @@ -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 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 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 get parents { var parents = []; 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}) { diff --git a/lib/src/config.dart b/lib/src/config.dart index 781f459..54d4006 100644 --- a/lib/src/config.dart +++ b/lib/src/config.dart @@ -11,17 +11,17 @@ class Config with IterableMixin { /// 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 { } } - /// 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 { _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 { _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 { /// Pointer to memory address for allocated config object. late final Pointer _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 { } 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 _configEntryPointer; - /// Returns name of the entry (normalised). + /// Name of the entry (normalised). String get name => _configEntryPointer.ref.name.cast().toDartString(); - /// Returns value of the entry. + /// Value of the entry. String get value => _configEntryPointer.ref.value.cast().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, diff --git a/lib/src/diff.dart b/lib/src/diff.dart index d2ab0ad..a63c3ae 100644 --- a/lib/src/diff.dart +++ b/lib/src/diff.dart @@ -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 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 get patches { final length = bindings.length(_diffPointer); var patches = []; @@ -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(sizeOf()); @@ -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 flags = const {GitDiffFind.byConfig}, @@ -145,14 +164,14 @@ class DiffDelta { /// Pointer to memory address for allocated diff delta object. final Pointer _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 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().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 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 _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 _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 = []; 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 get lines { var lines = []; for (var i = 0; i < linesCount; i++) { @@ -339,26 +357,26 @@ class DiffLine { /// Pointer to memory address for allocated diff line object. final Pointer _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().toDartString(); diff --git a/lib/src/index.dart b/lib/src/index.dart index a01d429..7804310 100644 --- a/lib/src/index.dart +++ b/lib/src/index.dart @@ -10,7 +10,7 @@ class Index with IterableMixin { /// 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 _indexPointer; @@ -20,7 +20,8 @@ class Index with IterableMixin { /// 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 { } } - /// 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 { ); } - /// 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 { /// /// 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 { /// 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 { /// /// 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 { } } - /// 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 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 flags = const {GitDiff.normal}, int contextLines = 3, @@ -191,6 +203,16 @@ class Index with IterableMixin { } /// 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 flags = const {GitDiff.normal}, @@ -226,23 +248,18 @@ class IndexEntry { /// Pointer to memory address for allocated index entry object. Pointer 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().toDartString(); - /// Sets path of the index entry. set path(String path) => _indexEntryPointer.ref.path = path.toNativeUtf8().cast(); - /// 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 { diff --git a/lib/src/mailmap.dart b/lib/src/mailmap.dart index 497c58d..edc73d5 100644 --- a/lib/src/mailmap.dart +++ b/lib/src/mailmap.dart @@ -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, diff --git a/lib/src/note.dart b/lib/src/note.dart index 4b62446..31b3120 100644 --- a/lib/src/note.dart +++ b/lib/src/note.dart @@ -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 _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 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. diff --git a/lib/src/odb.dart b/lib/src/odb.dart index 678d567..8570961 100644 --- a/lib/src/odb.dart +++ b/lib/src/odb.dart @@ -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 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 _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. diff --git a/lib/src/oid.dart b/lib/src/oid.dart index 2d386dd..05d1841 100644 --- a/lib/src/oid.dart +++ b/lib/src/oid.dart @@ -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 get pointer => _oidPointer; - /// Returns hexadecimal SHA string. + /// Hexadecimal SHA string. String get sha => bindings.toSHA(_oidPointer); @override diff --git a/lib/src/packbuilder.dart b/lib/src/packbuilder.dart index e873723..0db715c 100644 --- a/lib/src/packbuilder.dart +++ b/lib/src/packbuilder.dart @@ -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( diff --git a/lib/src/patch.dart b/lib/src/patch.dart index 2ad3fdb..009c50f 100644 --- a/lib/src/patch.dart +++ b/lib/src/patch.dart @@ -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 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 get hunks { final length = bindings.numHunks(_patchPointer); final hunks = []; diff --git a/lib/src/rebase.dart b/lib/src/rebase.dart index 83fb9da..44fde1a 100644 --- a/lib/src/rebase.dart +++ b/lib/src/rebase.dart @@ -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 _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 _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 diff --git a/lib/src/reference.dart b/lib/src/reference.dart index e583c19..ad2a342 100644 --- a/lib/src/reference.dart +++ b/lib/src/reference.dart @@ -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 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 diff --git a/lib/src/reflog.dart b/lib/src/reflog.dart index 18fab99..c2583b3 100644 --- a/lib/src/reflog.dart +++ b/lib/src/reflog.dart @@ -6,6 +6,8 @@ import 'bindings/reflog.dart' as bindings; class RefLog with IterableMixin { /// 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 { /// Pointer to memory address for allocated reflog object. late final Pointer _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 { } 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 _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 diff --git a/lib/src/refspec.dart b/lib/src/refspec.dart index 2d2886a..e6950b1 100644 --- a/lib/src/refspec.dart +++ b/lib/src/refspec.dart @@ -11,26 +11,26 @@ class Refspec { /// Pointer to memory address for allocated refspec object. final Pointer _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, diff --git a/lib/src/remote.dart b/lib/src/remote.dart index 5951aff..29563b7 100644 --- a/lib/src/remote.dart +++ b/lib/src/remote.dart @@ -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 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 get fetchRefspecs => bindings.fetchRefspecs(_remotePointer); - /// Get the remote's list of push refspecs. + /// List of push refspecs. List 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 refspecs, + List 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 _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 diff --git a/lib/src/repository.dart b/lib/src/repository.dart index d78ec09..0bdc593 100644 --- a/lib/src/repository.dart +++ b/lib/src/repository.dart @@ -19,13 +19,38 @@ class Repository { /// Initializes a new instance of the [Repository] class from provided /// pointer to repository object in memory. /// - /// Should be freed with `free()` to release allocated memory. + /// **IMPORTANT**: Should be freed to release allocated memory. Repository(this._repoPointer); - /// Initializes a new instance of the [Repository] class by creating a new - /// git repository in the given folder. + /// Creates new git repository at the provided [path]. /// - /// Should be freed with `free()` to release allocated memory. + /// [path] is the path to the repository. + /// + /// [bare] whether new repository should be bare. + /// + /// [flags] is a combination of [GitRepositoryInit] flags. Defaults to + /// [GitRepositoryInit.mkdir]. + /// + /// [mode] is the permissions for the folder. Default to 0 (permissions configured by + /// umask). + /// + /// [workdirPath] is the path to the working directory. Can be null for default path. + /// + /// [description] if set will be used to initialize the "description" file in the + /// repository, instead of using the template content. + /// + /// [templatePath] is the the path to use for the template directory if + /// [GitRepositoryInit.externalTemplate] is set. Defaults to the config or default + /// directory options. + /// + /// [initialHead] is the name of the head to point HEAD at. If null, then this will be + /// treated as "master" and the HEAD ref will be set to "refs/heads/master". If this + /// begins with "refs/" it will be used verbatim, otherwise "refs/heads/" will be prefixed. + /// + /// [originUrl] if set, then after the rest of the repository initialization is completed, + /// an "origin" remote will be added pointing to this URL. + /// + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Repository.init({ @@ -59,14 +84,13 @@ class Repository { ); } - /// Initializes a new instance of the [Repository] class by opening repository - /// at provided [path]. + /// Opens repository at provided [path]. /// - /// For a standard repository, [path] should either point to the `.git` folder + /// For a standard repository, [path] should either point to the ".git" folder /// or to the working directory. For a bare repository, [path] should directly /// point to the repository folder. /// - /// Should be freed with `free()` to release allocated memory. + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Repository.open(String path) { @@ -75,8 +99,16 @@ class Repository { _repoPointer = bindings.open(path); } - /// Initializes a new instance of the [Repository] class by cloning a remote repository - /// at provided [url] into [localPath]. + /// Clones a remote repository at provided [url] into [localPath]. + /// + /// By default this creates its repository and initial remote to match git's defaults. + /// You can use the [remote] and [repository] options to customize how these are created. + /// + /// [url] is the remote repository to clone. + /// + /// [localPath] is the local directory to clone to. + /// + /// [bare] whether cloned repo should be bare. /// /// [remote] is the callback function with `Remote Function(Repository repo, String name, String url)` /// signature. The [Remote] it returns will be used instead of default one. @@ -87,6 +119,10 @@ class Repository { /// [checkoutBranch] is the name of the branch to checkout after the clone. Defaults /// to using the remote's default branch. /// + /// [callbacks] is the combination of callback functions from [Callbacks] object. + /// + /// **IMPORTANT**: Should be freed to release allocated memory. + /// /// Throws a [LibGit2Error] if error occured. Repository.clone({ required String url, @@ -115,7 +151,7 @@ class Repository { /// Pointer to memory address for allocated repository object. Pointer get pointer => _repoPointer; - /// Look for a git repository and return its path. The lookup start from [startPath] + /// Looks for a git repository and return its path. The lookup start from [startPath] /// and walk across parent directories if nothing has been found. The lookup ends when /// the first repository is found, or when reaching a directory referenced in [ceilingDirs]. /// @@ -130,36 +166,35 @@ class Repository { /// Returns [Oid] object if it can be found in the ODB of repository with /// provided hexadecimal [sha] string that is 40 characters long or shorter. /// - /// Throws [ArgumentError] if provided [sha] hex string is not valid. - /// - /// Throws a [LibGit2Error] if error occured. + /// Throws [ArgumentError] if provided [sha] hex string is not valid or + /// [LibGit2Error] if error occured. Oid operator [](String sha) { return Oid.fromSHA(repo: this, sha: sha); } - /// Returns path to the `.git` folder for normal repositories - /// or path to the repository itself for bare repositories. + /// Path to the ".git" folder for normal repositories or path to the repository + /// itself for bare repositories. String get path => bindings.path(_repoPointer); - /// Returns the path of the shared common directory for this repository. + /// Path of the shared common directory for this repository. /// /// If the repository is bare, it is the root directory for the repository. - /// If the repository is a worktree, it is the parent repo's `.git` folder. - /// Otherwise, it is the `.git` folder. + /// If the repository is a worktree, it is the parent repo's ".git" folder. + /// Otherwise, it is the ".git" folder. String get commonDir => bindings.commonDir(_repoPointer); - /// Returns the currently active namespace for this repository. + /// Currently active namespace for this repository. /// /// If there is no namespace, or the namespace is not a valid utf8 string, /// empty string is returned. String get namespace => bindings.getNamespace(_repoPointer); - /// Sets the active namespace for this repository. + /// Sets the active [namespace] for this repository. /// /// This namespace affects all reference operations for the repo. See `man gitnamespaces` /// /// The [namespace] should not include the refs folder, e.g. to namespace all references - /// under refs/namespaces/foo/, use foo as the namespace. + /// under "refs/namespaces/foo/", use "foo" as the namespace. /// /// Pass null to unset. void setNamespace(String? namespace) { @@ -169,10 +204,10 @@ class Repository { ); } - /// Checks whether this repository is a bare repository or not. + /// Whether repository is a bare repository. bool get isBare => bindings.isBare(_repoPointer); - /// Check if a repository is empty. + /// Whether repository is empty. /// /// An empty repository has just been initialized and contains no references /// apart from HEAD, which must be pointing to the unborn master branch. @@ -180,7 +215,7 @@ class Repository { /// Throws a [LibGit2Error] if repository is corrupted. bool get isEmpty => bindings.isEmpty(_repoPointer); - /// Checks if a repository's HEAD is detached. + /// Whether repository's HEAD is detached. /// /// A repository's HEAD is detached when it points directly to a commit instead of a branch. /// @@ -201,7 +236,7 @@ class Repository { /// Otherwise, the HEAD will be detached and will directly point to the Commit. /// /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided [target] - /// is not Oid or String. + /// is not [Oid] or string. void setHead(Object target) { if (target is Oid) { bindings.setHeadDetached( @@ -216,7 +251,7 @@ class Repository { } } - /// Checks if the current branch is unborn. + /// Whether current branch is unborn. /// /// An unborn branch is one named from HEAD but which doesn't exist in the refs namespace, /// because it doesn't have any commit to point to. @@ -228,8 +263,10 @@ class Repository { /// Sets the identity to be used for writing reflogs. /// - /// If both are set, this name and email will be used to write to the reflog. - /// Pass null to unset. When unset, the identity will be taken from the repository's configuration. + /// If both are set, this [name] and [email] will be used to write to the reflog. + /// + /// Pass null to unset. When unset, the identity will be taken from the + /// repository's configuration. void setIdentity({required String? name, required String? email}) { bindings.setIdentity( repoPointer: _repoPointer, @@ -238,24 +275,25 @@ class Repository { ); } - /// Returns the configured identity to use for reflogs. + /// Configured identity to use for reflogs. Map get identity => bindings.identity(_repoPointer); - /// Checks if the repository was a shallow clone. + /// Whether repository was a shallow clone. bool get isShallow => bindings.isShallow(_repoPointer); - /// Checks if a repository is a linked work tree. + /// Whether repository is a linked work tree. bool get isWorktree => bindings.isWorktree(_repoPointer); - /// Retrieves git's prepared message. + /// Git's prepared message. /// - /// Operations such as git revert/cherry-pick/merge with the -n option + /// Operations such as `git revert/cherry-pick/merge` with the "-n" option /// stop just short of creating a commit with the changes and save their - /// prepared message in .git/MERGE_MSG so the next git-commit execution + /// prepared message in ".git/MERGE_MSG" so the next git-commit execution /// can present it to the user for them to amend if they wish. /// /// Use this function to get the contents of this file. - /// Don't forget to remove the file with [removeMessage] after you create the commit. + /// + /// **IMPORTANT**: remove the file with [removeMessage] after you create the commit. /// /// Throws a [LibGit2Error] if error occured. String get message => bindings.message(_repoPointer); @@ -263,8 +301,8 @@ class Repository { /// Removes git's prepared message. void removeMessage() => bindings.removeMessage(_repoPointer); - /// Returns the status of a git repository - ie, whether an operation - /// (merge, cherry-pick, etc) is in progress. + /// Status of a git repository - ie, whether an operation (merge, cherry-pick, etc) + /// is in progress. GitRepositoryState get state { final stateInt = bindings.state(_repoPointer); return GitRepositoryState.values.singleWhere( @@ -278,20 +316,23 @@ class Repository { /// Throws a [LibGit2Error] if error occured. void stateCleanup() => bindings.stateCleanup(_repoPointer); - /// Returns the path of the working directory for this repository. + /// Path of the working directory for this repository. /// - /// If the repository is bare, this function will always return empty string. + /// If the repository is bare, this method will always return empty string. String get workdir => bindings.workdir(_repoPointer); - /// Sets the path to the working directory for this repository. + /// Sets the [path] to the working directory for this repository. /// /// The working directory doesn't need to be the same one that contains the - /// `.git` folder for this repository. + /// ".git" folder for this repository. /// /// If this repository is bare, setting its working directory will turn it into a /// normal repository, capable of performing all the common workdir operations /// (checkout, status, index manipulation, etc). /// + /// [updateGitLink] if set creates/updates gitlink in workdir and sets config + /// "core.worktree" (if workdir is not the parent of the ".git" directory) + /// /// Throws a [LibGit2Error] if error occured. void setWorkdir({required String path, bool updateGitlink = false}) { bindings.setWorkdir( @@ -312,53 +353,54 @@ class Repository { 'state: $state, workdir: $workdir}'; } - /// Returns the configuration file for this repository. + /// Configuration file for this repository. /// /// 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. + /// **IMPORTANT**: Should be freed to release allocated memory. Config get config => Config(bindings.config(_repoPointer)); - /// Returns a snapshot of the repository's configuration. + /// Snapshot of the repository's configuration. /// /// 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. + /// **IMPORTANT**: Should be freed to release allocated memory. Config get configSnapshot => Config(bindings.configSnapshot(_repoPointer)); - /// Returns [Reference] object pointing to repository head. + /// Repository's head. /// - /// Must be freed once it's no longer being used. + /// **IMPORTANT**: Should be freed to release allocated memory. Reference get head => Reference(bindings.head(_repoPointer)); - /// Returns a list of all the references that can be found in a repository. + /// List of all the references names that can be found in a repository. /// /// Throws a [LibGit2Error] if error occured. List get references => Reference.list(this); - /// Lookups reference [name] in a [repo]sitory. - /// - /// Should be freed to release allocated memory. + /// Lookups reference [name] in a repository. /// /// The [name] will be checked for validity. /// + /// **IMPORTANT**: Should be freed to release allocated memory. + /// /// Throws a [LibGit2Error] if error occured. Reference lookupReference(String name) { return Reference.lookup(repo: this, name: name); } - /// Creates a new reference. + /// Creates a new reference for provided [target]. /// /// The reference will be created in the repository 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. /// @@ -392,7 +434,7 @@ class Repository { /// Throws a [LibGit2Error] if error occured. void deleteReference(String name) => Reference.delete(repo: this, name: name); - /// Renames an existing reference. + /// Renames an existing reference with provided [oldName]. /// /// This method works for both direct and symbolic references. /// @@ -420,34 +462,36 @@ class Repository { ); } - /// Returns [Index] file for this repository. + /// Index file for this repository. /// - /// Must be freed once it's no longer being used. + /// **IMPORTANT**: Should be freed to release allocated memory. Index get index => Index(bindings.index(_repoPointer)); - /// Returns [Odb] for this repository. + /// ODB for this repository. /// - /// ODB Object must be freed once it's no longer being used. + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Odb get odb => Odb(bindings.odb(_repoPointer)); /// Lookups a tree object for provided [oid]. /// - /// Should be freed to release allocated memory. + /// **IMPORTANT**: Should be freed to release allocated memory. Tree lookupTree(Oid oid) { return Tree.lookup(repo: this, oid: oid); } /// Creates a new action signature with default user and now timestamp. /// - /// This looks up the user.name and user.email from the configuration and uses the + /// 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 that information. Signature get defaultSignature => Signature.defaultSignature(this); /// Returns the list of commits starting from provided commit [oid]. /// /// If [sorting] isn't provided default will be used (reverse chronological order, like in git). + /// + /// **IMPORTANT**: Commits should be freed to release allocated memory. List log({ required Oid oid, Set sorting = const {GitSort.none}, @@ -467,7 +511,7 @@ class Repository { /// 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. + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Commit revParseSingle(String spec) { @@ -476,19 +520,36 @@ class Repository { /// Lookups commit object for provided [oid]. /// - /// Should be freed to release allocated memory. + /// **IMPORTANT**: Should be freed to release allocated memory. Commit lookupCommit(Oid oid) { return Commit.lookup(repo: this, oid: oid); } /// Creates new commit in the repository. /// - /// [updateRef] is name of the reference that will be updated to point to this 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. Oid createCommit({ required String message, @@ -503,7 +564,7 @@ class Repository { repo: this, message: message, author: author, - commiter: commiter, + committer: commiter, tree: tree, parents: parents, ); @@ -519,6 +580,12 @@ class Repository { /// 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. Oid amendCommit({ required Commit commit, @@ -541,12 +608,12 @@ class Repository { ); } - /// Reverts the given commit against the given "our" commit, producing an index that + /// Reverts provided [revertCommit] against provided [ourCommit], producing an index that /// reflects the result of the revert. /// /// [mainline] is parent of the [revertCommit] if it is a merge (i.e. 1, 2). /// - /// The returned index must be freed explicitly with `free()`. + /// **IMPORTANT**: produced index should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Index revertCommit({ @@ -571,7 +638,7 @@ class Repository { /// 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 released when no longer needed. /// /// Throws a [LibGit2Error] if error occured. RevParse revParseExt(String spec) { @@ -601,7 +668,7 @@ class Repository { Oid createBlob(String content) => Blob.create(repo: this, content: content); /// Creates a new blob from the file in working directory of a repository and writes - /// it to the ODB. Provided [path] should be relative to the working directory. + /// it to the ODB. Provided [relativePath] should be relative to the working directory. /// /// Throws a [LibGit2Error] if error occured. Oid createBlobFromWorkdir(String relativePath) { @@ -611,21 +678,22 @@ class Repository { ); } - /// Creates a new blob from the file in filesystem and writes it to the ODB. + /// Creates a new blob from the file at provided [path] in filesystem and writes + /// it to the ODB. /// /// Throws a [LibGit2Error] if error occured. Oid createBlobFromDisk(String path) { return Blob.createFromDisk(repo: this, path: path); } - /// Returns a list with all the tags in the repository. + /// List with all the tags names in the repository. /// /// Throws a [LibGit2Error] if error occured. List get tags => Tag.list(this); /// Lookups tag object for provided [oid]. /// - /// Should be freed to release allocated memory. + /// **IMPORTANT**: Should be freed to release allocated memory. Tag lookupTag(Oid oid) => Tag.lookup(repo: this, oid: oid); /// Creates a new tag in the repository for provided [target] object. @@ -635,10 +703,23 @@ class Repository { /// /// 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. /// + /// [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. Oid createTag({ required String tagName, @@ -665,27 +746,24 @@ class Repository { /// Throws a [LibGit2Error] if error occured. void deleteTag(String name) => Tag.delete(repo: this, name: name); - /// Returns a list of all branches that can be found in a repository. + /// List of all branches that can be found in a repository. /// - /// IMPORTANT: Branches must be freed manually when no longer needed to prevent - /// memory leak. + /// **IMPORTANT**: Branches should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. List get branches => Branch.list(repo: this); - /// Returns a list of local branches that can be found in a repository. + /// List of local branches that can be found in a repository. /// - /// IMPORTANT: Branches must be freed manually when no longer needed to prevent - /// memory leak. + /// **IMPORTANT**: Branches should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. List get branchesLocal => Branch.list(repo: this, type: GitBranch.local); - /// Returns a list of remote branches that can be found in a repository. + /// List of remote branches that can be found in a repository. /// - /// IMPORTANT: Branches must be freed manually when no longer needed to prevent - /// memory leak. + /// **IMPORTANT**: Branches should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. List get branchesRemote => @@ -698,7 +776,7 @@ class Repository { /// 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**: Branches should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Branch lookupBranch({ @@ -711,12 +789,16 @@ class Repository { /// 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 repo. + /// + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Branch createBranch({ @@ -732,14 +814,14 @@ class Repository { ); } - /// Deletes an existing branch reference. + /// Deletes an existing branch reference with provided [name]. /// /// Throws a [LibGit2Error] if error occured. void deleteBranch(String name) => Branch.delete(repo: this, name: name); - /// 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. /// @@ -752,7 +834,9 @@ class Repository { Branch.rename(repo: this, oldName: oldName, newName: newName, force: force); } - /// Checks status of the repository and returns map of file paths and their statuses. + /// Status of the repository. + /// + /// Returns map of file paths and their statuses. /// /// Returns empty map if there are no changes in statuses. /// @@ -792,7 +876,7 @@ class Repository { return result; } - /// Returns file status for a single file. + /// Returns file status for a single file at provided [path]. /// /// This does not do any sort of rename detection. Renames require a set of targets and because /// of the path filtering, there is not enough information to check renames correctly. To check @@ -817,7 +901,7 @@ class Repository { } } - /// Finds a merge base between two commits. + /// Finds a merge base between two commits [a] and [b]. /// /// Throws a [LibGit2Error] if error occured. Oid mergeBase({required Oid a, required Oid b}) { @@ -828,8 +912,8 @@ class Repository { )); } - /// Analyzes the given branch(es) and determines the opportunities for merging them - /// into a reference (default is 'HEAD'). + /// Analyzes the given branch's [theirHead] oid and determines the opportunities for + /// merging them into [ourRef] reference (default is 'HEAD'). /// /// Returns list with analysis result and preference for fast forward merge values /// respectively. @@ -885,9 +969,9 @@ class Repository { theirHead.free(); } - /// Merges two files as they exist in the index, using the given common ancestor - /// as the baseline, producing a string that reflects the merge result containing - /// possible conflicts. + /// Merges two files [ours] and [theirs] as they exist in the index, using the + /// given common [ancestor] as the baseline, producing a string that reflects + /// the merge result containing possible conflicts. /// /// Throws a [LibGit2Error] if error occured. String mergeFileFromIndex({ @@ -908,7 +992,19 @@ class Repository { /// 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. + /// [ourCommit] is the commit that reflects the destination tree. + /// + /// [theirCommit] is the commit to merge into [ourCommit]. + /// + /// [favor] is one of the [GitMergeFileFavor] flags for handling conflicting content. Defaults + /// to [GitMergeFileFavor.normal], recording conflict to the index. + /// + /// [mergeFlags] is a combination of [GitMergeFlag] flags. Defaults to [GitMergeFlag.findRenames] + /// enabling the ability to merge between a modified and renamed file. + /// + /// [fileFlags] is a combination of [GitMergeFileFlag] flags. Defaults to [GitMergeFileFlag.defaults]. + /// + /// **IMPORTANT**: returned index should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Index mergeCommits({ @@ -933,11 +1029,25 @@ class Repository { /// 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. + /// [ancestorTree] is the common ancestor between the trees, or null if none. + /// + /// [ourTree] is the tree that reflects the destination tree. + /// + /// [theirTree] is the tree to merge into [ourTree]. + /// + /// [favor] is one of the [GitMergeFileFavor] flags for handling conflicting content. Defaults + /// to [GitMergeFileFavor.normal], recording conflict to the index. + /// + /// [mergeFlags] is a combination of [GitMergeFlag] flags. Defaults to [GitMergeFlag.findRenames] + /// enabling the ability to merge between a modified and renamed file. + /// + /// [fileFlags] is a combination of [GitMergeFileFlag] flags. Defaults to [GitMergeFileFlag.defaults]. + /// + /// **IMPORTANT**: returned index should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. Index mergeTrees({ - required Tree ancestorTree, + Tree? ancestorTree, required Tree ourTree, required Tree theirTree, GitMergeFileFavor favor = GitMergeFileFavor.normal, @@ -946,7 +1056,7 @@ class Repository { }) { return Index(merge_bindings.mergeTrees( repoPointer: _repoPointer, - ancestorTreePointer: ancestorTree.pointer, + ancestorTreePointer: ancestorTree?.pointer ?? nullptr, ourTreePointer: ourTree.pointer, theirTreePointer: theirTree.pointer, favor: favor.value, @@ -1031,6 +1141,12 @@ class Repository { /// Sets the current head to the specified commit [oid] and optionally resets the index /// and working tree to match. /// + /// [oid] is the committish to which the HEAD should be moved to. This object can either + /// be a commit or a tag. When a tag oid is being passed, it should be dereferencable to + /// a commit which oid will be used as the target of the branch. + /// + /// [resetType] is one of the [GitReset] flags. + /// /// Throws a [LibGit2Error] if error occured. void reset({required Oid oid, required GitReset resetType}) { final object = object_bindings.lookup( @@ -1055,6 +1171,16 @@ class Repository { /// If [b] is null, by default the [a] tree compared to working directory. If [cached] is /// set to true the [a] tree compared to index/staging area. /// + /// [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. Diff diff({ Tree? a, @@ -1109,6 +1235,24 @@ class Repository { /// Returns a [Patch] with changes between the blobs. /// + /// [a] is the blob for old side of diff. + /// + /// [b] is the blob for new side of diff. + /// + /// [aPath] treat [a] blob as if it had this filename, can be null. + /// + /// [bPath] treat [b] 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 diffBlobs({ required Blob a, @@ -1122,8 +1266,8 @@ class Repository { return a.diff(newBlob: b, oldAsPath: aPath, newAsPath: bPath); } - /// Applies the [diff] to the given repository, making changes directly in the - /// working directory (default), the index, or both. + /// Applies the [diff] to the repository, making changes in the provided [location] + /// (directly in the working directory (default), the index or both). /// /// Throws a [LibGit2Error] if error occured. void apply({ @@ -1137,7 +1281,8 @@ class Repository { ); } - /// Checks if the [diff] will apply to the working directory (default), the index, or both. + /// Checks if the [diff] will apply to provided [location] (the working directory (default), + /// the index or both). bool applies({ required Diff diff, GitApplyLocation location = GitApplyLocation.workdir, @@ -1155,26 +1300,42 @@ class Repository { /// Saves the local modifications to a new stash. /// + /// [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. Oid createStash({ required Signature stasher, String? message, - bool keepIndex = false, - bool includeUntracked = false, - bool includeIgnored = false, + Set flags = const {GitStash.defaults}, }) { return Stash.create( repo: this, stasher: stasher, message: message, - keepIndex: keepIndex, - includeUntracked: includeUntracked, - includeIgnored: includeIgnored, + flags: flags, ); } /// 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. void applyStash({ int index = 0, @@ -1196,7 +1357,8 @@ class Repository { ); } - /// 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. void dropStash({int index = 0}) { @@ -1206,6 +1368,20 @@ class Repository { /// 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. void popStash({ int index = 0, @@ -1227,20 +1403,24 @@ class Repository { ); } - /// Returns a list of the configured remotes for a repository. + /// List of the configured remotes names for a repository. List get remotes => Remote.list(this); /// Lookups remote with provided [name]. /// - /// 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 lookupRemote(String name) { return Remote.lookup(repo: this, name: name); } - /// Adds a remote with provided [name] and [url] to the repository's - /// configuration with the default [fetch] refspec if none provided . + /// Adds remote with provided [name] and [url] to the repository'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 createRemote({ @@ -1251,20 +1431,20 @@ class Repository { return Remote.create(repo: this, name: name, url: url, fetch: fetch); } - /// 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. /// /// Throws a [LibGit2Error] if error occured. void deleteRemote(String name) => Remote.delete(repo: this, 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. @@ -1277,7 +1457,7 @@ class Repository { return Remote.rename(repo: this, oldName: oldName, newName: newName); } - /// Looks up the value of one git attribute for path. + /// Lookups the value of one git attribute with provided [name] for [path]. /// /// Returned value can be either `true`, `false`, `null` (if the attribute was not set at all), /// or a [String] value, if the attribute was set to an actual string. @@ -1294,9 +1474,11 @@ class Repository { ); } - /// Gets the blame for a single file. + /// Returns the blame for a single file. /// - /// [flags] is a combination of [GitBlameFlag]s. + /// [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 @@ -1315,6 +1497,8 @@ class Repository { /// [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 blame({ required String path, @@ -1337,18 +1521,20 @@ class Repository { ); } - /// Returns list of notes for repository. + /// List of notes for repository. /// - /// 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. List get notes => Note.list(this); - /// 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. + /// [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 lookupNote({ @@ -1362,7 +1548,19 @@ class Repository { ); } - /// Adds a note for an [annotatedOid]. + /// Creates a note for an [annotatedOid]. + /// + /// [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. Oid createNote({ @@ -1386,6 +1584,14 @@ class Repository { /// Deletes the note for an [annotatedOid]. /// + /// [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. void deleteNote({ required Oid annotatedOid, @@ -1402,7 +1608,7 @@ class Repository { ); } - /// Checks if a commit is the descendant of another commit. + /// Checks if a provided [commit] is the descendant of another [ancestor] commit. /// /// Note that a commit is not considered a descendant of itself, in contrast to /// `git merge-base --is-ancestor`. @@ -1421,6 +1627,10 @@ class Repository { /// There is no need for branches containing the commits to have any upstream relationship, /// but it helps to think of one as a branch and the other as its upstream, the ahead and /// behind values will be what git would report for the branches. + /// + /// [local] is the commit oid for local. + /// + /// [upstream] is the commit oid for upstream. List aheadBehind({ required Oid local, required Oid upstream, @@ -1432,7 +1642,7 @@ class Repository { ); } - /// Describes a commit or the current worktree. + /// Describes a [commit] if provided or the current worktree. /// /// [maxCandidatesTags] is the number of candidate tags to consider. Increasing above 10 will /// take slightly longer but may produce a more accurate result. A value of 0 will cause @@ -1506,7 +1716,7 @@ class Repository { } /// Packs the objects in the odb chosen by the [packDelegate] function and - /// writes .pack and .idx files for them into provided [path] or default location. + /// writes ".pack" and ".idx" files for them into provided [path] or default location. /// /// Returns the number of objects written to the pack. /// @@ -1543,22 +1753,22 @@ class Repository { return result; } - /// Returns a list with all tracked submodules paths of a repository. + /// List with all tracked submodules paths of a repository. List get submodules => Submodule.list(this); - /// Lookups submodule by name or path. + /// Lookups submodule information by [name] or path (they are usually the same). /// - /// You must free submodule when done with it. + /// **IMPORTANT**: Should be freed to release allocated memory. /// /// Throws a [LibGit2Error] if error occured. - Submodule lookupSubmodule(String submodule) { - return Submodule.lookup(repo: this, submodule: submodule); + Submodule lookupSubmodule(String name) { + return Submodule.lookup(repo: this, name: name); } /// 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. @@ -1597,13 +1807,17 @@ class Repository { /// 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 addSubmodule({ required String url, @@ -1620,14 +1834,14 @@ class Repository { ); } - /// Returns list of names of linked working trees. + /// List of linked working trees names. /// /// Throws a [LibGit2Error] if error occured. List get worktrees => Worktree.list(this); - /// Lookups up existing worktree for provided [name]. + /// Lookups existing worktree 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 lookupWorktree(String name) { @@ -1639,7 +1853,11 @@ class Repository { /// If [ref] is provided, no new branch will be created but specified [ref] will /// be used instead. /// - /// Should be freed with `free()` to release allocated memory. + /// [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 createWorktree({ diff --git a/lib/src/revparse.dart b/lib/src/revparse.dart index fb3f8f7..b15084c 100644 --- a/lib/src/revparse.dart +++ b/lib/src/revparse.dart @@ -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 _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 diff --git a/lib/src/revwalk.dart b/lib/src/revwalk.dart index a87bd9c..07ddf97 100644 --- a/lib/src/revwalk.dart +++ b/lib/src/revwalk.dart @@ -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 sorting) { diff --git a/lib/src/signature.dart b/lib/src/signature.dart index 84718d7..10a64ed 100644 --- a/lib/src/signature.dart +++ b/lib/src/signature.dart @@ -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().toDartString(); - /// Returns email of the author. + /// Email of the author. String get email => _signaturePointer.ref.email.cast().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 diff --git a/lib/src/stash.dart b/lib/src/stash.dart index ed42322..4b92c0c 100644 --- a/lib/src/stash.dart +++ b/lib/src/stash.dart @@ -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 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, diff --git a/lib/src/submodule.dart b/lib/src/submodule.dart index 68395f4..ab6d45d 100644 --- a/lib/src/submodule.dart +++ b/lib/src/submodule.dart @@ -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 { diff --git a/lib/src/tag.dart b/lib/src/tag.dart index 1631382..4c5970b 100644 --- a/lib/src/tag.dart +++ b/lib/src/tag.dart @@ -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) { diff --git a/lib/src/tree.dart b/lib/src/tree.dart index e17f2c5..357f30a 100644 --- a/lib/src/tree.dart +++ b/lib/src/tree.dart @@ -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 get pointer => _treePointer; - /// Returns a list with tree entries of a tree. + /// List with tree entries of a tree. List get entries { final entryCount = bindings.entryCount(_treePointer); var result = []; @@ -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 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 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 _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); diff --git a/lib/src/treebuilder.dart b/lib/src/treebuilder.dart index 8e9816f..f957cba 100644 --- a/lib/src/treebuilder.dart +++ b/lib/src/treebuilder.dart @@ -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 _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) { diff --git a/lib/src/worktree.dart b/lib/src/worktree.dart index 812d305..f6c26dd 100644 --- a/lib/src/worktree.dart +++ b/lib/src/worktree.dart @@ -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 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. diff --git a/test/commit_test.dart b/test/commit_test.dart index b73fa28..987b9d2 100644 --- a/test/commit_test.dart +++ b/test/commit_test.dart @@ -175,7 +175,7 @@ void main() { repo: repo, message: message, author: author, - commiter: commiter, + committer: commiter, tree: tree, parents: [parent1, parent2], ); diff --git a/test/index_test.dart b/test/index_test.dart index 207e109..b8f52c9 100644 --- a/test/index_test.dart +++ b/test/index_test.dart @@ -37,12 +37,12 @@ void main() { test('returns index entry at provided position', () { expect(index[3].path, 'file'); - expect(index[3].sha, fileSha); + expect(index[3].oid.sha, fileSha); }); test('returns index entry at provided path', () { expect(index['file'].path, 'file'); - expect(index['file'].sha, fileSha); + expect(index['file'].oid.sha, fileSha); }); test('throws if provided entry position is out of bounds', () { @@ -93,13 +93,13 @@ void main() { final entry = index['file']; index.add(entry); - expect(index['file'].sha, fileSha); + expect(index['file'].oid.sha, fileSha); expect(index.length, 4); }); test('successfully adds with provided path string', () { index.add('file'); - expect(index['file'].sha, fileSha); + expect(index['file'].oid.sha, fileSha); expect(index.length, 4); }); @@ -155,21 +155,21 @@ void main() { index.addAll(['file', 'feature_file']); expect(index.length, 2); - expect(index['file'].sha, fileSha); - expect(index['feature_file'].sha, featureFileSha); + expect(index['file'].oid.sha, fileSha); + expect(index['feature_file'].oid.sha, featureFileSha); index.clear(); index.addAll(['[f]*']); expect(index.length, 2); - expect(index['file'].sha, fileSha); - expect(index['feature_file'].sha, featureFileSha); + expect(index['file'].oid.sha, fileSha); + expect(index['feature_file'].oid.sha, featureFileSha); index.clear(); index.addAll(['feature_f???']); expect(index.length, 1); - expect(index['feature_file'].sha, featureFileSha); + expect(index['feature_file'].oid.sha, featureFileSha); }); test('throws when trying to addAll in bare repository', () { diff --git a/test/stash_test.dart b/test/stash_test.dart index 2c4f6f0..28adb4f 100644 --- a/test/stash_test.dart +++ b/test/stash_test.dart @@ -54,8 +54,7 @@ void main() { repo.createStash( stasher: stasher, - includeUntracked: true, - includeIgnored: true, + flags: {GitStash.includeUntracked, GitStash.includeIgnored}, ); expect(repo.status.isEmpty, true); expect(swpPath.existsSync(), false); @@ -72,7 +71,7 @@ void main() { final index = repo.index; index.add('file'); - repo.createStash(stasher: stasher, keepIndex: true); + repo.createStash(stasher: stasher, flags: {GitStash.keepIndex}); expect(repo.status.isEmpty, false); expect(repo.stashes.length, 1); @@ -111,7 +110,7 @@ void main() { index.add('stash.this'); expect(index.find('stash.this'), true); - repo.createStash(stasher: stasher, includeUntracked: true); + repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked}); expect(repo.status.isEmpty, true); expect(index.find('stash.this'), false); @@ -204,7 +203,7 @@ void main() { index.add('stash.this'); expect(index.find('stash.this'), true); - repo.createStash(stasher: stasher, includeUntracked: true); + repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked}); expect(repo.status.isEmpty, true); expect(index.find('stash.this'), false); @@ -252,7 +251,7 @@ void main() { test('returns string representation of Stash object', () { File('${tmpDir.path}/stash.this').writeAsStringSync('stash'); - repo.createStash(stasher: stasher, includeUntracked: true); + repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked}); expect(repo.stashes[0].toString(), contains('Stash{')); }); });