diff --git a/analysis_options.yaml b/analysis_options.yaml index 46d4433..cc78928 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -4,6 +4,7 @@ linter: - prefer_const_constructors - sort_constructors_first - directives_ordering + - lines_longer_than_80_chars analyzer: exclude: - lib/src/bindings/libgit2_bindings.dart diff --git a/example/config_example.dart b/example/config_example.dart index 1fa1618..fec97f5 100644 --- a/example/config_example.dart +++ b/example/config_example.dart @@ -28,8 +28,8 @@ void main() { // Set value of config variable repoConfig['core.variable'] = 'value'; - print( - '\nNew value for variable "core.variable": ${repoConfig['core.variable']}'); + print('\nNew value for variable ' + '"core.variable": ${repoConfig['core.variable']}'); // Delete variable repoConfig.delete('core.variable'); diff --git a/lib/src/bindings/attr.dart b/lib/src/bindings/attr.dart index 593ac78..250e898 100644 --- a/lib/src/bindings/attr.dart +++ b/lib/src/bindings/attr.dart @@ -5,8 +5,9 @@ import 'libgit2_bindings.dart'; /// Look up the value of one git attribute 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. +/// 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. Object? getAttribute({ required Pointer repoPointer, required int flags, diff --git a/lib/src/bindings/blame.dart b/lib/src/bindings/blame.dart index 1fbbecc..c50b69e 100644 --- a/lib/src/bindings/blame.dart +++ b/lib/src/bindings/blame.dart @@ -79,7 +79,8 @@ Pointer getHunkByIndex({ } } -/// Gets the hunk that relates to the given line number (1-based) in the newest commit. +/// Gets the hunk that relates to the given line number (1-based) in the newest +/// commit. /// /// Throws [RangeError] if [lineNumber] is out of range. Pointer getHunkByLine({ diff --git a/lib/src/bindings/blob.dart b/lib/src/bindings/blob.dart index b0168d3..b4cbd37 100644 --- a/lib/src/bindings/blob.dart +++ b/lib/src/bindings/blob.dart @@ -39,8 +39,8 @@ bool isBinary(Pointer blob) { /// Get a read-only buffer with the raw content of a blob. /// /// A pointer to the raw content of a blob is returned; this pointer is owned -/// internally by the object and shall not be free'd. The pointer may be invalidated -/// at a later time. +/// internally by the object and shall not be free'd. The pointer may be +/// invalidated at a later time. String content(Pointer blob) { return libgit2.git_blob_rawcontent(blob).cast().toDartString(); } @@ -101,7 +101,8 @@ Pointer createFromWorkdir({ } } -/// Read a file from the filesystem and write its content to the Object Database as a loose blob. +/// Read a file from the filesystem and write its content to the Object +/// Database as a loose blob. /// /// Throws a [LibGit2Error] if error occured. Pointer createFromDisk({ diff --git a/lib/src/bindings/branch.dart b/lib/src/bindings/branch.dart index f70cfc8..3cf5a3e 100644 --- a/lib/src/bindings/branch.dart +++ b/lib/src/bindings/branch.dart @@ -48,7 +48,8 @@ List> list({ /// Lookup a branch by its name in a repository. /// -/// The generated reference must be freed by the user. The branch name will be checked for validity. +/// The generated reference must be freed by the user. The branch name will be +/// checked for validity. /// /// Throws a [LibGit2Error] if error occured. Pointer lookup({ @@ -78,7 +79,8 @@ Pointer lookup({ /// Create 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. /// /// The returned reference must be freed by the user. /// @@ -167,8 +169,8 @@ bool isHead(Pointer branch) { /// Determine if 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. +/// 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. /// /// Throws a [LibGit2Error] if error occured. bool isCheckedOut(Pointer branch) { diff --git a/lib/src/bindings/checkout.dart b/lib/src/bindings/checkout.dart index 083a138..e22e87b 100644 --- a/lib/src/bindings/checkout.dart +++ b/lib/src/bindings/checkout.dart @@ -6,13 +6,14 @@ import '../error.dart'; import '../util.dart'; import 'libgit2_bindings.dart'; -/// Updates files in the index and the working tree to match the content of the commit -/// pointed at by HEAD. +/// Updates files in the index and the working tree to match the content of the +/// commit pointed at by HEAD. /// -/// Note that this is not the correct mechanism used to switch branches; do not change -/// your HEAD and then call this method, that would leave you with checkout conflicts -/// since your working directory would then appear to be dirty. Instead, checkout the -/// target of the branch and then update HEAD using `setHead` to point to the branch you checked out. +/// Note that this is not the correct mechanism used to switch branches; do not +/// change your HEAD and then call this method, that would leave you with +/// checkout conflicts since your working directory would then appear to be +/// dirty. Instead, checkout the target of the branch and then update HEAD +/// using [setHead] to point to the branch you checked out. /// /// Throws a [LibGit2Error] if error occured. void head({ diff --git a/lib/src/bindings/commit.dart b/lib/src/bindings/commit.dart index e7b8db0..7543449 100644 --- a/lib/src/bindings/commit.dart +++ b/lib/src/bindings/commit.dart @@ -26,14 +26,15 @@ Pointer lookup({ } } -/// Creates an annotated commit from the given commit id. The resulting annotated commit -/// must be freed with [annotatedFree]. +/// Creates an annotated commit from the given commit id. The resulting +/// annotated commit must be freed with [annotatedFree]. /// -/// An annotated commit contains information about how it was looked up, which may be useful -/// for functions like merge or rebase to provide context to the operation. For example, conflict -/// files will include the name of the source or target branches being merged. It is therefore -/// preferable to use the most specific function (eg git_annotated_commit_from_ref) instead of -/// this one when that data is known. +/// An annotated commit contains information about how it was looked up, which +/// may be useful for functions like merge or rebase to provide context to the +/// operation. For example, conflict files will include the name of the source +/// or target branches being merged. It is therefore preferable to use the most +/// specific function (eg git_annotated_commit_from_ref) instead of this one +/// when that data is known. /// /// Throws a [LibGit2Error] if error occured. Pointer> annotatedLookup({ @@ -117,13 +118,15 @@ Pointer create({ /// Amend an existing commit by replacing only non-null values. /// -/// This creates a new commit that is exactly the same as the old commit, except that -/// any non-null values will be updated. The new commit has the same parents as the old commit. +/// This creates a new commit that is exactly the same as the old commit, +/// except that any non-null values will be updated. The new commit has the +/// same parents as the old commit. /// -/// The [updateRef] value works as in the regular [create], updating the ref to point to -/// the newly rewritten commit. If you want to amend a commit that is not currently -/// 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. +/// The [updateRef] value works as in the regular [create], updating the ref to +/// point to the newly rewritten commit. If you want to amend a commit that is +/// not currently 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. /// /// Throws a [LibGit2Error] if error occured. Pointer amend({ @@ -165,7 +168,8 @@ Pointer amend({ } } -/// Get the encoding for the message of a commit, as a string representing a standard encoding name. +/// Get the encoding for the message of a commit, as a string representing a +/// standard encoding name. /// /// The encoding may be NULL if the encoding header in the commit is missing; /// in that case UTF-8 is assumed. @@ -176,7 +180,8 @@ String messageEncoding(Pointer commit) { /// Get the 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 message(Pointer commit) { return libgit2.git_commit_message(commit).cast().toDartString(); } @@ -217,10 +222,10 @@ Pointer tree(Pointer commit) { return libgit2.git_commit_tree_id(commit); } -/// Reverts the given commit against the given "our" commit, producing an index that -/// reflects the result of the revert. +/// Reverts the given commit against the given "our" commit, producing an index +/// that reflects the result of the revert. /// -/// The returned index must be freed explicitly with `free()`. +/// The returned index must be freed explicitly with [free]. /// /// Throws a [LibGit2Error] if error occured. Pointer revertCommit({ diff --git a/lib/src/bindings/config.dart b/lib/src/bindings/config.dart index 755f527..3bb6be8 100644 --- a/lib/src/bindings/config.dart +++ b/lib/src/bindings/config.dart @@ -106,9 +106,9 @@ String findXdg() { /// Create a snapshot of the configuration. /// -/// Create a snapshot of the current state of a configuration, which allows you to look -/// into a consistent view of the configuration for looking up complex values -/// (e.g. a remote, submodule). +/// Create a snapshot of the current state of a configuration, which allows you +/// to look into a consistent view of the configuration for looking up complex +/// values (e.g. a remote, submodule). Pointer snapshot(Pointer config) { final out = calloc>(); libgit2.git_config_snapshot(out, config); diff --git a/lib/src/bindings/describe.dart b/lib/src/bindings/describe.dart index 0dd7977..c9c1257 100644 --- a/lib/src/bindings/describe.dart +++ b/lib/src/bindings/describe.dart @@ -10,7 +10,8 @@ import 'libgit2_bindings.dart'; /// /// Perform the describe operation on the given committish object. /// -/// Returned object should be freed with `describeResultFree()` once no longer needed. +/// Returned object should be freed with `describeResultFree()` once no longer +/// needed. /// /// Throws a [LibGit2Error] if error occured. Pointer commit({ diff --git a/lib/src/bindings/diff.dart b/lib/src/bindings/diff.dart index fa525e5..373eaf6 100644 --- a/lib/src/bindings/diff.dart +++ b/lib/src/bindings/diff.dart @@ -130,11 +130,12 @@ int length(Pointer diff) => libgit2.git_diff_num_deltas(diff); /// Merge one diff into another. /// -/// This merges items from the "from" list into the "onto" list. The resulting diff -/// will have all items that appear in either list. If an item appears in both lists, -/// then it will be "merged" to appear as if the old version was from the "onto" list -/// and the new version is from the "from" list (with the exception that if the item -/// has a pending DELETE in the middle, then it will show as deleted). +/// This merges items from the "from" list into the "onto" list. The resulting +/// diff will have all items that appear in either list. If an item appears in +/// both lists, then it will be "merged" to appear as if the old version was +/// from the "onto" list and the new version is from the "from" list (with the +/// exception that if the item has a pending DELETE in the middle, then it will +/// show as deleted). void merge({ required Pointer ontoPointer, required Pointer fromPointer, @@ -144,13 +145,15 @@ void merge({ /// Read the contents 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. -/// For example, a patch file likely contains abbreviated object IDs, so the object IDs in a -/// diff delta produced by this function will also be abbreviated. +/// 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. For example, a patch file likely contains +/// abbreviated object IDs, so the object IDs in a diff delta produced by this +/// function will also be abbreviated. /// -/// This function will only read patch files created by a git implementation, it will not -/// read unified diffs produced by the `diff` program, nor any other types of patch files. +/// This function will only read patch files created by a git implementation, +/// it will not read unified diffs produced by the `diff` program, nor any +/// other types of patch files. Pointer parse(String content) { final out = calloc>(); final contentC = content.toNativeUtf8().cast(); @@ -163,9 +166,10 @@ Pointer parse(String content) { /// Transform a diff marking file renames, copies, etc. /// -/// This modifies a diff in place, replacing old entries that look like renames or copies -/// 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. +/// This modifies a diff in place, replacing old entries that look like renames +/// or copies 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. /// /// Throws a [LibGit2Error] if error occured. void findSimilar({ @@ -198,12 +202,13 @@ void findSimilar({ /// Calculate the patch ID for the given patch. /// -/// Calculate a stable patch ID for the given patch by summing the hash of the file diffs, -/// ignoring whitespace and line numbers. This can be used to derive whether two diffs are -/// the same with a high probability. +/// Calculate a stable patch ID for the given patch by summing the hash of the +/// file diffs, ignoring whitespace and line numbers. This can be used to +/// derive whether two diffs are the same with a high probability. /// -/// Currently, this function only calculates stable patch IDs, as defined in `git-patch-id(1)`, -/// and should in fact generate the same IDs as the upstream git project does. +/// Currently, this function only calculates stable patch IDs, as defined in +/// `git-patch-id(1)`, and should in fact generate the same IDs as the upstream +/// git project does. /// /// Throws a [LibGit2Error] if error occured. Pointer patchOid(Pointer diff) { @@ -228,10 +233,10 @@ Pointer getDeltaByIndex({ /// Look up the 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] -/// value into these letters for your own purposes. [GitDelta.untracked] will return -/// a space (i.e. ' '). +/// 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] value into these letters for your own +/// purposes. [GitDelta.untracked] will return a space (i.e. ' '). String statusChar(int status) { return String.fromCharCode(libgit2.git_diff_status_char(status)); } @@ -294,8 +299,8 @@ Pointer addToBuf({ return bufferPointer; } -/// Apply a diff to the given repository, making changes directly in the working directory, -/// the index, or both. +/// Apply a diff to the given repository, making changes directly in the +/// working directory, the index, or both. /// /// Throws a [LibGit2Error] if error occured. bool apply({ diff --git a/lib/src/bindings/graph.dart b/lib/src/bindings/graph.dart index f18c32b..b47b530 100644 --- a/lib/src/bindings/graph.dart +++ b/lib/src/bindings/graph.dart @@ -32,9 +32,10 @@ bool descendantOf({ /// Count the number of unique commits between two commit objects. /// -/// 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. +/// 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. List aheadBehind({ required Pointer repoPointer, required Pointer localPointer, diff --git a/lib/src/bindings/index.dart b/lib/src/bindings/index.dart index 6585bfc..45c7f5b 100644 --- a/lib/src/bindings/index.dart +++ b/lib/src/bindings/index.dart @@ -6,16 +6,17 @@ import '../error.dart'; import '../util.dart'; import 'libgit2_bindings.dart'; -/// Update the contents of an existing index object in memory by reading from the hard disk. +/// Update the contents of an existing index object in memory by reading from +/// the hard disk. /// -/// If force is true, this performs a "hard" read that discards in-memory changes and -/// always reloads the on-disk index data. If there is no on-disk version, -/// the index will be cleared. +/// If force is true, this performs a "hard" read that discards in-memory +/// changes and always reloads the on-disk index data. If there is no on-disk +/// version, the index will be cleared. /// -/// If force is false, this does a "soft" read that reloads the index data from disk only -/// if it has changed since the last time it was loaded. Purely in-memory index data -/// will be untouched. Be aware: if there are changes on disk, unwritten in-memory changes -/// are discarded. +/// If force is false, this does a "soft" read that reloads the index data from +/// disk only if it has changed since the last time it was loaded. Purely +/// in-memory index data will be untouched. Be aware: if there are changes on +/// disk, unwritten in-memory changes are discarded. void read({required Pointer indexPointer, required bool force}) { final forceC = force == true ? 1 : 0; libgit2.git_index_read(indexPointer, forceC); @@ -33,11 +34,13 @@ void readTree({ /// Write the index as a tree. /// -/// 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. +/// 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. /// -/// The index instance cannot be bare, and needs to be associated to an existing repository. +/// The index instance cannot be bare, and needs to be associated to an +/// existing repository. /// /// The index must not contain any file in conflict. /// @@ -56,8 +59,8 @@ Pointer writeTree(Pointer index) { /// Write the index as a tree to the given repository. /// -/// This method will do the same as [writeTree], but letting the user choose the repository -/// where the tree will be written. +/// This method will do the same as [writeTree], but letting the user choose +/// the repository where the tree will be written. /// /// The index must not contain any file in conflict. /// @@ -77,7 +80,8 @@ Pointer writeTreeTo({ } } -/// Find the first position of any entries which point to given path in the Git index. +/// Find the first position of any entries which point to given path in the Git +/// index. bool find({required Pointer indexPointer, required String path}) { final pathC = path.toNativeUtf8().cast(); final result = libgit2.git_index_find(nullptr, indexPointer, pathC); @@ -132,8 +136,8 @@ Pointer getByPath({ /// Clear the contents (all the entries) of an index object. /// -/// This clears the index object in memory; changes must be explicitly written to -/// disk for them to take effect persistently. +/// This clears the index object in memory; changes must be explicitly written +/// to disk for them to take effect persistently. /// /// Throws a [LibGit2Error] if error occured. void clear(Pointer index) { @@ -146,8 +150,9 @@ void clear(Pointer index) { /// Add or update an index entry from an in-memory struct. /// -/// If a previous index entry exists that has the same path and stage as the given `sourceEntry`, -/// it will be replaced. Otherwise, the `sourceEntry` will be added. +/// If a previous index entry exists that has the same path and stage as the +/// given `sourceEntry`, it will be replaced. Otherwise, the `sourceEntry` will +/// be added. /// /// Throws a [LibGit2Error] if error occured. void add({ @@ -163,15 +168,17 @@ void add({ /// Add or update an index entry from a file on disk. /// -/// The file path must be relative to the repository's working folder and must be readable. +/// The file path must be relative to the repository's working folder and must +/// be readable. /// /// This method will fail in bare index instances. /// -/// This forces the file to be added to the index, not looking at gitignore rules. +/// This forces the file to be added to the index, not looking at gitignore +/// rules. /// -/// If this file currently is the result of a merge conflict, this file will no longer be -/// marked as conflicting. The data about the conflict will be moved to the "resolve undo" -/// (REUC) section. +/// If this file currently is the result of a merge conflict, this file will no +/// longer be marked as conflicting. The data about the conflict will be moved +/// to the "resolve undo" (REUC) section. /// /// Throws a [LibGit2Error] if error occured. void addByPath({ @@ -192,9 +199,10 @@ void addByPath({ /// /// This method will fail in bare index instances. /// -/// 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). +/// 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). /// /// Throws a [LibGit2Error] if error occured. void addAll({ @@ -232,7 +240,8 @@ void addAll({ } } -/// Write an existing index object from memory back to disk using an atomic file lock. +/// Write an existing index object from memory back to disk using an atomic +/// file lock. void write(Pointer index) => libgit2.git_index_write(index); /// Remove an entry from the index. diff --git a/lib/src/bindings/merge.dart b/lib/src/bindings/merge.dart index c51689e..34a9dbb 100644 --- a/lib/src/bindings/merge.dart +++ b/lib/src/bindings/merge.dart @@ -25,8 +25,8 @@ Pointer mergeBase({ } } -/// Analyzes the given branch(es) and determines the opportunities for merging them -/// into a reference. +/// Analyzes the given branch(es) and determines the opportunities for merging +/// them into a reference. List analysis({ required Pointer repoPointer, required Pointer ourRefPointer, @@ -52,10 +52,10 @@ List analysis({ return result; } -/// Merges the given commit(s) into HEAD, writing the results into the working directory. -/// Any changes are staged for commit and any conflicts are written to the index. Callers -/// should inspect the repository's index after this completes, resolve any conflicts and -/// prepare a commit. +/// Merges the given commit(s) into HEAD, writing the results into the working +/// directory. Any changes are staged for commit and any conflicts are written +/// to the index. Callers should inspect the repository's index after this +/// completes, resolve any conflicts and prepare a commit. void merge({ required Pointer repoPointer, required Pointer> theirHeadsPointer, @@ -84,8 +84,8 @@ void merge({ } /// Merge 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. +/// as the baseline, producing a string that reflects the merge result +/// containing possible conflicts. /// /// Throws a [LibGit2Error] if error occured. String mergeFileFromIndex({ @@ -114,10 +114,10 @@ String mergeFileFromIndex({ } } -/// Merge two commits, producing a git_index that reflects the result of the merge. -/// The index may be written as-is to the working directory or checked out. If the index -/// is to be converted to a tree, the caller should resolve any conflicts that arose as -/// part of the merge. +/// Merge two commits, producing a git_index that reflects the result of the +/// merge. The index may be written as-is to the working directory or checked +/// out. If the index is to be converted to a tree, the caller should resolve +/// any conflicts that arose as part of the merge. /// /// The returned index must be freed explicitly. /// @@ -155,10 +155,10 @@ Pointer mergeCommits({ } } -/// Merge two trees, producing a git_index that reflects the result of the merge. -/// The index may be written as-is to the working directory or checked out. If the index -/// is to be converted to a tree, the caller should resolve any conflicts that arose as part -/// of the merge. +/// Merge two trees, producing a git_index that reflects the result of the +/// merge. The index may be written as-is to the working directory or checked +/// out. If the index is to be converted to a tree, the caller should resolve +/// any conflicts that arose as part of the merge. /// /// The returned index must be freed explicitly. /// @@ -198,7 +198,8 @@ Pointer mergeTrees({ } } -/// Cherry-pick the given commit, producing changes in the index and working directory. +/// Cherry-pick the given commit, producing changes in the index and working +/// directory. /// /// Throws a [LibGit2Error] if error occured. void cherryPick({ diff --git a/lib/src/bindings/object.dart b/lib/src/bindings/object.dart index f48ffb6..fa944eb 100644 --- a/lib/src/bindings/object.dart +++ b/lib/src/bindings/object.dart @@ -14,9 +14,9 @@ int type(Pointer obj) => libgit2.git_object_type(obj); /// The generated reference is owned by the repository and should be closed with /// the `free()` method instead of free'd manually. /// -/// The 'type' parameter must match the type of the object in the odb; the method will -/// fail otherwise. The special value 'GIT_OBJECT_ANY' may be passed to let the method -/// guess the object's type. +/// The 'type' parameter must match the type of the object in the odb; the +/// method will fail otherwise. The special value 'GIT_OBJECT_ANY' may be +/// passed to let the method guess the object's type. /// /// Throws a [LibGit2Error] if error occured. Pointer lookup({ @@ -37,8 +37,8 @@ Pointer lookup({ /// Close an open object to release memory. /// -/// This method instructs the library to close an existing object; note that git_objects -/// are owned and cached by the repository so the object may or may not be freed after -/// this library call, depending on how aggressive is the caching mechanism used by -/// the repository. +/// This method instructs the library to close an existing object; note that +/// git_objects are owned and cached by the repository so the object may or may +/// not be freed after this library call, depending on how aggressive is the +/// caching mechanism used by the repository. void free(Pointer object) => libgit2.git_object_free(object); diff --git a/lib/src/bindings/odb.dart b/lib/src/bindings/odb.dart index aced45b..19678bf 100644 --- a/lib/src/bindings/odb.dart +++ b/lib/src/bindings/odb.dart @@ -20,11 +20,11 @@ Pointer create() { /// Add an on-disk alternate to an existing Object DB. /// -/// Note that the added path must point to an `objects`, not to a full repository, -/// to use it as an alternate store. +/// Note that the added path must point to an `objects`, not to a full +/// repository, to use it as an alternate store. /// -/// Alternate backends are always checked for objects after all the main backends -/// have been exhausted. +/// Alternate backends are always checked for objects after all the main +/// backends have been exhausted. /// /// Writing is disabled on alternate backends. void addDiskAlternate({ @@ -36,7 +36,8 @@ void addDiskAlternate({ calloc.free(pathC); } -/// Determine if an object can be found in the object database by an abbreviated object ID. +/// Determine if an object can be found in the object database by an +/// abbreviated object ID. /// /// Throws a [LibGit2Error] if error occured. Pointer existsPrefix({ @@ -108,8 +109,8 @@ List objects(Pointer odb) { /// /// This method queries all available ODB backends trying to read the given OID. /// -/// The returned object is reference counted and internally cached, so it should be -/// closed by the user once it's no longer in use. +/// The returned object is reference counted and internally cached, so it +/// should be closed by the user once it's no longer in use. /// /// Throws a [LibGit2Error] if error occured. Pointer read({ @@ -141,14 +142,16 @@ int objectType(Pointer object) { /// Return the data of an ODB object. /// -/// This is the uncompressed, raw data as read from the ODB, without the leading header. +/// This is the uncompressed, raw data as read from the ODB, without the +/// leading header. String objectData(Pointer object) { return libgit2.git_odb_object_data(object).cast().toDartString(); } /// Return the size of an ODB object. /// -/// This is the real size of the `data` buffer, not the actual size of the object. +/// This is the real size of the `data` buffer, not the actual size of the +/// object. int objectSize(Pointer object) { return libgit2.git_odb_object_size(object); } diff --git a/lib/src/bindings/patch.dart b/lib/src/bindings/patch.dart index b9601cf..2c63bb8 100644 --- a/lib/src/bindings/patch.dart +++ b/lib/src/bindings/patch.dart @@ -8,8 +8,8 @@ import 'libgit2_bindings.dart'; /// Directly generate a patch from the difference between two buffers. /// -/// You can use the standard patch accessor functions to read the patch data, and -/// you must free the patch when done. +/// You can use the standard patch accessor functions to read the patch data, +/// and you must free the patch when done. Map fromBuffers({ String? oldBuffer, String? oldAsPath, @@ -47,16 +47,16 @@ Map fromBuffers({ calloc.free(newAsPathC); calloc.free(opts); - // Returning map with pointers to patch and buffers because patch object does not - // have refenrece to underlying buffers or blobs. So if the buffer or blob is freed/removed + // Returning map with pointers to patch and buffers because patch object does + // not have refenrece to underlying buffers or blobs. So if the buffer or blob is freed/removed // the patch text becomes corrupted. return {'patch': out.value, 'a': oldBufferC, 'b': newBufferC}; } /// Directly generate a patch from the difference between two blobs. /// -/// You can use the standard patch accessor functions to read the patch data, and you -/// must free the patch when done. +/// You can use the standard patch accessor functions to read the patch data, +/// and you must free the patch when done. Map fromBlobs({ required Pointer oldBlobPointer, String? oldAsPath, @@ -88,16 +88,16 @@ Map fromBlobs({ calloc.free(newAsPathC); calloc.free(opts); - // Returning map with pointers to patch and blobs because patch object does not - // have reference to underlying blobs. So if the blob is freed/removed the patch - // text becomes corrupted. + // Returning map with pointers to patch and blobs because patch object does + // not have reference to underlying blobs. So if the blob is freed/removed the + // patch text becomes corrupted. return {'patch': out.value, 'a': oldBlobPointer, 'b': newBlobPointer}; } /// Directly generate a patch from the difference between a blob and a buffer. /// -/// You can use the standard patch accessor functions to read the patch data, and you must -/// free the patch when done. +/// You can use the standard patch accessor functions to read the patch data, +/// and you must free the patch when done. Map fromBlobAndBuffer({ Pointer? oldBlobPointer, String? oldAsPath, @@ -132,17 +132,17 @@ Map fromBlobAndBuffer({ calloc.free(bufferAsPathC); calloc.free(opts); - // Returning map with pointers to patch and buffers because patch object does not - // have reference to underlying buffers or blobs. So if the buffer or blob is freed/removed - // the patch text becomes corrupted. + // Returning map with pointers to patch and buffers because patch object does + // not have reference to underlying buffers or blobs. So if the buffer or + // blob is freed/removed the patch text becomes corrupted. return {'patch': out.value, 'a': oldBlobPointer, 'b': bufferC}; } /// Return a patch for an entry in the diff list. /// -/// The newly created patch object contains the text diffs for the delta. You have to call -/// `free()` when you are done with it. You can use the patch object to loop over all the -/// hunks and lines in the diff of the one delta. +/// The newly created patch object contains the text diffs for the delta. You +/// have to call [free] when you are done with it. You can use the patch object +/// to loop over all the hunks and lines in the diff of the one delta. /// /// Throws a [LibGit2Error] if error occured. Pointer fromDiff({ @@ -169,8 +169,8 @@ int numHunks(Pointer patch) => libgit2.git_patch_num_hunks(patch); /// Get the information about a hunk in a patch. /// -/// Given a patch and a hunk index into the patch, this returns detailed information -/// about that hunk. +/// Given a patch and a hunk index into the patch, this returns detailed +/// information about that hunk. Map hunk({ required Pointer patchPointer, required int hunkIndex, @@ -215,12 +215,12 @@ String text(Pointer patch) { /// Look up 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. +/// 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. /// -/// 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 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). int size({ required Pointer patchPointer, required bool includeContext, diff --git a/lib/src/bindings/rebase.dart b/lib/src/bindings/rebase.dart index 3c0dbf3..379a7b9 100644 --- a/lib/src/bindings/rebase.dart +++ b/lib/src/bindings/rebase.dart @@ -6,16 +6,19 @@ import '../error.dart'; import '../util.dart'; import 'libgit2_bindings.dart'; -/// Initializes a rebase operation to rebase the changes in [branchPointer] relative -/// to [upstreamPointer] onto [ontoPointer] another branch. To begin the rebase process, call -/// `next()`. When you have finished with this object, call `free()`. +/// Initializes a rebase operation to rebase the changes in [branchPointer] +/// relative to [upstreamPointer] onto [ontoPointer] another branch. To begin +/// the rebase process, call [next]. When you have finished with this object, +/// call [free]. /// -/// [branchPointer] is the terminal commit to rebase, or null to rebase the current branch. +/// [branchPointer] is the terminal commit to rebase, or null to rebase the +/// current branch. /// -/// [upstreamPointer] is the commit to begin rebasing from, or null to rebase all -/// reachable commits. +/// [upstreamPointer] is the commit to begin rebasing from, or null to rebase +/// all reachable commits. /// -/// [ontoPointer] is the branch to rebase onto, or null to rebase onto the given upstream. +/// [ontoPointer] is the branch to rebase onto, or null to rebase onto the +/// given upstream. /// /// Throws a [LibGit2Error] if error occured. Pointer init({ @@ -102,12 +105,13 @@ void commit({ } } -/// Finishes a rebase that is currently in progress once all patches have been applied. +/// Finishes a rebase that is currently in progress once all patches have been +/// applied. void finish(Pointer rebase) => libgit2.git_rebase_finish(rebase, nullptr); -/// Aborts a rebase that is currently in progress, resetting the repository and working -/// directory to their state before rebase began. +/// Aborts a rebase that is currently in progress, resetting the repository and +/// working directory to their state before rebase began. void abort(Pointer rebase) => libgit2.git_rebase_abort(rebase); /// Free memory allocated for rebase object. diff --git a/lib/src/bindings/reference.dart b/lib/src/bindings/reference.dart index ffde7ba..18bb2db 100644 --- a/lib/src/bindings/reference.dart +++ b/lib/src/bindings/reference.dart @@ -14,7 +14,8 @@ int referenceType(Pointer ref) => /// Get the OID pointed to by a direct reference. /// -/// Only available if the reference is direct (i.e. an object id reference, not a symbolic one). +/// Only available if the reference is direct (i.e. an object id reference, not +/// a symbolic one). Pointer target(Pointer ref) => libgit2.git_reference_target(ref); @@ -25,8 +26,8 @@ Pointer target(Pointer ref) => /// /// The peeled reference must be freed manually once it's no longer needed. /// -/// If a direct reference is passed as an argument, a copy of that reference is returned. -/// This copy must be manually freed too. +/// If a direct reference is passed as an argument, a copy of that reference is +/// returned. This copy must be manually freed too. /// /// Throws a [LibGit2Error] if error occured. Pointer resolve(Pointer ref) { @@ -85,11 +86,11 @@ String shorthand(Pointer ref) { /// /// The new name will be checked for validity. /// -/// If the force flag is not enabled, and there's already a reference with the given name, -/// the renaming will fail. +/// If the force flag is not enabled, and there's already a reference with the +/// given name, the renaming will fail. /// -/// IMPORTANT: The user needs to write a proper reflog entry if the reflog is enabled for -/// the repository. We only rename the reflog if it exists. +/// IMPORTANT: The user needs to write a proper reflog entry if the reflog is +/// enabled for the repository. We only rename the reflog if it exists. /// /// Throws a [LibGit2Error] if error occured. Pointer rename({ @@ -179,25 +180,29 @@ bool isTag(Pointer ref) { /// Create a new direct reference. /// /// A direct reference (also called an object id reference) refers directly to a -/// specific object id (a.k.a. OID or SHA) in the repository. The id permanently refers to -/// the object (although the reference itself can be moved). For example, in libgit2 -/// the direct ref "refs/tags/v0.17.0" refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. +/// specific object id (a.k.a. OID or SHA) in the repository. The id +/// permanently refers to the object (although the reference itself can be +/// moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" refers +/// to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. /// -/// The direct reference will be created in the repository and written to the disk. -/// The generated reference object must be freed by the user. +/// The direct reference will be created in the repository and written to the +/// disk. The generated reference object must be freed by the user. /// /// Valid reference names must follow one of two patterns: /// -/// Top-level names must contain only capital letters and underscores, and 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 -/// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have -/// special meaning to revparse. -/// This function will throw a [LibGit2Error] if a reference already exists with the given name -/// unless force is true, in which case it will be overwritten. +/// 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 '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." +/// and "@{" which have special meaning to revparse. /// -/// The message for the reflog will be ignored if the reference does not belong in the -/// standard set (HEAD, branches and remote-tracking branches) and it does not have a reflog. +/// This function will throw a [LibGit2Error] if a reference already exists +/// with the given name unless force is true, in which case it will be +/// overwritten. +/// +/// The message for the reflog will be ignored if the reference does not belong +/// in the standard set (HEAD, branches and remote-tracking branches) and it +/// does not have a reflog. /// /// Throws a [LibGit2Error] if error occured. Pointer createDirect({ @@ -233,26 +238,29 @@ Pointer createDirect({ /// Create a new symbolic reference. /// -/// A symbolic reference is a reference name that refers to another reference name. -/// If the other name moves, the symbolic name will move, too. As a simple example, -/// the "HEAD" reference might refer to "refs/heads/master" while on the "master" branch -/// of a repository. +/// A symbolic reference is a reference name that refers to another reference +/// name. If the other name moves, the symbolic name will move, too. As a +/// simple example, the "HEAD" reference might refer to "refs/heads/master" +/// while on the "master" branch of a repository. /// -/// The symbolic reference will be created in the repository and written to the disk. -/// The generated reference object must be freed by the user. +/// The symbolic reference will be created in the repository and written to the +/// disk. The generated reference object must be freed by the user. /// /// Valid reference names must follow one of two patterns: /// -/// Top-level names must contain only capital letters and underscores, and must begin and end -/// with a letter. (e.g. "HEAD", "ORIG_HEAD"). -/// Names prefixed with "refs/" can be almost anything. You must avoid the characters -/// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have special -/// meaning to revparse. -/// This function will throw an [LibGit2Error] if a reference already exists with the given -/// name unless force is true, in which case it will be overwritten. +/// 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 '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and +/// "@{" which have special meaning to revparse. /// -/// The message for the reflog will be ignored if the reference does not belong in the standard -/// set (HEAD, branches and remote-tracking branches) and it does not have a reflog. +/// This function will throw an [LibGit2Error] if a reference already exists +/// with the given name unless force is true, in which case it will be +/// overwritten. +/// +/// The message for the reflog will be ignored if the reference does not belong +/// in the standard set (HEAD, branches and remote-tracking branches) and it +/// does not have a reflog. /// /// Throws a [LibGit2Error] if error occured. Pointer createSymbolic({ @@ -291,7 +299,8 @@ Pointer createSymbolic({ /// Delete an existing reference. /// /// This method works for both direct and symbolic references. -/// The reference will be immediately removed on disk but the memory will not be freed. +/// The reference will be immediately removed on disk but the memory will not +/// be freed. void delete(Pointer ref) => libgit2.git_reference_delete(ref); /// Get the repository where a reference resides. @@ -299,8 +308,9 @@ Pointer owner(Pointer ref) { return libgit2.git_reference_owner(ref); } -/// Conditionally create a new reference with the same name as the given reference -/// but a different OID target. The reference must be a direct reference, otherwise this will fail. +/// Conditionally create a new reference with the same name as the given +/// reference but a different OID target. The reference must be a direct +/// reference, otherwise this will fail. /// /// The new reference will be written to disk, overwriting the given reference. /// @@ -329,15 +339,17 @@ Pointer setTarget({ } } -/// Create a new reference with the same name as the given reference but a different -/// symbolic target. The reference must be a symbolic reference, otherwise this will fail. +/// Create a new reference with the same name as the given reference but a +/// different symbolic target. The reference must be a symbolic reference, +/// otherwise this will fail. /// /// The new reference will be written to disk, overwriting the given reference. /// /// The target name will be checked for validity. /// -/// The message for the reflog will be ignored if the reference does not belong in the -/// standard set (HEAD, branches and remote-tracking branches) and and it does not have a reflog. +/// The message for the reflog will be ignored if the reference does not belong +/// in the standard set (HEAD, branches and remote-tracking branches) and and +/// it does not have a reflog. /// /// Throws a [LibGit2Error] if error occured. Pointer setTargetSymbolic({ @@ -378,10 +390,11 @@ bool compare({ /// Recursively peel reference until object of the specified type is found. /// -/// The retrieved peeled object is owned by the repository and should be closed to release memory. +/// The retrieved peeled object is owned by the repository and should be closed +/// to release memory. /// -/// If you pass GIT_OBJECT_ANY as the target type, then the object will be peeled until a -/// non-tag object is met. +/// If you pass GIT_OBJECT_ANY as the target type, then the object will be +/// peeled until a non-tag object is met. /// /// Throws a [LibGit2Error] if error occured. Pointer peel({ diff --git a/lib/src/bindings/refspec.dart b/lib/src/bindings/refspec.dart index 20f4228..6f746f0 100644 --- a/lib/src/bindings/refspec.dart +++ b/lib/src/bindings/refspec.dart @@ -79,7 +79,8 @@ String transform({ } } -/// Transform a target reference to its source reference following the refspec's rules. +/// Transform a target reference to its source reference following the +/// refspec's rules. /// /// Throws a [LibGit2Error] if error occured. String rTransform({ diff --git a/lib/src/bindings/remote.dart b/lib/src/bindings/remote.dart index 069eecf..8e7b60e 100644 --- a/lib/src/bindings/remote.dart +++ b/lib/src/bindings/remote.dart @@ -47,7 +47,8 @@ Pointer lookup({ } } -/// Add a remote with the default fetch refspec to the repository's configuration. +/// Add a remote with the default fetch refspec to the repository's +/// configuration. /// /// Throws a [LibGit2Error] if error occured. Pointer create({ @@ -71,7 +72,8 @@ Pointer create({ } } -/// Add a remote with the provided fetch refspec to the repository's configuration. +/// Add a remote with the provided fetch refspec to the repository's +/// configuration. /// /// Throws a [LibGit2Error] if error occured. Pointer createWithFetchSpec({ @@ -106,7 +108,8 @@ Pointer createWithFetchSpec({ /// Delete an existing persisted remote. /// -/// All remote-tracking branches and configuration settings for the remote will be removed. +/// All remote-tracking branches and configuration settings for the remote will +/// be removed. /// /// Throws a [LibGit2Error] if error occured. void delete({ @@ -127,12 +130,13 @@ void delete({ /// /// Returns list of non-default refspecs that cannot be renamed. /// -/// All remote-tracking branches and configuration settings for the remote are updated. +/// All remote-tracking branches and configuration settings for the remote are +/// updated. /// /// The new name 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. +/// No loaded instances of a the remote with the old name will change their +/// name or their list of refspecs. /// /// Throws a [LibGit2Error] if error occured. List rename({ @@ -163,8 +167,8 @@ List rename({ /// Set 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. +/// 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. /// /// Throws a [LibGit2Error] if error occured. void setUrl({ @@ -186,8 +190,8 @@ void setUrl({ /// Set 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. +/// 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. /// /// Throws a [LibGit2Error] if error occured. void setPushUrl({ @@ -266,8 +270,8 @@ List pushRefspecs(Pointer remote) { /// Add a fetch refspec to the remote's configuration. /// -/// Add the given refspec to the fetch list in the configuration. No loaded remote -/// instances will be affected. +/// Add the given refspec to the fetch list in the configuration. No loaded +/// remote instances will be affected. /// /// Throws a [LibGit2Error] if error occured. void addFetch({ @@ -289,8 +293,8 @@ void addFetch({ /// Add a push refspec to the remote's configuration. /// -/// Add the given refspec to the push list in the configuration. No loaded remote -/// instances will be affected. +/// Add the given refspec to the push list in the configuration. No loaded +/// remote instances will be affected. /// /// Throws a [LibGit2Error] if error occured. void addPush({ @@ -312,9 +316,9 @@ void addPush({ /// Open a connection to a remote. /// -/// The transport is selected based on the URL. The direction argument is due to a -/// limitation of the git protocol (over TCP or SSH) which starts up a specific binary -/// which can only do the one or the other. +/// The transport is selected based on the URL. The direction argument is due +/// to a limitation of the git protocol (over TCP or SSH) which starts up a +/// specific binary which can only do the one or the other. /// /// Throws a [LibGit2Error] if error occured. void connect({ @@ -355,11 +359,12 @@ void connect({ /// Get the remote repository's reference advertisement list. /// -/// Get the list of references with which the server responds to a new connection. +/// Get the list of references with which the server responds to a new +/// connection. /// -/// The remote (or more exactly its transport) must have connected to the remote repository. -/// This list is available as soon as the connection to the remote is initiated and it -/// remains available after disconnecting. +/// The remote (or more exactly its transport) must have connected to the +/// remote repository. This list is available as soon as the connection to the +/// remote is initiated and it remains available after disconnecting. /// /// Throws a [LibGit2Error] if error occured. List> lsRemotes(Pointer remote) { @@ -395,8 +400,8 @@ List> lsRemotes(Pointer remote) { /// Download new data and update tips. /// -/// Convenience function to connect to a remote, download the data, disconnect and -/// update the remote-tracking branches. +/// Convenience function to connect to a remote, download the data, disconnect +/// and update the remote-tracking branches. /// /// Throws a [LibGit2Error] if error occured. void fetch({ diff --git a/lib/src/bindings/remote_callbacks.dart b/lib/src/bindings/remote_callbacks.dart index d508808..c66bba0 100644 --- a/lib/src/bindings/remote_callbacks.dart +++ b/lib/src/bindings/remote_callbacks.dart @@ -16,8 +16,8 @@ class RemoteCallbacks { /// Callback function that reports transfer progress. static void Function(TransferProgress)? transferProgress; - /// A callback that will be regularly called with the current count of progress - /// done by the indexer during the download of new data. + /// A callback that will be regularly called with the current count of + /// progress done by the indexer during the download of new data. static int transferProgressCb( Pointer stats, Pointer payload, @@ -70,12 +70,14 @@ class RemoteCallbacks { return 0; } - /// A function matching the `Remote Function(Repository repo, String name, String url)` signature - /// to override the remote creation and customization process during a clone operation. + /// A function matching the + /// `Remote Function(Repository repo, String name, String url)` signature to + /// override the remote creation and customization process during a clone + /// operation. static Remote Function(Repository, String, String)? remoteFunction; - /// A callback used to create the git remote, prior to its being used to perform - /// the clone operation. + /// A callback used to create the git remote, prior to its being used to + /// perform the clone operation. static int remoteCb( Pointer> remote, Pointer repo, @@ -92,8 +94,9 @@ class RemoteCallbacks { return 0; } - /// A function matching the `Repository Function(String path, bool bare)` signature to override - /// the repository creation and customization process during a clone operation. + /// A function matching the `Repository Function(String path, bool bare)` + /// signature to override the repository creation and customization process + /// during a clone operation. static Repository Function(String, bool)? repositoryFunction; /// A callback used to create the new repository into which to clone. @@ -111,11 +114,12 @@ class RemoteCallbacks { return 0; } - /// [Credentials] object used for authentication in order to connect to remote. + /// [Credentials] object used for authentication in order to connect to + /// remote. static Credentials? credentials; - /// Credential acquisition callback that will be called if the remote host requires - /// authentication in order to connect to it. + /// Credential acquisition callback that will be called if the remote host + /// requires authentication in order to connect to it. static int credentialsCb( Pointer> credPointer, Pointer url, diff --git a/lib/src/bindings/repository.dart b/lib/src/bindings/repository.dart index 4540650..38e5a76 100644 --- a/lib/src/bindings/repository.dart +++ b/lib/src/bindings/repository.dart @@ -30,11 +30,13 @@ Pointer open(String path) { } } -/// Look 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]. +/// Look 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]. /// -/// The method will automatically detect if the repository is bare (if there is a repository). +/// The method will automatically detect if the repository is bare (if there is +/// a repository). String discover({ required String startPath, String? ceilingDirs, @@ -201,10 +203,11 @@ String getNamespace(Pointer repo) { /// Sets the active namespace for this repository. /// -/// This namespace affects all reference operations for the repo. See `man gitnamespaces` +/// 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. +/// The [namespace] should not include the refs folder, e.g. to namespace all +/// references under refs/namespaces/foo/, use foo as the namespace. void setNamespace({ required Pointer repoPointer, String? namespace, @@ -255,7 +258,8 @@ Pointer head(Pointer repo) { /// Check if a repository's HEAD is detached. /// -/// A repository's HEAD is detached when it points directly to a commit instead of a branch. +/// A repository's HEAD is detached when it points directly to a commit instead +/// of a branch. /// /// Throws a [LibGit2Error] if error occured. bool isHeadDetached(Pointer repo) { @@ -270,8 +274,8 @@ bool isHeadDetached(Pointer repo) { /// Check if the 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. +/// 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. /// /// Throws a [LibGit2Error] if error occured. bool isBranchUnborn(Pointer repo) { @@ -287,7 +291,8 @@ bool isBranchUnborn(Pointer repo) { /// Set 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. +/// Pass NULL to unset. When unset, the identity will be taken from the +/// repository's configuration. void setIdentity({ required Pointer repoPointer, String? name, @@ -324,10 +329,12 @@ Map identity(Pointer repo) { /// Get the 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). +/// 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. +/// The configuration file must be freed once it's no longer being used by the +/// user. Pointer config(Pointer repo) { final out = calloc>(); libgit2.git_repository_config(out, repo); @@ -337,9 +344,11 @@ Pointer config(Pointer repo) { /// Get a 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 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. +/// The configuration file must be freed once it's no longer being used by the +/// user. Pointer configSnapshot(Pointer repo) { final out = calloc>(); libgit2.git_repository_config_snapshot(out, repo); @@ -376,7 +385,8 @@ bool isWorktree(Pointer repo) { /// 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. +/// Don't forget to remove the file with [removeMessage] after you create the +/// commit. /// /// Throws a [LibGit2Error] if error occured. String message(Pointer repo) { @@ -443,10 +453,11 @@ Pointer refdb(Pointer repo) { /// /// If the provided reference points to a Tree or a Blob, the HEAD is unaltered. /// -/// If the provided reference points to a branch, the HEAD will point to that branch, -/// staying attached, or become attached if it isn't yet. +/// If the provided reference points to a branch, the HEAD will point to that +/// branch, staying attached, or become attached if it isn't yet. /// -/// If the branch doesn't exist yet, the HEAD will be attached to an unborn branch. +/// If the branch doesn't exist yet, the HEAD will be attached to an unborn +/// branch. /// /// Otherwise, the HEAD will be detached and will directly point to the Commit. /// @@ -467,11 +478,14 @@ void setHead({ /// Make the repository HEAD directly point to the commit. /// -/// If the provided committish cannot be found in the repository, the HEAD is unaltered. +/// If the provided committish cannot be found in the repository, the HEAD is +/// unaltered. /// -/// If the provided commitish cannot be peeled into a commit, the HEAD is unaltered. +/// If the provided commitish cannot be peeled into a commit, the HEAD is +/// unaltered. /// -/// Otherwise, the HEAD will eventually be detached and will directly point to the peeled commit. +/// Otherwise, the HEAD will eventually be detached and will directly point to +/// the peeled commit. /// /// Throws a [LibGit2Error] if error occured. void setHeadDetached({ @@ -493,8 +507,8 @@ void setHeadDetached({ /// The working directory doesn't need to be the same one that contains the /// `.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 +/// 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). /// /// Throws a [LibGit2Error] if error occured. diff --git a/lib/src/bindings/reset.dart b/lib/src/bindings/reset.dart index 194806a..ba1000d 100644 --- a/lib/src/bindings/reset.dart +++ b/lib/src/bindings/reset.dart @@ -3,16 +3,17 @@ import 'dart:ffi'; import '../util.dart'; import 'libgit2_bindings.dart'; -/// Sets the current head to the specified commit oid and optionally resets the index -/// and working tree to match. +/// Sets the current head to the specified commit oid and optionally resets the +/// index and working tree to match. /// /// SOFT reset means the Head will be moved to the commit. /// -/// MIXED reset will trigger a SOFT reset, plus the index will be replaced with the -/// content of the commit tree. +/// MIXED reset will trigger a SOFT reset, plus the index will be replaced with +/// the content of the commit tree. /// -/// HARD reset will trigger a MIXED reset and the working directory will be replaced -/// with the content of the index. (Untracked and ignored files will be left alone, however.) +/// HARD reset will trigger a MIXED reset and the working directory will be +/// replaced with the content of the index. (Untracked and ignored files will +/// be left alone, however.) void reset({ required Pointer repoPointer, required Pointer targetPointer, diff --git a/lib/src/bindings/revparse.dart b/lib/src/bindings/revparse.dart index 1e7a65e..096be07 100644 --- a/lib/src/bindings/revparse.dart +++ b/lib/src/bindings/revparse.dart @@ -62,9 +62,9 @@ Pointer revParseSingle({ /// See `man gitrevisions`, or https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions /// for information on the syntax accepted. /// -/// In some cases (@{<-n>} or @{upstream}), the expression may point to an -/// intermediate reference. When such expressions are being passed in, reference_out will be -/// valued as well. +/// In some cases (@{<-n>} or @{upstream}), the expression may +/// point to an intermediate reference. When such expressions are being passed +/// in, reference_out will be valued as well. /// /// The returned object and reference should be released when no longer needed. /// diff --git a/lib/src/bindings/revwalk.dart b/lib/src/bindings/revwalk.dart index 1f7362b..9b74bbc 100644 --- a/lib/src/bindings/revwalk.dart +++ b/lib/src/bindings/revwalk.dart @@ -12,11 +12,12 @@ import 'libgit2_bindings.dart'; /// This revision walker uses a custom memory pool and an internal commit cache, /// so it is relatively expensive to allocate. /// -/// For maximum performance, this revision walker should be reused for different walks. +/// For maximum performance, this revision walker should be reused for +/// different walks. /// -/// This revision walker is not thread safe: it may only be used to walk a repository -/// on a single thread; however, it is possible to have several revision walkers in several -/// different threads walking the same repository. +/// This revision walker is not thread safe: it may only be used to walk a +/// repository on a single thread; however, it is possible to have several +/// revision walkers in several different threads walking the same repository. /// /// Throws a [LibGit2Error] if error occured. Pointer create(Pointer repo) { @@ -43,10 +44,11 @@ void sorting({ /// Add a new root for the traversal. /// -/// The pushed commit will be marked as one of the roots from which to start the walk. -/// This commit may not be walked if it or a child is hidden. +/// The pushed commit will be marked as one of the roots from which to start +/// the walk. This commit may not be walked if it or a child is hidden. /// -/// At least one commit must be pushed onto the walker before a walk can be started. +/// At least one commit must be pushed onto the walker before a walk can be +/// started. /// /// The given id must belong to a committish on the walked repository. /// @@ -64,12 +66,13 @@ void push({ /// Get the list of commits from the revision walk. /// -/// The initial call to this method is not blocking when iterating through a repo -/// with a time-sorting mode. +/// The initial call to this method is not blocking when iterating through a +/// repo with a time-sorting mode. /// -/// Iterating with Topological or inverted modes makes the initial call blocking to -/// preprocess the commit list, but this block should be mostly unnoticeable on most -/// repositories (topological preprocessing times at 0.3s on the git.git repo). +/// Iterating with Topological or inverted modes makes the initial call +/// blocking to preprocess the commit list, but this block should be mostly +/// unnoticeable on most repositories (topological preprocessing times at 0.3s +/// on the git.git repo). /// /// The revision walker is reset when the walk is over. List> walk({ @@ -101,7 +104,8 @@ List> walk({ /// /// The given id must belong to a committish on the walked repository. /// -/// The resolved commit and all its parents will be hidden from the output on the revision walk. +/// The resolved commit and all its parents will be hidden from the output on +/// the revision walk. /// /// Throws a [LibGit2Error] if error occured. void hide({ @@ -117,8 +121,9 @@ void hide({ /// Reset the revision walker for reuse. /// -/// This will clear all the pushed and hidden commits, and leave the walker in a blank state -/// (just like at creation) ready to receive new commit pushes and start a new walk. +/// This will clear all the pushed and hidden commits, and leave the walker in +/// a blank state (just like at creation) ready to receive new commit pushes +/// and start a new walk. /// /// The revision walk is automatically reset when a walk is over. void reset(Pointer walker) => libgit2.git_revwalk_reset(walker); diff --git a/lib/src/bindings/signature.dart b/lib/src/bindings/signature.dart index 2df6fa9..df3dc24 100644 --- a/lib/src/bindings/signature.dart +++ b/lib/src/bindings/signature.dart @@ -56,8 +56,9 @@ Pointer now({required String name, required String email}) { /// Create 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 -/// current time as the timestamp, and creates a new signature based on that information. +/// 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. Pointer defaultSignature(Pointer repo) { final out = calloc>(); libgit2.git_signature_default(out, repo); diff --git a/lib/src/bindings/stash.dart b/lib/src/bindings/stash.dart index 151aa20..357953d 100644 --- a/lib/src/bindings/stash.dart +++ b/lib/src/bindings/stash.dart @@ -92,7 +92,8 @@ void drop({required Pointer repoPointer, required int index}) { } } -/// Apply a single stashed state from the stash list and remove it from the list if successful. +/// Apply a single stashed state from the stash list and remove it from the +/// list if successful. /// /// Throws a [LibGit2Error] if error occured. void pop({ diff --git a/lib/src/bindings/status.dart b/lib/src/bindings/status.dart index 3728abd..aaed2a9 100644 --- a/lib/src/bindings/status.dart +++ b/lib/src/bindings/status.dart @@ -42,17 +42,20 @@ Pointer getByIndex({ /// Get file status for a single file. /// -/// This tries to get status for the filename that you give. If no files match that name -/// (in either the HEAD, index, or working directory), this returns GIT_ENOTFOUND. +/// This tries to get status for the filename that you give. If no files match +/// that name (in either the HEAD, index, or working directory), this returns +/// GIT_ENOTFOUND. /// -/// If the name matches multiple files (for example, if the path names a directory or if -/// running on a case- insensitive filesystem and yet the HEAD has two entries that both -/// match the path), then this returns GIT_EAMBIGUOUS because it cannot give correct results. +/// If the name matches multiple files (for example, if the path names a +/// directory or if running on a case- insensitive filesystem and yet the HEAD +/// has two entries that both match the path), then this returns GIT_EAMBIGUOUS +/// because it cannot give correct results. /// -/// 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 -/// file status with rename detection, there is no choice but to do a full listNew -/// and scan through looking for the path that you are interested in. +/// 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 file status with rename detection, +/// there is no choice but to do a full listNew and scan through looking for +/// the path that you are interested in. /// /// Throws a [LibGit2Error] if error occured. int file({required Pointer repoPointer, required String path}) { diff --git a/lib/src/bindings/submodule.dart b/lib/src/bindings/submodule.dart index e226dd9..1eed371 100644 --- a/lib/src/bindings/submodule.dart +++ b/lib/src/bindings/submodule.dart @@ -69,8 +69,8 @@ Pointer lookup({ /// Just like `git submodule init`, this copies information about the /// submodule into `.git/config`. /// -/// By default, existing entries will not be overwritten, but setting [overwrite] -/// to true forces them to be updated. +/// By default, existing entries will not be overwritten, but setting +/// [overwrite] to true forces them to be updated. void init({ required Pointer submodulePointer, bool overwrite = false, @@ -80,14 +80,14 @@ void init({ } /// Update a submodule. This will clone a missing submodule and checkout the -/// subrepository to the commit specified in the index of the containing repository. -/// If the submodule repository doesn't contain the target commit (e.g. because -/// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch -/// options supplied in [callbacks]. +/// subrepository to the commit specified in the index of the containing +/// repository. If the submodule repository doesn't contain the target commit +/// (e.g. because fetchRecurseSubmodules isn't set), then the submodule is +/// fetched using the fetch options supplied in [callbacks]. /// -/// If the submodule is not initialized, setting [init] to true will initialize the -/// submodule before updating. Otherwise, this will return an error if attempting -/// to update an uninitialzed repository. +/// If the submodule is not initialized, setting [init] to true will initialize +/// the submodule before updating. Otherwise, this will return an error if +/// attempting to update an uninitialzed repository. /// /// Throws a [LibGit2Error] if error occured. void update({ @@ -119,10 +119,10 @@ void update({ /// Open the repository for a submodule. /// -/// This is a newly opened repository object. The caller is responsible for calling -/// `free()` on it when done. 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. +/// This is a newly opened repository object. The caller is responsible for +/// calling free on it when done. 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. /// /// Throws a [LibGit2Error] if error occured. Pointer open(Pointer submodule) { @@ -139,10 +139,11 @@ Pointer open(Pointer submodule) { /// Set up a new git submodule for checkout. /// -/// This does `git submodule add` up to the fetch and checkout of the submodule contents. -/// It preps a new submodule, creates an entry in `.gitmodules` and creates an empty -/// initialized repository either at the given path in the working directory or in -/// `.git/modules` with a gitlink from the working directory to the new repo. +/// This does `git submodule add` up to the fetch and checkout of the submodule +/// contents. It preps a new submodule, creates an entry in `.gitmodules` and +/// creates an empty initialized repository either at the given path in the +/// working directory or in `.git/modules` with a gitlink from the working +/// directory to the new repo. /// /// Throws a [LibGit2Error] if error occured. Pointer addSetup({ @@ -208,16 +209,16 @@ void clone({ /// /// This should be called on a submodule once you have called add setup and done /// the clone of the submodule. This adds the `.gitmodules` file and the newly -/// cloned submodule to the index to be ready to be committed (but doesn't actually -/// do the commit). +/// cloned submodule to the index to be ready to be committed (but doesn't +/// actually do the commit). void addFinalize(Pointer submodule) { libgit2.git_submodule_add_finalize(submodule); } /// Get the status for a submodule. /// -/// This looks at a submodule and tries to determine the status. How deeply it examines -/// the working directory to do this will depend on the [ignore] value. +/// This looks at a submodule and tries to determine the status. How deeply it +/// examines the working directory to do this will depend on the [ignore] value. int status({ required Pointer repoPointer, required String name, @@ -236,17 +237,17 @@ int status({ /// Copy submodule remote info into submodule repo. /// -/// This copies the information about the submodules URL into the checked out submodule -/// config, acting like `git submodule sync`. This is useful if you have altered the URL -/// for the submodule (or it has been altered by a fetch of upstream changes) and you -/// need to update your local repo. +/// This copies the information about the submodules URL into the checked out +/// submodule config, acting like `git submodule sync`. This is useful if you +/// have altered the URL for the submodule (or it has been altered by a fetch +/// of upstream changes) and you need to update your local repo. void sync(Pointer submodule) => libgit2.git_submodule_sync(submodule); /// Reread submodule info from config, index, and HEAD. /// -/// Call this to reread cached submodule information for this submodule if you have -/// reason to believe that it has changed. +/// Call this to reread cached submodule information for this submodule if you +/// have reason to believe that it has changed. /// /// Set [force] to true to reload even if the data doesn't seem out of date. void reload({ @@ -335,10 +336,10 @@ Pointer? indexId(Pointer submodule) { /// Get the OID for the submodule in the current working directory. /// -/// 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 -/// won't notice that. You should call [status] for a more complete picture about -/// the state of the working directory. +/// 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 won't notice that. You should call [status] for a more complete +/// picture about the state of the working directory. /// /// Returns null if submodule is not checked out. Pointer? workdirId(Pointer submodule) { @@ -388,8 +389,8 @@ void setUpdateRule({ /// /// This returns a pointer to the repository that contains the submodule. /// This is a just a reference to the repository that was passed to the original -/// [lookup] call, so if that repository has been freed, then this may be a dangling -/// reference. +/// [lookup] call, so if that repository has been freed, then this may be a +/// dangling reference. Pointer owner(Pointer submodule) { return libgit2.git_submodule_owner(submodule); } diff --git a/lib/src/bindings/tag.dart b/lib/src/bindings/tag.dart index c9efd83..495daf6 100644 --- a/lib/src/bindings/tag.dart +++ b/lib/src/bindings/tag.dart @@ -47,7 +47,8 @@ Pointer lookup({ /// Get the tagged object of a tag. /// -/// This method performs a repository lookup for the given object and returns it. +/// This method performs a repository lookup for the given object and returns +/// it. /// /// Throws a [LibGit2Error] if error occured. Pointer target(Pointer tag) { @@ -82,8 +83,9 @@ Pointer tagger(Pointer tag) => /// Create a new tag in the repository from an object. /// -/// A new reference will also be created pointing to this tag object. If force is true -/// and a reference already exists with the given name, it'll be replaced. +/// A new reference will also be created pointing to this tag object. If force +/// is true and a reference already exists with the given name, it'll be +/// replaced. /// /// The message will not be cleaned up. /// diff --git a/lib/src/bindings/tree.dart b/lib/src/bindings/tree.dart index 488d430..6d339dc 100644 --- a/lib/src/bindings/tree.dart +++ b/lib/src/bindings/tree.dart @@ -33,8 +33,8 @@ Pointer owner(Pointer tree) => /// Lookup a tree entry by its position in the tree. /// -/// This returns a tree entry that is owned by the tree. You don't have to free it, -/// but you must not use it after the tree is released. +/// This returns a tree entry that is owned by the tree. You don't have to free +/// it, but you must not use it after the tree is released. /// /// Throws [RangeError] when provided index is outside of valid range. Pointer getByIndex({ @@ -52,8 +52,8 @@ Pointer getByIndex({ /// Lookup a tree entry by its filename. /// -/// This returns a tree entry that is owned by the tree. You don't have to free it, -/// but you must not use it after the tree is released. +/// This returns a tree entry that is owned by the tree. You don't have to free +/// it, but you must not use it after the tree is released. /// /// Throws [ArgumentError] if nothing found for provided filename. Pointer getByName({ @@ -72,10 +72,11 @@ Pointer getByName({ } } -/// Retrieve a tree entry contained in a tree or in any of its subtrees, given its relative path. +/// Retrieve a tree entry contained in a tree or in any of its subtrees, given +/// its relative path. /// -/// Unlike the other lookup functions, the returned tree entry is owned by the user and must be -/// freed explicitly with [entryFree]. +/// Unlike the other lookup functions, the returned tree entry is owned by the +/// user and must be freed explicitly with [entryFree]. /// /// Throws a [LibGit2Error] if error occured. Pointer getByPath({ diff --git a/lib/src/bindings/treebuilder.dart b/lib/src/bindings/treebuilder.dart index 7d70286..bada9d5 100644 --- a/lib/src/bindings/treebuilder.dart +++ b/lib/src/bindings/treebuilder.dart @@ -8,11 +8,11 @@ import 'libgit2_bindings.dart'; /// Create a new tree builder. /// -/// The tree builder can be used to create or modify trees in memory and write them -/// as tree objects to the database. +/// The tree builder can be used to create or modify trees in memory and write +/// them as tree objects to the database. /// -/// If the source parameter is not null, the tree builder will be initialized with -/// the entries of the given tree. +/// If the source parameter is not null, the tree builder will be initialized +/// with the entries of the given tree. /// /// If the source parameter is null, the tree builder will start with no entries /// and will have to be filled manually. @@ -72,8 +72,8 @@ Pointer getByFilename({ /// /// Insert a new entry for filename in the builder with the given attributes. /// -/// If an entry named filename already exists, its attributes will be updated with -/// the given ones. +/// If an entry named 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. diff --git a/lib/src/bindings/worktree.dart b/lib/src/bindings/worktree.dart index 2b928c5..6e68cdc 100644 --- a/lib/src/bindings/worktree.dart +++ b/lib/src/bindings/worktree.dart @@ -10,7 +10,8 @@ import 'libgit2_bindings.dart'; /// Add a new working tree. /// /// Add a new working tree for the repository, that is create the required -/// data structures inside the repository and check out the current HEAD at path. +/// data structures inside the repository and check out the current HEAD at +/// path. /// /// Throws a [LibGit2Error] if error occured. Pointer create({ @@ -136,8 +137,8 @@ void unlock(Pointer wt) => libgit2.git_worktree_unlock(wt); /// Check if 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. +/// A valid worktree requires both the git data structures inside the linked +/// parent repository and the linked working copy to be present. bool isValid(Pointer wt) { return libgit2.git_worktree_validate(wt) == 0 ? true : false; } diff --git a/lib/src/blame.dart b/lib/src/blame.dart index 71d5797..fcffc2d 100644 --- a/lib/src/blame.dart +++ b/lib/src/blame.dart @@ -14,18 +14,20 @@ class Blame with IterableMixin { /// /// [path] is the path to file to consider. /// - /// [flags] is a combination of [GitBlameFlag]s. Defaults to [GitBlameFlag.normal]. + /// [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 - /// it to associate those lines with the parent commit. The default value is 20. - /// This value only takes effect if any of the [GitBlameFlag.trackCopies*] + /// it to associate those lines with the parent commit. The default value is + /// 20. This value only takes effect if any of the [GitBlameFlag.trackCopies*] /// flags are specified. /// - /// [newestCommit] is the id of the newest commit to consider. The default is HEAD. + /// [newestCommit] is the id of the newest commit to consider. The default is + /// HEAD. /// - /// [oldestCommit] is the id of the oldest commit to consider. The default is the - /// first commit encountered with no parent. + /// [oldestCommit] is the id of the oldest commit to consider. The default is + /// the first commit encountered with no parent. /// /// [minLine] is the first line in the file to blame. The default is 1 /// (line numbers start with 1). @@ -71,7 +73,8 @@ class Blame with IterableMixin { )); } - /// Returns 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) { @@ -105,7 +108,8 @@ class BlameHunk { return _blameHunkPointer.ref.boundary == 1 ? true : false; } - /// 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; /// Author of [finalCommitOid]. If [GitBlameFlag.useMailmap] has been @@ -116,8 +120,8 @@ class BlameHunk { /// [Oid] of the commit where this line was last changed. Oid get finalCommitOid => Oid.fromRaw(_blameHunkPointer.ref.final_commit_id); - /// 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; /// Author of [originCommitOid]. If [GitBlameFlag.useMailmap] has been @@ -125,9 +129,9 @@ class BlameHunk { Signature get originCommitter => Signature(_blameHunkPointer.ref.orig_signature); - /// [Oid] of the commit where this hunk was found. This will usually be the same - /// as [finalCommitOid], except when [GitBlameFlag.trackCopiesAnyCommitCopies] - /// been specified. + /// [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); /// Path to the file where this hunk originated, as of the commit specified by @@ -138,8 +142,9 @@ class BlameHunk { @override String toString() { return 'BlameHunk{linesCount: $linesCount, isBoundary: $isBoundary, ' - 'finalStartLineNumber: $finalStartLineNumber, finalCommitter: $finalCommitter, ' - 'finalCommitOid: $finalCommitOid, originStartLineNumber: $originStartLineNumber, ' + 'finalStartLineNumber: $finalStartLineNumber, ' + 'finalCommitter: $finalCommitter, finalCommitOid: $finalCommitOid, ' + 'originStartLineNumber: $originStartLineNumber, ' 'originCommitter: $originCommitter, originCommitOid: $originCommitOid, ' 'originPath: $originPath}'; } diff --git a/lib/src/blob.dart b/lib/src/blob.dart index a88f8d2..e3aeefe 100644 --- a/lib/src/blob.dart +++ b/lib/src/blob.dart @@ -39,8 +39,9 @@ class Blob { )); } - /// Creates a new blob from the file in working directory of a repository and writes - /// it to the ODB. Provided [relativePath] should be relative to the working directory. + /// Creates a new blob from the file in working directory of a repository and + /// writes it to the ODB. Provided [relativePath] should be relative to the + /// working directory. /// /// Throws a [LibGit2Error] if error occured. static Oid createFromWorkdir({ @@ -120,7 +121,8 @@ class Blob { ); } - /// Directly generates a [Patch] from the difference between the blob and a buffer. + /// Directly generates a [Patch] from the difference between the blob and a + /// buffer. /// /// [buffer] is the raw data for new side of diff, or null for empty. /// diff --git a/lib/src/branch.dart b/lib/src/branch.dart index 1187b3c..780e9dc 100644 --- a/lib/src/branch.dart +++ b/lib/src/branch.dart @@ -69,11 +69,11 @@ class Branch { /// Pointer to memory address for allocated branch object. Pointer get pointer => _branchPointer; - /// Returns a list of branches that can be found in a [repo]sitory for provided [type]. - /// Default is all branches (local and remote). + /// 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 - /// memory leak. + /// **IMPORTANT**: Branches must be freed manually when no longer needed to + /// prevent memory leak. /// /// Throws a [LibGit2Error] if error occured. static List list({ @@ -133,8 +133,9 @@ class 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. + /// 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. /// /// Throws a [LibGit2Error] if error occured. bool get isCheckedOut => bindings.isCheckedOut(_branchPointer); @@ -152,6 +153,7 @@ class Branch { @override String toString() { - return 'Branch{name: $name, target: $target, isHead: $isHead, isCheckedOut: $isCheckedOut}'; + return 'Branch{name: $name, target: $target, isHead: $isHead, ' + 'isCheckedOut: $isCheckedOut}'; } } diff --git a/lib/src/callbacks.dart b/lib/src/callbacks.dart index e76d478..08e33be 100644 --- a/lib/src/callbacks.dart +++ b/lib/src/callbacks.dart @@ -1,20 +1,24 @@ import 'package:libgit2dart/libgit2dart.dart'; class Callbacks { - /// Callback functions used in various methods of [Remote] and with [Repository.clone]. + /// 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. + /// [transferProgress] is the callback function that reports transfer + /// progress. /// - /// [sidebandProgress] is the callback function that reports textual progress from the remote. + /// [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. + /// `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. + /// `void Function(String refname, String message)` used to inform of the + /// update status from the remote. const Callbacks({ this.credentials, this.transferProgress, @@ -32,11 +36,13 @@ class Callbacks { /// Callback function that reports textual progress from the remote. final void Function(String)? sidebandProgress; - /// Callback function matching the `void Function(String refname, Oid old, Oid new)` - /// that report reference updates. + /// Callback function matching the + /// `void Function(String refname, Oid old, Oid new)` that report reference + /// updates. final void Function(String, Oid, Oid)? updateTips; - /// Callback function matching the `void Function(String refname, String message)` - /// used to inform of the update status from the remote. + /// Callback function matching the + /// `void Function(String refname, String message)` used to inform of the + /// update status from the remote. final void Function(String, String)? pushUpdateReference; } diff --git a/lib/src/commit.dart b/lib/src/commit.dart index 0db4454..6570dbd 100644 --- a/lib/src/commit.dart +++ b/lib/src/commit.dart @@ -32,28 +32,29 @@ class 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. + /// [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. + /// [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]. + /// [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]. + /// [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({ @@ -81,17 +82,19 @@ class Commit { /// Amends an existing commit by replacing only non-null values. /// - /// This creates a new commit that is exactly the same as the old commit, except that - /// any non-null values will be updated. The new commit has the same parents as the old commit. + /// This creates a new commit that is exactly the same as the old commit, + /// except that any non-null values will be updated. The new commit has the + /// same parents as the old commit. /// - /// The [updateRef] value works as in the regular [create], updating the ref to point to - /// the newly rewritten commit. If you want to amend a commit that is not currently - /// 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. + /// The [updateRef] value works as in the regular [create], updating the ref + /// to point to the newly rewritten commit. If you want to amend a commit + /// that is not currently 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]. + /// 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]. /// @@ -169,14 +172,16 @@ class Commit { @override String toString() { - return 'Commit{oid: $oid, message: $message, messageEncoding: $messageEncoding, ' - 'time: $time, committer: $committer, author: $author}'; + return 'Commit{oid: $oid, message: $message, ' + 'messageEncoding: $messageEncoding, time: $time, committer: $committer,' + ' author: $author}'; } } -/// An annotated commit contains information about how it was looked up, which may be useful -/// for functions like merge or rebase to provide context to the operation. For example, conflict -/// files will include the name of the source or target branches being merged. +/// An annotated commit contains information about how it was looked up, which +/// may be useful for functions like merge or rebase to provide context to the +/// operation. For example, conflict files will include the name of the source +/// or target branches being merged. /// /// Note: for internal use. class AnnotatedCommit { diff --git a/lib/src/config.dart b/lib/src/config.dart index febbb99..2ba6641 100644 --- a/lib/src/config.dart +++ b/lib/src/config.dart @@ -21,7 +21,8 @@ class Config with IterableMixin { /// 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). + /// Git config file following the default Git config syntax (see + /// `man git-config`). /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -76,9 +77,9 @@ class Config with IterableMixin { /// Pointer to memory address for allocated config object. late final Pointer _configPointer; - /// 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). + /// 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)); /// Returns the [ConfigEntry] of a [variable]. @@ -153,8 +154,8 @@ class Config with IterableMixin { ); } - /// Deletes one or several values from a multivar [variable] in the config file - /// with the highest level (usually the local one). + /// Deletes one or several values from a multivar [variable] in the config + /// file with the highest level (usually the local one). /// /// The [regexp] is applied case-sensitively on the value. /// Empty [regexp] deletes all values of a multivar [variable]. @@ -205,7 +206,8 @@ class ConfigEntry { @override String toString() { - return 'ConfigEntry{name: $name, value: $value, includeDepth: $includeDepth, level: $level}'; + return 'ConfigEntry{name: $name, value: $value, ' + 'includeDepth: $includeDepth, level: $level}'; } } diff --git a/lib/src/credentials.dart b/lib/src/credentials.dart index 7a1749e..d38cb87 100644 --- a/lib/src/credentials.dart +++ b/lib/src/credentials.dart @@ -50,8 +50,8 @@ class Keypair implements Credentials { @override String toString() { - return 'Keypair{username: $username, pubKey: $pubKey, privateKey: $privateKey, ' - 'passPhrase: $passPhrase}'; + return 'Keypair{username: $username, pubKey: $pubKey, ' + 'privateKey: $privateKey, passPhrase: $passPhrase}'; } } @@ -95,7 +95,7 @@ class KeypairFromMemory implements Credentials { @override String toString() { - return 'KeypairFromMemory{username: $username, pubKey: $pubKey, privateKey: $privateKey, ' - 'passPhrase: $passPhrase}'; + return 'KeypairFromMemory{username: $username, pubKey: $pubKey, ' + 'privateKey: $privateKey, passPhrase: $passPhrase}'; } } diff --git a/lib/src/diff.dart b/lib/src/diff.dart index 78c9b5c..df480b3 100644 --- a/lib/src/diff.dart +++ b/lib/src/diff.dart @@ -17,13 +17,15 @@ class Diff { /// 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. - /// For example, a patch file likely contains abbreviated object IDs, so the object IDs in a - /// diff delta produced by this function will also be abbreviated. + /// 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. For example, a patch file likely + /// contains abbreviated object IDs, so the object IDs in a diff delta + /// produced by this function will also be abbreviated. /// - /// This function will only read patch files created by a git implementation, it will not - /// read unified diffs produced by the `diff` program, nor any other types of patch files. + /// This function will only read patch files created by a git implementation, + /// it will not read unified diffs produced by the `diff` program, nor any + /// other types of patch files. Diff.parse(String content) { libgit2.git_libgit2_init(); _diffPointer = bindings.parse(content); @@ -37,7 +39,8 @@ class 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. + /// Returns a list of [DiffDelta]s containing file pairs with and old and new + /// revisions. List get deltas { final length = bindings.length(_diffPointer); var deltas = []; @@ -96,28 +99,32 @@ class Diff { /// Transforms a diff marking file renames, copies, etc. /// - /// This modifies a diff in place, replacing old entries that look like renames or copies - /// 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. + /// This modifies a diff in place, replacing old entries that look like + /// renames or copies 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]. + /// [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. + /// [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. + /// [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. + /// [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. + /// [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. + /// [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({ @@ -139,12 +146,13 @@ class Diff { ); } - /// Calculates a stable patch [Oid] for the given patch by summing the hash of the file diffs, - /// ignoring whitespace and line numbers. This can be used to derive whether two diffs are - /// the same with a high probability. + /// Calculates a stable patch [Oid] for the given patch by summing the hash + /// of the file diffs, ignoring whitespace and line numbers. This can be used + /// to derive whether two diffs are the same with a high probability. /// - /// Currently, this function only calculates stable patch IDs, as defined in `git-patch-id(1)`, - /// and should in fact generate the same IDs as the upstream git project does. + /// Currently, this function only calculates stable patch IDs, as defined in + /// `git-patch-id(1)`, and should in fact generate the same IDs as the + /// upstream git project does. /// /// Throws a [LibGit2Error] if error occured. Oid get patchOid => Oid(bindings.patchOid(_diffPointer)); @@ -175,10 +183,10 @@ class DiffDelta { /// 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] - /// value into these letters for your own purposes. [GitDelta.untracked] will return - /// a space (i.e. ' '). + /// 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] value into these letters for your own + /// purposes. [GitDelta.untracked] will return a space (i.e. ' '). String get statusChar => bindings.statusChar(_diffDeltaPointer.ref.status); /// Flags for the delta object. @@ -214,7 +222,8 @@ class DiffDelta { /// link, a submodule commit id, or even a tree (although that only if you /// are tracking type changes or ignored/untracked directories). class DiffFile { - /// Initializes a new instance of [DiffFile] class from provided diff file object. + /// Initializes a new instance of [DiffFile] class from provided diff file + /// object. const DiffFile(this._diffFile); final git_diff_file _diffFile; @@ -243,7 +252,8 @@ class DiffFile { @override String toString() { - return 'DiffFile{oid: $oid, path: $path, size: $size, flags: $flags, mode: $mode}'; + return 'DiffFile{oid: $oid, path: $path, size: $size, flags: $flags, ' + 'mode: $mode}'; } } @@ -284,13 +294,15 @@ class DiffStats { @override String toString() { - return 'DiffStats{insertions: $insertions, deletions: $deletions, filesChanged: $filesChanged}'; + return 'DiffStats{insertions: $insertions, deletions: $deletions, ' + 'filesChanged: $filesChanged}'; } } class DiffHunk { /// Initializes a new instance of [DiffHunk] class from provided - /// pointers to patch object and diff hunk object in memory and number of lines in hunk. + /// pointers to patch object and diff hunk object in memory and number of + /// lines in hunk. const DiffHunk( this._patchPointer, this._diffHunkPointer, @@ -346,8 +358,9 @@ class DiffHunk { @override String toString() { - return 'DiffHunk{linesCount: $linesCount, index: $index, oldStart: $oldStart, ' - 'oldLines: $oldLines, newStart: $newStart, newLines: $newLines, header: $header}'; + return 'DiffHunk{linesCount: $linesCount, index: $index, ' + 'oldStart: $oldStart, oldLines: $oldLines, newStart: $newStart, ' + 'newLines: $newLines, header: $header}'; } } @@ -384,7 +397,8 @@ class DiffLine { @override String toString() { - return 'DiffLine{oldLineNumber: $oldLineNumber, newLineNumber: $newLineNumber, ' - 'numLines: $numLines, contentOffset: $contentOffset, content: $content}'; + return 'DiffLine{oldLineNumber: $oldLineNumber, ' + 'newLineNumber: $newLineNumber, numLines: $numLines, ' + 'contentOffset: $contentOffset, content: $content}'; } } diff --git a/lib/src/git_types.dart b/lib/src/git_types.dart index e77b877..b2041ca 100644 --- a/lib/src/git_types.dart +++ b/lib/src/git_types.dart @@ -70,8 +70,8 @@ class GitSort { /// this sorting mode can be combined with topological sorting. static const time = GitSort._(2, 'time'); - /// Iterate through the repository contents in reverse order; this sorting mode - /// can be combined with any of the above. + /// Iterate through the repository contents in reverse order; this sorting + /// mode can be combined with any of the above. static const reverse = GitSort._(4, 'reverse'); static const List values = [none, topological, time, reverse]; @@ -1336,8 +1336,8 @@ class GitFeature { final int _value; final String _name; - /// If set, libgit2 was built thread-aware and can be safely used from multiple - /// threads. + /// If set, libgit2 was built thread-aware and can be safely used from + /// multiple threads. static const threads = GitFeature._(1, 'threads'); /// If set, libgit2 was built with and linked against a TLS implementation. @@ -1596,7 +1596,8 @@ class GitSubmoduleUpdate { /// out branch of the submodule. static const merge = GitSubmoduleUpdate._(3, 'merge'); - /// Do not update this submodule even when the commit in the superproject is updated. + /// Do not update this submodule even when the commit in the superproject is + /// updated. static const none = GitSubmoduleUpdate._(4, 'none'); static const List values = [ diff --git a/lib/src/index.dart b/lib/src/index.dart index 9a0f003..27606d8 100644 --- a/lib/src/index.dart +++ b/lib/src/index.dart @@ -84,18 +84,20 @@ class Index with IterableMixin { /// Clears the contents (all the entries) of an index object. /// - /// This clears the index object in memory; changes must be explicitly written to - /// disk for them to take effect persistently. + /// This clears the index object in memory; changes must be explicitly + /// written to disk for them to take effect persistently. /// /// Throws a [LibGit2Error] if error occured. void clear() => bindings.clear(_indexPointer); - /// Adds or updates an index entry from an [IndexEntry] or from a file on disk. + /// Adds or updates an index entry from an [IndexEntry] or from a file on + /// disk. /// - /// If a previous index entry exists that has the same path and stage as the given `entry`, - /// it will be replaced. Otherwise, the `entry` will be added. + /// If a previous index entry exists that has the same path and stage as the + /// given [entry], it will be replaced. Otherwise, the [entry] will be added. /// - /// The file path must be relative to the repository's working folder and must be readable. + /// The file path must be relative to the repository's working folder and + /// must be readable. /// /// This method will fail in bare index instances. /// @@ -115,47 +117,51 @@ 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 - /// 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). + /// 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). /// /// Throws a [LibGit2Error] if error occured. void addAll(List pathspec) { bindings.addAll(indexPointer: _indexPointer, pathspec: pathspec); } - /// Updates the contents of an existing index object in memory by reading from the hard disk. + /// 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 - /// always reloads the on-disk index data. If there is no on-disk version, - /// the index will be cleared. + /// 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 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. + /// If [force] is false, this does a "soft" read that reloads the index data + /// from disk only if it has changed since the last time it was loaded. + /// Purely in-memory index data will be untouched. Be aware: if there are + /// changes on disk, unwritten in-memory changes are discarded. void read({bool force = true}) => bindings.read(indexPointer: _indexPointer, force: force); - /// Updates the contents of an existing index object in memory by reading from the - /// specified [tree]. + /// Updates the contents of an existing index object in memory by reading + /// from the specified [tree]. void readTree(Tree tree) { bindings.readTree(indexPointer: _indexPointer, treePointer: tree.pointer); } - /// Writes an existing index object from memory back to disk using an atomic file lock. + /// Writes an existing index object from memory back to disk using an atomic + /// file lock. void write() => bindings.write(_indexPointer); /// Writes the index as a tree. /// - /// 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. + /// 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. /// /// 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)); @@ -167,15 +173,15 @@ class Index with IterableMixin { } } - /// Removes an entry from the index at provided [path] relative to repository working - /// directory with optional [stage]. + /// 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 at provided list of [path]s relative to repository - /// working directory. + /// 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) => @@ -310,7 +316,8 @@ class ConflictEntry { @override String toString() => - 'ConflictEntry{ancestor: $ancestor, our: $our, their: $their, path: $_path}'; + 'ConflictEntry{ancestor: $ancestor, our: $our, their: $their, ' + 'path: $_path}'; } class _IndexIterator implements Iterator { diff --git a/lib/src/mailmap.dart b/lib/src/mailmap.dart index edc73d5..9d8644d 100644 --- a/lib/src/mailmap.dart +++ b/lib/src/mailmap.dart @@ -31,7 +31,8 @@ class Mailmap { /// /// Mailmaps are loaded in the following order: /// - /// 1. `.mailmap` in the root of the repository's working directory, if present. + /// 1. `.mailmap` in the root of the repository's working directory, if + /// present. /// 2. The blob object identified by the `mailmap.blob` config entry, if set. /// NOTE: `mailmap.blob` defaults to `HEAD:.mailmap` in bare repositories /// 3. The path in the `mailmap.file` config entry, if set. @@ -46,8 +47,8 @@ class Mailmap { /// Pointer to memory address for allocated mailmap object. late final Pointer _mailmapPointer; - /// Returns list containing resolved [name] and [email] to the corresponding real name - /// and real email respectively. + /// Returns list containing resolved [name] and [email] to the corresponding + /// real name and real email respectively. List resolve({ required String name, required String email, @@ -67,8 +68,8 @@ class Mailmap { )); } - /// Adds a single entry to the given mailmap object. If the entry already exists, - /// it will be replaced with the new entry. + /// Adds a single entry to the given mailmap object. If the entry already + /// exists, it will be replaced with the new entry. /// /// Throws a [ArgumentError] if [replaceEmail] is empty string. void addEntry({ diff --git a/lib/src/odb.dart b/lib/src/odb.dart index 8570961..ae695ce 100644 --- a/lib/src/odb.dart +++ b/lib/src/odb.dart @@ -30,11 +30,11 @@ class Odb { /// Adds an on-disk alternate to an existing Object DB. /// - /// Note that the added [path] must point to an `objects`, not to a full repository, - /// to use it as an alternate store. + /// Note that the added [path] must point to an `objects`, not to a full + /// repository, to use it as an alternate store. /// - /// Alternate backends are always checked for objects after all the main backends - /// have been exhausted. + /// Alternate backends are always checked for objects after all the main + /// backends have been exhausted. /// /// Writing is disabled on alternate backends. void addDiskAlternate(String path) { @@ -56,9 +56,11 @@ class Odb { /// Reads an object from the database. /// - /// This method queries all available ODB backends trying to read the given [oid]. + /// This method queries all available ODB backends trying to read the given + /// [oid]. /// - /// **IMPORTANT**: Returned object should be freed to release allocated memory. + /// **IMPORTANT**: Returned object should be freed to release allocated + /// memory. /// /// Throws a [LibGit2Error] if error occured. OdbObject read(Oid oid) { @@ -70,10 +72,11 @@ class Odb { /// Writes raw [data] to into the object database. /// - /// [type] should be one of [GitObject.blob], [GitObject.commit], [GitObject.tag] or - /// [GitObject.tree]. + /// [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. + /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided + /// type is invalid. Oid write({required GitObject type, required String data}) { if (type == GitObject.any || type == GitObject.invalid || diff --git a/lib/src/oid.dart b/lib/src/oid.dart index 5c3ea5a..f58b789 100644 --- a/lib/src/oid.dart +++ b/lib/src/oid.dart @@ -12,9 +12,9 @@ class Oid { /// pointer to Oid object in memory. Oid(this._oidPointer); - /// Initializes a new instance of [Oid] class by determining if an object can be found - /// in the ODB of [repo]sitory with provided hexadecimal [sha] string that is 40 characters - /// long or shorter. + /// Initializes a new instance of [Oid] class by determining if an object can + /// be found in the ODB of [repo]sitory with provided hexadecimal [sha] + /// string that is 40 characters long or shorter. /// /// Throws [ArgumentError] if provided [sha] hex string is not valid. /// @@ -37,7 +37,8 @@ class Oid { } } - /// Initializes a new instance of [Oid] class from provided raw git_oid structure. + /// Initializes a new instance of [Oid] class from provided raw git_oid + /// structure. Oid.fromRaw(git_oid raw) { _oidPointer = bindings.fromRaw(raw.id); } diff --git a/lib/src/patch.dart b/lib/src/patch.dart index 009c50f..5126765 100644 --- a/lib/src/patch.dart +++ b/lib/src/patch.dart @@ -12,8 +12,8 @@ class Patch { /// **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 - /// blob and a buffer. + /// Directly generates a patch from the difference between two blobs, buffers + /// or blob and a buffer. /// /// [a] and [b] can be [Blob], [String] or null. /// @@ -117,15 +117,15 @@ class Patch { /// 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. + /// 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. /// - /// 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 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. + /// If [includeHunkHeaders] and [includeFileHeaders] are set to true, they + /// will be included in the total size. int size({ bool includeContext = false, bool includeHunkHeaders = false, diff --git a/lib/src/rebase.dart b/lib/src/rebase.dart index 44fde1a..2537338 100644 --- a/lib/src/rebase.dart +++ b/lib/src/rebase.dart @@ -4,16 +4,18 @@ import 'bindings/libgit2_bindings.dart'; import 'bindings/rebase.dart' as bindings; class Rebase { - /// Initializes a rebase operation to rebase the changes in [branch] relative to [upstream] - /// [onto] another branch. To begin the rebase process, call [next]. + /// 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. + /// [branch] is the terminal commit to rebase, default is to rebase the + /// current branch. /// /// [upstream] is the commit to begin rebasing from, default is to rebase all /// reachable commits. /// - /// [onto] is the branch to rebase onto, default is to rebase onto the given [upstream] - /// (throws if [upstream] is not provided). + /// [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. /// @@ -62,10 +64,11 @@ class Rebase { } /// Performs the next rebase operation and returns the information about it. - /// If the operation is one that applies a patch (which is any operation except - /// [GitRebaseOperation.exec]) then the patch will be applied and the index and - /// working directory will be updated with the changes. If there are conflicts, - /// you will need to address those before committing the changes. + /// If the operation is one that applies a patch (which is any operation + /// except [GitRebaseOperation.exec]) then the patch will be applied and the + /// index and working directory will be updated with the changes. If there + /// are conflicts, you will need to address those before committing the + /// changes. /// /// Throws a [LibGit2Error] if error occured. RebaseOperation next() { @@ -77,11 +80,11 @@ class Rebase { /// /// [committer] is the committer of the rebase. /// - /// [message] the message for this commit, can be null to use the message from the - /// original commit. + /// [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. + /// [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({ @@ -97,11 +100,12 @@ class Rebase { ); } - /// Finishes a rebase that is currently in progress once all patches have been applied. + /// Finishes a rebase that is currently in progress once all patches have + /// been applied. void finish() => bindings.finish(_rebasePointer); - /// Aborts a rebase that is currently in progress, resetting the repository and working - /// directory to their state before rebase began. + /// Aborts a rebase that is currently in progress, resetting the repository + /// and working directory to their state before rebase began. void abort() => bindings.abort(_rebasePointer); /// Releases memory allocated for rebase object. diff --git a/lib/src/reference.dart b/lib/src/reference.dart index 2c57b97..e5d3f05 100644 --- a/lib/src/reference.dart +++ b/lib/src/reference.dart @@ -22,20 +22,21 @@ class Reference { /// 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 - /// with a letter. (e.g. "HEAD", "ORIG_HEAD"). + /// - 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 /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have /// special meaning to revparse. /// - /// Throws a [LibGit2Error] if a reference already exists with the given [name] - /// unless [force] is true, in which case it will be overwritten. + /// Throws a [LibGit2Error] if a reference already exists with the given + /// [name] unless [force] is true, in which case it will be overwritten. /// - /// The [logMessage] message for the reflog will be ignored if the reference does not belong in the - /// standard set (HEAD, branches and remote-tracking branches) and it does not have a reflog. + /// The [logMessage] message for the reflog will be ignored if the reference + /// does not belong in the standard set (HEAD, branches and remote-tracking + /// branches) and it does not have a reflog. /// - /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided [target] - /// is not Oid or String reference name. + /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided + /// [target] is not Oid or String reference name. Reference.create({ required Repository repo, required String name, @@ -96,11 +97,12 @@ class Reference { /// /// The [newName] will be checked for validity. /// - /// If the [force] flag is set to false, and there's already a reference with the given name, - /// the renaming will fail. + /// If the [force] flag is set to false, and there's already a reference with + /// the given name, the renaming will fail. /// - /// IMPORTANT: The user needs to write a proper reflog entry [logMessage] if the reflog is - /// enabled for the repository. We only rename the reflog if it exists. + /// IMPORTANT: The user needs to write a proper reflog entry [logMessage] if + /// the reflog is enabled for the repository. We only rename the reflog if it + /// exists. /// /// Throws a [LibGit2Error] if error occured. static void rename({ @@ -125,9 +127,9 @@ class Reference { /// Throws a [LibGit2Error] if error occured. static List list(Repository repo) => bindings.list(repo.pointer); - /// Suggests that the [repo]sitory's refdb compress or optimize its references. - /// This mechanism is implementation specific. For on-disk reference databases, - /// for example, this may pack all loose references. + /// Suggests that the [repo]sitory's refdb compress or optimize its + /// references. This mechanism is implementation specific. For on-disk + /// reference databases, for example, this may pack all loose references. /// /// Throws a [LibGit2Error] if error occured. static void compress(Repository repo) { @@ -159,11 +161,11 @@ class Reference { /// Updates the [target] of this reference. /// - /// [target] being either Oid for direct reference or string reference name for symbolic - /// reference. + /// [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. + /// Throws a [LibGit2Error] if error occured or [ArgumentError] if [target] + /// is not [Oid] or string. void setTarget({required Object target, String? logMessage}) { if (target is Oid) { final newPointer = bindings.setTarget( @@ -189,11 +191,14 @@ class Reference { /// Recursively peel reference until object of the specified [type] is found. /// - /// The retrieved peeled object is owned by the repository and should be closed to release memory. + /// The retrieved peeled object is owned by the repository and should be + /// freed to release memory. /// - /// If no [type] is provided, then the object will be peeled until a non-tag object is met. + /// If no [type] is provided, then the object will be peeled until a non-tag + /// object is met. /// - /// Returned object should be explicitly downcasted to one of four of git object types. + /// Returned object should be explicitly downcasted to one of four of git + /// object types. /// /// ```dart /// final commit = ref.peel(GitObject.commit) as Commit; @@ -223,8 +228,8 @@ class Reference { /// 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. + /// 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); /// Whether reflog exists for the specified reference [name]. @@ -272,7 +277,8 @@ class Reference { @override String toString() { - return 'Reference{name: $name, target: $target, type: $type, isBranch: $isBranch, ' - 'isNote: $isNote, isRemote: $isRemote, isTag: $isTag}'; + return 'Reference{name: $name, target: $target, type: $type, ' + 'isBranch: $isBranch, isNote: $isNote, isRemote: $isRemote, ' + 'isTag: $isTag}'; } } diff --git a/lib/src/refspec.dart b/lib/src/refspec.dart index e6950b1..916f360 100644 --- a/lib/src/refspec.dart +++ b/lib/src/refspec.dart @@ -56,7 +56,8 @@ class Refspec { ); } - /// Transforms a target reference to its source reference following the refspec's rules. + /// Transforms a target reference to its source reference following the + /// refspec's rules. /// /// Throws a [LibGit2Error] if error occured. String rTransform(String name) { @@ -68,6 +69,7 @@ class Refspec { @override String toString() { - return 'Refspec{source: $source, destination: $destination, force: $force, string: $string}'; + return 'Refspec{source: $source, destination: $destination, force: $force, ' + 'string: $string}'; } } diff --git a/lib/src/remote.dart b/lib/src/remote.dart index 29563b7..6a4fe95 100644 --- a/lib/src/remote.dart +++ b/lib/src/remote.dart @@ -50,7 +50,8 @@ class Remote { /// Deletes an existing persisted remote with provided [name]. /// - /// All remote-tracking branches and configuration settings for the remote will be removed. + /// All remote-tracking branches and configuration settings for the remote + /// will be removed. /// /// Throws a [LibGit2Error] if error occured. static void delete({required Repository repo, required String name}) { @@ -61,12 +62,13 @@ class Remote { /// /// Returns list of non-default refspecs that cannot be renamed. /// - /// All remote-tracking branches and configuration settings for the remote are updated. + /// All remote-tracking branches and configuration settings for the remote + /// are updated. /// /// 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. + /// No loaded instances of a the remote with the old name will change their + /// name or their list of refspecs. /// /// Throws a [LibGit2Error] if error occured. static List rename({ @@ -88,8 +90,8 @@ class Remote { /// 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. + /// 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. /// /// Throws a [LibGit2Error] if error occured. static void setUrl({ @@ -106,8 +108,8 @@ class Remote { /// 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. + /// 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. /// /// Throws a [LibGit2Error] if error occured. static void setPushUrl({ @@ -184,17 +186,20 @@ class Remote { /// List of push refspecs. List get pushRefspecs => bindings.pushRefspecs(_remotePointer); - /// Returns the remote repository's reference list and their associated commit ids. + /// Returns the remote repository's reference list and their associated + /// commit ids. /// - /// [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. + /// [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. + /// [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 - /// pointing to. null if there is no local copy of the remote head. + /// - `loid` is the oid of the object the local copy of the remote head is + /// currently pointing to. null if there is no local copy of the remote head. /// - `name` is the name of the reference. /// - `oid` is the oid of the object the remote head is currently pointing to. /// - `symref` is the target of the symbolic reference or empty string. @@ -217,16 +222,20 @@ class Remote { /// Downloads new data and updates tips. /// - /// [refspecs] is the list of refspecs to use for this fetch. Defaults to the base refspecs. + /// [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". + /// [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. + /// [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. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// Throws a [LibGit2Error] if error occured. TransferProgress fetch({ @@ -249,12 +258,15 @@ class Remote { /// Performs a push. /// - /// [refspecs] is the list of refspecs to use for pushing. Defaults to the configured refspecs. + /// [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. + /// [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. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// Throws a [LibGit2Error] if error occured. void push({ @@ -272,7 +284,8 @@ class Remote { /// Prunes tracking refs that are no longer present on remote. /// - /// [callbacks] is the combination of callback functions from [Callbacks] object. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// Throws a [LibGit2Error] if error occured. void prune([Callbacks callbacks = const Callbacks()]) { @@ -287,15 +300,16 @@ class Remote { @override String toString() { - return 'Remote{name: $name, url: $url, pushUrl: $pushUrl, refspecCount: $refspecCount}'; + return 'Remote{name: $name, url: $url, pushUrl: $pushUrl, ' + 'refspecCount: $refspecCount}'; } } -/// Provides callers information about the progress of indexing a packfile, either -/// directly or part of a fetch or clone that downloads a packfile. +/// Provides callers information about the progress of indexing a packfile, +/// either directly or part of a fetch or clone that downloads a packfile. class TransferProgress { - /// Initializes a new instance of [TransferProgress] class from provided pointer - /// to transfer progress object in memory. + /// Initializes a new instance of [TransferProgress] class from provided + /// pointer to transfer progress object in memory. const TransferProgress(this._transferProgressPointer); /// Pointer to memory address for allocated transfer progress object. @@ -324,8 +338,9 @@ class TransferProgress { @override String toString() { - return 'TransferProgress{totalObjects: $totalObjects, indexedObjects: $indexedObjects, ' - 'receivedObjects: $receivedObjects, localObjects: $localObjects, totalDeltas: $totalDeltas, ' + return 'TransferProgress{totalObjects: $totalObjects, ' + 'indexedObjects: $indexedObjects, receivedObjects: $receivedObjects, ' + 'localObjects: $localObjects, totalDeltas: $totalDeltas, ' 'indexedDeltas: $indexedDeltas, receivedBytes: $receivedBytes}'; } } diff --git a/lib/src/repository.dart b/lib/src/repository.dart index 54c58e3..ad2f8aa 100644 --- a/lib/src/repository.dart +++ b/lib/src/repository.dart @@ -33,24 +33,26 @@ class Repository { /// [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). + /// [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. + /// [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. + /// [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. + /// [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. + /// [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. + /// [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. /// @@ -103,8 +105,9 @@ class Repository { /// 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. + /// 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. /// @@ -112,16 +115,19 @@ class Repository { /// /// [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. + /// [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. /// - /// [repository] is the callback function matching the `Repository Function(String path, bool bare)` - /// signature. The [Repository] it returns will be used instead of creating a new one. + /// [repository] is the callback function matching the + /// `Repository Function(String path, bool bare)` signature. The [Repository] + /// it returns will be used instead of creating a new one. /// - /// [checkoutBranch] is the name of the branch to checkout after the clone. Defaults - /// to using the remote's default branch. + /// [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. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -153,11 +159,13 @@ class Repository { /// Pointer to memory address for allocated repository object. Pointer get pointer => _repoPointer; - /// 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]. + /// 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]. /// - /// The method will automatically detect if the repository is bare (if there is a repository). + /// The method will automatically detect if the repository is bare (if there + /// is a repository). static String discover({required String startPath, String? ceilingDirs}) { return bindings.discover( startPath: startPath, @@ -174,8 +182,8 @@ class Repository { return Oid.fromSHA(repo: this, sha: sha); } - /// 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); /// Path of the shared common directory for this repository. @@ -193,10 +201,11 @@ class Repository { /// Sets the active [namespace] for this repository. /// - /// This namespace affects all reference operations for the repo. See `man gitnamespaces` + /// 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. + /// The [namespace] should not include the refs folder, e.g. to namespace all + /// references under "refs/namespaces/foo/", use "foo" as the namespace. /// /// Pass null to unset. void setNamespace(String? namespace) { @@ -219,7 +228,8 @@ class Repository { /// Whether repository's HEAD is detached. /// - /// A repository's HEAD is detached when it points directly to a commit instead of a branch. + /// A repository's HEAD is detached when it points directly to a commit + /// instead of a branch. /// /// Throws a [LibGit2Error] if error occured. bool get isHeadDetached { @@ -228,17 +238,20 @@ class Repository { /// Makes the repository HEAD point to the specified reference or commit. /// - /// If the provided [target] points to a Tree or a Blob, the HEAD is unaltered. + /// If the provided [target] points to a Tree or a Blob, the HEAD is + /// unaltered. /// - /// If the provided [target] points to a branch, the HEAD will point to that branch, - /// staying attached, or become attached if it isn't yet. + /// If the provided [target] points to a branch, the HEAD will point to that + /// branch, staying attached, or become attached if it isn't yet. /// - /// If the branch doesn't exist yet, the HEAD will be attached to an unborn branch. + /// If the branch doesn't exist yet, the HEAD will be attached to an unborn + /// branch. /// - /// Otherwise, the HEAD will be detached and will directly point to the Commit. + /// 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. + /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided + /// [target] is not [Oid] or string. void setHead(Object target) { if (target is Oid) { bindings.setHeadDetached( @@ -255,8 +268,8 @@ class Repository { /// 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. + /// 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. /// /// Throws a [LibGit2Error] if error occured. bool get isBranchUnborn { @@ -265,7 +278,8 @@ 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. + /// 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. @@ -295,7 +309,8 @@ class Repository { /// /// Use this function to get the contents of this file. /// - /// **IMPORTANT**: 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); @@ -303,8 +318,8 @@ class Repository { /// Removes git's prepared message. void removeMessage() => bindings.removeMessage(_repoPointer); - /// 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( @@ -328,9 +343,9 @@ class Repository { /// The working directory doesn't need to be the same one that contains the /// ".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). + /// 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) @@ -349,24 +364,29 @@ class Repository { @override String toString() { - return 'Repository{path: $path, commonDir: $commonDir, namespace: $namespace, ' - 'isBare: $isBare, isEmpty: $isEmpty, isHeadDetached: $isHeadDetached, ' - 'isBranchUnborn: $isBranchUnborn, isShallow: $isShallow, isWorktree: $isWorktree, ' - 'state: $state, workdir: $workdir}'; + return 'Repository{path: $path, commonDir: $commonDir, ' + 'namespace: $namespace, isBare: $isBare, isEmpty: $isEmpty, ' + 'isHeadDetached: $isHeadDetached, isBranchUnborn: $isBranchUnborn, ' + 'isShallow: $isShallow, isWorktree: $isWorktree, state: $state, ' + 'workdir: $workdir}'; } /// 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). + /// 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). /// /// **IMPORTANT**: Should be freed to release allocated memory. Config get config => Config(bindings.config(_repoPointer)); /// 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. + /// 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. /// /// **IMPORTANT**: Should be freed to release allocated memory. Config get configSnapshot => Config(bindings.configSnapshot(_repoPointer)); @@ -400,20 +420,21 @@ class Repository { /// 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 - /// with a letter. (e.g. "HEAD", "ORIG_HEAD"). + /// - 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 /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have /// special meaning to revparse. /// - /// Throws a [LibGit2Error] if a reference already exists with the given [name] - /// unless [force] is true, in which case it will be overwritten. + /// Throws a [LibGit2Error] if a reference already exists with the given + /// [name] unless [force] is true, in which case it will be overwritten. /// - /// The [logMessage] message for the reflog will be ignored if the reference does not belong in the - /// standard set (HEAD, branches and remote-tracking branches) and it does not have a reflog. + /// The [logMessage] message for the reflog will be ignored if the reference + /// does not belong in the standard set (HEAD, branches and remote-tracking + /// branches) and it does not have a reflog. /// - /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided [target] - /// is not Oid or String reference name. + /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided + /// [target] is not Oid or String reference name. Reference createReference({ required String name, required Object target, @@ -442,11 +463,12 @@ class Repository { /// /// The [newName] will be checked for validity. /// - /// If the [force] flag is set to false, and there's already a reference with the given name, - /// the renaming will fail. + /// If the [force] flag is set to false, and there's already a reference with + /// the given name, the renaming will fail. /// - /// IMPORTANT: The user needs to write a proper reflog entry [logMessage] if the reflog is - /// enabled for the repository. We only rename the reflog if it exists. + /// IMPORTANT: The user needs to write a proper reflog entry [logMessage] if + /// the reflog is enabled for the repository. We only rename the reflog if it + /// exists. /// /// Throws a [LibGit2Error] if error occured. void renameReference({ @@ -485,13 +507,15 @@ class Repository { /// 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 - /// current time as the timestamp, and creates a new signature based on that information. + /// 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). + /// 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({ @@ -529,28 +553,29 @@ class Repository { /// Creates new commit in the repository. /// - /// [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 + /// [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. + /// [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]. + /// [tree] is an instance of a [Tree] object that will be used as the tree + /// for the commit. /// - /// [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]. + /// [parents] is a list of [Commit] objects that will be used as the parents + /// for this commit. This list 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({ @@ -574,17 +599,19 @@ class Repository { /// Amends an existing commit by replacing only non-null values. /// - /// This creates a new commit that is exactly the same as the old commit, except that - /// any non-null values will be updated. The new commit has the same parents as the old commit. + /// This creates a new commit that is exactly the same as the old commit, + /// except that any non-null values will be updated. The new commit has the + /// same parents as the old commit. /// - /// The [updateRef] value works as in the regular [create], updating the ref to point to - /// the newly rewritten commit. If you want to amend a commit that is not currently - /// 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. + /// The [updateRef] value works as in the regular [create], updating the ref + /// to point to the newly rewritten commit. If you want to amend a commit + /// that is not currently 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]. + /// 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]. /// @@ -610,8 +637,8 @@ class Repository { ); } - /// Reverts provided [revertCommit] against provided [ourCommit], producing an index that - /// reflects the result of the revert. + /// 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). /// @@ -631,16 +658,18 @@ class Repository { )); } - /// Finds a single object and intermediate reference (if there is one) by a [spec] revision string. + /// Finds a single object and intermediate reference (if there is one) by a + /// [spec] revision string. /// /// See `man gitrevisions`, or https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions /// for information on the syntax accepted. /// - /// In some cases (@{<-n>} or @{upstream}), the expression may point to an - /// intermediate reference. When such expressions are being passed in, reference_out will be - /// valued as well. + /// In some cases (@{<-n>} or @{upstream}), the expression may + /// point to an intermediate reference. When such expressions are being + /// passed in, reference_out will be valued as well. /// - /// **IMPORTANT**: 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) { @@ -669,8 +698,9 @@ class Repository { /// Throws a [LibGit2Error] if error occured. 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 [relativePath] should be relative to the working directory. + /// Creates a new blob from the file in working directory of a repository and + /// writes it to the ODB. Provided [relativePath] should be relative to the + /// working directory. /// /// Throws a [LibGit2Error] if error occured. Oid createBlobFromWorkdir(String relativePath) { @@ -680,8 +710,8 @@ class Repository { ); } - /// Creates a new blob from the file at provided [path] 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) { @@ -700,8 +730,9 @@ class Repository { /// Creates a new tag in the repository for provided [target] object. /// - /// A new reference will also be created pointing to this tag object. If [force] is true - /// and a reference already exists with the given name, it'll be replaced. + /// A new reference will also be created pointing to this tag object. If + /// [force] is true and a reference already exists with the given name, it'll + /// be replaced. /// /// The [message] will not be cleaned up. /// @@ -709,18 +740,23 @@ class Repository { /// '~', '^', ':', '\', '?', '[', 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. + /// [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]. + /// [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. + /// [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. + /// [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. + /// [force] determines whether existing reference with the same [tagName] + /// should be replaced. /// /// Throws a [LibGit2Error] if error occured. Oid createTag({ @@ -865,8 +901,8 @@ class Repository { .toDartString(); } - // Skipping GitStatus.current because entry that is in the list can't be without changes - // but `&` on `0` value falsly adds it to the set of flags + // Skipping GitStatus.current because entry that is in the list can't be + // without changes but `&` on `0` value falsly adds it to the set of flags result[path] = GitStatus.values .skip(1) .where((e) => entry.ref.status & e.value == e.value) @@ -880,10 +916,11 @@ class Repository { /// 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 - /// file status with rename detection, there is no choice but to do a full [status] and scan - /// through looking for the path that you are interested in. + /// 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 file status with rename + /// detection, there is no choice but to do a full [status] and scan through + /// looking for the path that you are interested in. /// /// Throws a [LibGit2Error] if error occured. Set statusFile(String path) { @@ -895,7 +932,8 @@ class Repository { if (statusInt == GitStatus.current.value) { return {GitStatus.current}; } else { - // Skipping GitStatus.current because `&` on `0` value falsly adds it to the set of flags + // Skipping GitStatus.current because `&` on `0` value falsly adds it to + // the set of flags return GitStatus.values .skip(1) .where((e) => statusInt & e.value == e.value) @@ -914,11 +952,12 @@ class Repository { )); } - /// Analyzes the given branch's [theirHead] oid and determines the opportunities for - /// merging them into [ourRef] 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. + /// Returns list with analysis result and preference for fast forward merge + /// values respectively. /// /// Throws a [LibGit2Error] if error occured. List mergeAnalysis({ @@ -950,10 +989,10 @@ class Repository { return [analysisSet, mergePreference]; } - /// Merges the given commit [oid] into HEAD, writing the results into the working directory. - /// Any changes are staged for commit and any conflicts are written to the index. Callers - /// should inspect the repository's index after this completes, resolve any conflicts and - /// prepare a commit. + /// Merges the given commit [oid] into HEAD, writing the results into the + /// working directory. Any changes are staged for commit and any conflicts + /// are written to the index. Callers should inspect the repository's index + /// after this completes, resolve any conflicts and prepare a commit. /// /// Throws a [LibGit2Error] if error occured. void merge(Oid oid) { @@ -989,22 +1028,25 @@ class Repository { ); } - /// Merges two commits, producing an index that reflects the result of the merge. - /// The index may be written as-is to the working directory or checked out. If the index - /// is to be converted to a tree, the caller should resolve any conflicts that arose as - /// part of the merge. + /// Merges two commits, producing an index that reflects the result of the + /// merge. The index may be written as-is to the working directory or checked + /// out. If the index is to be converted to a tree, the caller should resolve + /// any conflicts that arose as part of the merge. /// /// [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. + /// [favor] is one of the [GitMergeFileFavor] flags for handling conflicting + /// content. Defaults to [GitMergeFileFavor.normal], recording conflict to t + /// he index. /// - /// [mergeFlags] is a combination of [GitMergeFlag] flags. Defaults to [GitMergeFlag.findRenames] - /// enabling the ability to merge between a modified and renamed file. + /// [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]. + /// [fileFlags] is a combination of [GitMergeFileFlag] flags. Defaults to + /// [GitMergeFileFlag.defaults]. /// /// **IMPORTANT**: returned index should be freed to release allocated memory. /// @@ -1026,10 +1068,10 @@ class Repository { )); } - /// Merges two trees, producing an index that reflects the result of the merge. - /// The index may be written as-is to the working directory or checked out. If the index - /// is to be converted to a tree, the caller should resolve any conflicts that arose as part - /// of the merge. + /// Merges two trees, producing an index that reflects the result of the + /// merge. The index may be written as-is to the working directory or checked + /// out. If the index is to be converted to a tree, the caller should resolve + /// any conflicts that arose as part of the merge. /// /// [ancestorTree] is the common ancestor between the trees, or null if none. /// @@ -1037,13 +1079,16 @@ class Repository { /// /// [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. + /// [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. + /// [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]. + /// [fileFlags] is a combination of [GitMergeFileFlag] flags. Defaults to + /// [GitMergeFileFlag.defaults]. /// /// **IMPORTANT**: returned index should be freed to release allocated memory. /// @@ -1067,11 +1112,12 @@ class Repository { )); } - /// Cherry-picks the provided [commit], producing changes in the index and working directory. + /// Cherry-picks the provided [commit], producing changes in the index and + /// working directory. /// - /// Any changes are staged for commit and any conflicts are written to the index. Callers - /// should inspect the repository's index after this completes, resolve any conflicts and - /// prepare a commit. + /// Any changes are staged for commit and any conflicts are written to the + /// index. Callers should inspect the repository's index after this + /// completes, resolve any conflicts and prepare a commit. /// /// Throws a [LibGit2Error] if error occured. void cherryPick(Commit commit) { @@ -1081,7 +1127,8 @@ class Repository { ); } - /// Checkouts the provided reference [refName] using the given strategy, and update the HEAD. + /// Checkouts the provided reference [refName] using the given strategy, and + /// update the HEAD. /// /// If no reference [refName] is given, checkouts from the index. /// @@ -1090,8 +1137,8 @@ class Repository { /// /// [directory] is alternative checkout path to workdir. /// - /// [paths] is list of files to checkout from provided reference [refName]. If paths are provided - /// HEAD will not be set to the reference [refName]. + /// [paths] is list of files to checkout from provided reference [refName]. + /// If paths are provided HEAD will not be set to the reference [refName]. void checkout({ String? refName, Set strategy = const { @@ -1140,12 +1187,13 @@ class Repository { } } - /// Sets the current head to the specified commit [oid] and optionally resets the index - /// and working tree to match. + /// 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. + /// [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. /// @@ -1167,11 +1215,11 @@ class Repository { object_bindings.free(object); } - /// Returns a [Diff] with changes between the trees, tree and index, tree and workdir or - /// index and workdir. + /// Returns a [Diff] with changes between the trees, tree and index, tree and + /// workdir or index and workdir. /// - /// 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. + /// 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]. /// @@ -1268,8 +1316,9 @@ class Repository { return a.diff(newBlob: b, oldAsPath: aPath, newAsPath: bPath); } - /// Applies the [diff] to the repository, making changes in the provided [location] - /// (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({ @@ -1283,8 +1332,8 @@ class Repository { ); } - /// Checks if the [diff] will apply to provided [location] (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, @@ -1306,7 +1355,8 @@ class Repository { /// /// [message] is optional description along with the stashed state. /// - /// [flags] is a combination of [GitStash] flags. Defaults to [GitStash.defaults]. + /// [flags] is a combination of [GitStash] flags. Defaults to + /// [GitStash.defaults]. /// /// Throws a [LibGit2Error] if error occured. Oid createStash({ @@ -1324,19 +1374,20 @@ class Repository { /// Applies a single stashed state from the stash list. /// - /// [index] is the position of the stashed state in the list. Defaults to last saved. + /// [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. + /// [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]. + /// [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. + /// [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({ @@ -1359,8 +1410,8 @@ class Repository { ); } - /// Removes a single stashed state from the stash list at provided [index]. Defaults to - /// the last saved stash. + /// 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}) { @@ -1370,19 +1421,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. + /// [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. + /// [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]. + /// [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. + /// [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({ @@ -1435,7 +1487,8 @@ class Repository { /// Deletes an existing persisted remote with provided [name]. /// - /// All remote-tracking branches and configuration settings for the remote will be removed. + /// 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); @@ -1444,12 +1497,13 @@ class Repository { /// /// Returns list of non-default refspecs that cannot be renamed. /// - /// All remote-tracking branches and configuration settings for the remote are updated. + /// All remote-tracking branches and configuration settings for the remote + /// are updated. /// /// 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. + /// No loaded instances of a the remote with the old name will change their + /// name or their list of refspecs. /// /// Throws a [LibGit2Error] if error occured. List renameRemote({ @@ -1461,8 +1515,9 @@ class Repository { /// 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. + /// 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. Object? getAttribute({ required String path, required String name, @@ -1480,18 +1535,20 @@ class Repository { /// /// [path] is the path to file to consider. /// - /// [flags] is a combination of [GitBlameFlag]s. Defaults to [GitBlameFlag.normal]. + /// [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 - /// it to associate those lines with the parent commit. The default value is 20. - /// This value only takes effect if any of the [GitBlameFlag.trackCopies*] + /// it to associate those lines with the parent commit. The default value is + /// 20. This value only takes effect if any of the [GitBlameFlag.trackCopies*] /// flags are specified. /// - /// [newestCommit] is the id of the newest commit to consider. The default is HEAD. + /// [newestCommit] is the id of the newest commit to consider. The default is + /// HEAD. /// - /// [oldestCommit] is the id of the oldest commit to consider. The default is the - /// first commit encountered with no parent. + /// [oldestCommit] is the id of the oldest commit to consider. The default is + /// the first commit encountered with no parent. /// /// [minLine] is the first line in the file to blame. The default is 1 /// (line numbers start with 1). @@ -1610,10 +1667,11 @@ class Repository { ); } - /// Checks if a provided [commit] is the descendant of another [ancestor] 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`. + /// Note that a commit is not considered a descendant of itself, in contrast + /// to `git merge-base --is-ancestor`. /// /// Throws a [LibGit2Error] if error occured. bool descendantOf({required Oid commit, required Oid ancestor}) { @@ -1624,11 +1682,13 @@ class Repository { ); } - /// Returns list with the `ahead` and `behind` number of unique commits respectively. + /// Returns list with the `ahead` and `behind` number of unique commits + /// respectively. /// - /// 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. + /// 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. /// @@ -1646,28 +1706,29 @@ class Repository { /// 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 - /// only exact matches to be output. Default is 10. + /// [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 only exact matches to be output. + /// Default is 10. /// - /// [describeStrategy] is reference lookup strategy that is one of [GitDescribeStrategy]. - /// Default matches only annotated tags. + /// [describeStrategy] is reference lookup strategy that is one of + /// [GitDescribeStrategy]. Default matches only annotated tags. /// /// [pattern] is pattern to use for tags matching, excluding the "refs/tags/" prefix. /// - /// [onlyFollowFirstParent] checks whether or not to follow only the first parent - /// commit upon seeing a merge commit. + /// [onlyFollowFirstParent] checks whether or not to follow only the first + /// parent commit upon seeing a merge commit. /// - /// [showCommitOidAsFallback] determines if full id of the commit should be shown - /// if no matching tag or reference is found. + /// [showCommitOidAsFallback] determines if full id of the commit should be + /// shown if no matching tag or reference is found. /// - /// [abbreviatedSize] is the minimum number of hexadecimal digits to show for abbreviated - /// object names. A value of 0 will suppress long format, only showing the closest tag. - /// Default is 7. + /// [abbreviatedSize] is the minimum number of hexadecimal digits to show for + /// abbreviated object names. A value of 0 will suppress long format, only + /// showing the closest tag. Default is 7. /// - /// [alwaysUseLongFormat] determines if he long format (the nearest tag, the number of - /// commits, and the abbrevated commit name) should be used even when the commit matches - /// the tag. + /// [alwaysUseLongFormat] determines if he long format (the nearest tag, the + /// number of commits, and the abbrevated commit name) should be used even + /// when the commit matches the tag. /// /// [dirtySuffix] is a string to append if the working tree is dirty. /// @@ -1718,15 +1779,16 @@ 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. /// - /// [packDelegate] is a function that will provide what objects should be added to the - /// pack builder. Default is add all objects. + /// [packDelegate] is a function that will provide what objects should be + /// added to the pack builder. Default is add all objects. /// - /// [threads] is number of threads the PackBuilder will spawn. Default is none. 0 will - /// let libgit2 to autodetect number of CPUs. + /// [threads] is number of threads the PackBuilder will spawn. Default is + /// none. 0 will let libgit2 to autodetect number of CPUs. /// /// Throws a [LibGit2Error] if error occured. int pack({ @@ -1758,7 +1820,8 @@ class Repository { /// List with all tracked submodules paths of a repository. List get submodules => Submodule.list(this); - /// Lookups submodule information by [name] or path (they are usually the same). + /// Lookups submodule information by [name] or path (they are usually the + /// same). /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -1772,8 +1835,8 @@ class Repository { /// Just like `git submodule init`, this copies information about the /// submodule into ".git/config". /// - /// By default, existing entries will not be overwritten, but setting [overwrite] - /// to true forces them to be updated. + /// By default, existing entries will not be overwritten, but setting + /// [overwrite] to true forces them to be updated. /// /// Throws a [LibGit2Error] if error occured. void initSubmodule({ @@ -1784,14 +1847,14 @@ class Repository { } /// Updates a submodule. This will clone a missing submodule and checkout the - /// subrepository to the commit specified in the index of the containing repository. - /// If the submodule repository doesn't contain the target commit (e.g. because - /// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch - /// options supplied in [callbacks]. + /// subrepository to the commit specified in the index of the containing + /// repository. If the submodule repository doesn't contain the target commit + /// (e.g. because fetchRecurseSubmodules isn't set), then the submodule is + /// fetched using the fetch options supplied in [callbacks]. /// - /// If the submodule is not initialized, setting [init] to true will initialize the - /// submodule before updating. Otherwise, this will return an error if attempting - /// to update an uninitialzed repository. + /// If the submodule is not initialized, setting [init] to true will + /// initialize the submodule before updating. Otherwise, this will return an + /// error if attempting to update an uninitialzed repository. /// /// Throws a [LibGit2Error] if error occured. void updateSubmodule({ @@ -1816,7 +1879,8 @@ class Repository { /// [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. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -1852,8 +1916,8 @@ class Repository { /// Creates new worktree. /// - /// If [ref] is provided, no new branch will be created but specified [ref] will - /// be used instead. + /// If [ref] is provided, no new branch will be created but specified [ref] + /// will be used instead. /// /// [name] is the name of the working tree. /// diff --git a/lib/src/revparse.dart b/lib/src/revparse.dart index b15084c..c8d0860 100644 --- a/lib/src/revparse.dart +++ b/lib/src/revparse.dart @@ -4,16 +4,18 @@ import 'bindings/libgit2_bindings.dart'; import 'bindings/revparse.dart' as bindings; class RevParse { - /// Finds a single object and intermediate reference (if there is one) by a [spec] revision string. + /// Finds a single object and intermediate reference (if there is one) by a + /// [spec] revision string. /// /// See `man gitrevisions`, or https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions /// for information on the syntax accepted. /// - /// In some cases (@{<-n>} or @{upstream}), the expression may point to an - /// intermediate reference. When such expressions are being passed in, reference_out will be - /// valued as well. + /// In some cases (@{<-n>} or @{upstream}), the expression may + /// point to an intermediate reference. When such expressions are being + /// passed in, reference_out will be valued as well. /// - /// **IMPORTANT**: The returned object and reference should be freed to release allocated memory. + /// **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}) { diff --git a/lib/src/revwalk.dart b/lib/src/revwalk.dart index 07ddf97..73684b9 100644 --- a/lib/src/revwalk.dart +++ b/lib/src/revwalk.dart @@ -39,10 +39,11 @@ class RevWalk { /// Adds a new root commit [oid] for the traversal. /// - /// The pushed commit will be marked as one of the roots from which to start the walk. - /// This commit may not be walked if it or a child is hidden. + /// The pushed commit will be marked as one of the roots from which to start + /// the walk. This commit may not be walked if it or a child is hidden. /// - /// At least one commit must be pushed onto the walker before a walk can be started. + /// At least one commit must be pushed onto the walker before a walk can be + /// started. /// /// The given [oid] must belong to a committish on the walked repository. /// @@ -58,7 +59,8 @@ class RevWalk { /// /// The given id must belong to a committish on the walked repository. /// - /// The resolved commit and all its parents will be hidden from the output on the revision walk. + /// The resolved commit and all its parents will be hidden from the output on + /// the revision walk. /// /// Throws a [LibGit2Error] if error occured. void hide(Oid oid) { @@ -70,8 +72,9 @@ class RevWalk { /// Resets the revision walker for reuse. /// - /// This will clear all the pushed and hidden commits, and leave the walker in a blank state - /// (just like at creation) ready to receive new commit pushes and start a new walk. + /// This will clear all the pushed and hidden commits, and leave the walker + /// in a blank state (just like at creation) ready to receive new commit + /// pushes and start a new walk. /// /// The revision walk is automatically reset when a walk is over. void reset() => bindings.reset(_revWalkPointer); diff --git a/lib/src/signature.dart b/lib/src/signature.dart index 10a64ed..cd316d1 100644 --- a/lib/src/signature.dart +++ b/lib/src/signature.dart @@ -15,7 +15,8 @@ class Signature { /// 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'. + /// If [time] isn't provided [Signature] will be created with a timestamp of + /// 'now'. /// /// **IMPORTANT**: Should be freed to release allocated memory. Signature.create({ @@ -45,8 +46,9 @@ class Signature { /// 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 - /// current time as the timestamp, and creates a new signature based on that information. + /// 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. static Signature defaultSignature(Repository repo) => Signature(bindings.defaultSignature(repo.pointer)); @@ -82,6 +84,7 @@ class Signature { @override String toString() { - return 'Signature{name: $name, email: $email, time: $time, offset: $offset}'; + return 'Signature{name: $name, email: $email, time: $time, ' + 'offset: $offset}'; } } diff --git a/lib/src/stash.dart b/lib/src/stash.dart index 4b92c0c..ab24459 100644 --- a/lib/src/stash.dart +++ b/lib/src/stash.dart @@ -2,8 +2,8 @@ import 'package:libgit2dart/libgit2dart.dart'; import 'bindings/stash.dart' as bindings; class Stash { - /// Initializes a new instance of [Stash] class from provided stash [index], [message] - /// and [oid]. + /// Initializes a new instance of [Stash] class from provided stash [index], + /// [message] and [oid]. const Stash({ required this.index, required this.message, @@ -30,7 +30,8 @@ class Stash { /// /// [message] is optional description along with the stashed state. /// - /// [flags] is a combination of [GitStash] flags. Defaults to [GitStash.defaults]. + /// [flags] is a combination of [GitStash] flags. Defaults to + /// [GitStash.defaults]. /// /// Throws a [LibGit2Error] if error occured. static Oid create({ @@ -51,19 +52,20 @@ class Stash { /// Applies a single stashed state from the stash list. /// - /// [index] is the position of the stashed state in the list. Defaults to last saved. + /// [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. + /// [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]. + /// [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. + /// [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({ @@ -87,8 +89,8 @@ class Stash { ); } - /// Removes a single stashed state from the stash list at provided [index]. Defaults to - /// the last saved stash. + /// 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}) { @@ -101,19 +103,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. + /// [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. + /// [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]. + /// [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. + /// [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({ diff --git a/lib/src/submodule.dart b/lib/src/submodule.dart index ab6d45d..597fc7b 100644 --- a/lib/src/submodule.dart +++ b/lib/src/submodule.dart @@ -4,7 +4,8 @@ import 'bindings/libgit2_bindings.dart'; import 'bindings/submodule.dart' as bindings; class Submodule { - /// Lookups submodule information by [name] or path (they are usually the same). + /// Lookups submodule information by [name] or path (they are usually the + /// same). /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -25,7 +26,8 @@ class Submodule { /// [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. + /// [callbacks] is the combination of callback functions from [Callbacks] + /// object. /// /// **IMPORTANT**: Should be freed to release allocated memory. /// @@ -57,8 +59,8 @@ class Submodule { /// Just like `git submodule init`, this copies information about the /// submodule into ".git/config". /// - /// By default, existing entries will not be overwritten, but setting [overwrite] - /// to true forces them to be updated. + /// By default, existing entries will not be overwritten, but setting + /// [overwrite] to true forces them to be updated. /// /// Throws a [LibGit2Error] if error occured. static void init({ @@ -77,14 +79,14 @@ class Submodule { } /// Updates a submodule. This will clone a missing submodule and checkout the - /// subrepository to the commit specified in the index of the containing repository. - /// If the submodule repository doesn't contain the target commit (e.g. because - /// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch - /// options supplied in [callbacks]. + /// subrepository to the commit specified in the index of the containing + /// repository. If the submodule repository doesn't contain the target commit + /// (e.g. because fetchRecurseSubmodules isn't set), then the submodule is + /// fetched using the fetch options supplied in [callbacks]. /// - /// If the submodule is not initialized, setting [init] to true will initialize the - /// submodule before updating. Otherwise, this will return an error if attempting - /// to update an uninitialzed repository. + /// If the submodule is not initialized, setting [init] to true will + /// initialize the submodule before updating. Otherwise, this will return an + /// error if attempting to update an uninitialzed repository. /// /// Throws a [LibGit2Error] if error occured. static void update({ @@ -112,11 +114,14 @@ class Submodule { /// Opens the repository for a submodule. /// - /// 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. + /// 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. + /// **IMPORTANT**: Returned [Repository] object should be freed to release + /// allocated memory. /// /// Throws a [LibGit2Error] if error occured. Repository open() { @@ -125,9 +130,9 @@ class Submodule { /// Returns the status for a submodule. /// - /// This looks at a submodule and tries to determine the status. How deeply it examines - /// the working directory to do this will depend on the combination of [GitSubmoduleIgnore] - /// values provided to [ignore] . + /// This looks at a submodule and tries to determine the status. How deeply + /// it examines the working directory to do this will depend on the + /// combination of [GitSubmoduleIgnore] values provided to [ignore] . Set status({ GitSubmoduleIgnore ignore = GitSubmoduleIgnore.unspecified, }) { @@ -144,16 +149,16 @@ class Submodule { /// Copies submodule remote info into submodule repo. /// - /// This copies the information about the submodules URL into the checked out submodule - /// config, acting like `git submodule sync`. This is useful if you have altered the URL - /// for the submodule (or it has been altered by a fetch of upstream changes) and you - /// need to update your local repo. + /// This copies the information about the submodules URL into the checked out + /// submodule config, acting like `git submodule sync`. This is useful if you + /// have altered the URL for the submodule (or it has been altered by a fetch + /// of upstream changes) and you need to update your local repo. void sync() => bindings.sync(_submodulePointer); /// Rereads submodule info from config, index, and HEAD. /// - /// Call this to reread cached submodule information for this submodule if you have - /// reason to believe that it has changed. + /// Call this to reread cached submodule information for this submodule if + /// you have reason to believe that it has changed. /// /// Set [force] to true to reload even if the data doesn't seem out of date. void reload({bool force = false}) { @@ -199,26 +204,27 @@ class Submodule { ); } - /// [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); } - /// [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); } - /// [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 - /// won't notice that. You should call [status] for a more complete picture about - /// the state of the working directory. + /// 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 won't notice that. You should call [status] for a + /// more complete picture about the state of the working directory. Oid? get workdirOid { final result = bindings.workdirId(_submodulePointer); return result == null ? null : Oid(result); @@ -263,7 +269,7 @@ class Submodule { @override String toString() { return 'Submodule{name: $name, path: $path, url: $url, status: $status, ' - 'branch: $branch, headOid: $headOid, indexOid: $indexOid, workdirOid: $workdirOid, ' - 'ignore: $ignore, updateRule: $updateRule}'; + 'branch: $branch, headOid: $headOid, indexOid: $indexOid, ' + 'workdirOid: $workdirOid, ignore: $ignore, updateRule: $updateRule}'; } } diff --git a/lib/src/tag.dart b/lib/src/tag.dart index 8f235b5..143f7a5 100644 --- a/lib/src/tag.dart +++ b/lib/src/tag.dart @@ -28,8 +28,9 @@ class Tag { /// Creates a new tag in the repository for provided [target] object. /// - /// A new reference will also be created pointing to this tag object. If [force] is true - /// and a reference already exists with the given name, it'll be replaced. + /// A new reference will also be created pointing to this tag object. If + /// [force] is true and a reference already exists with the given name, it'll + /// be replaced. /// /// The [message] will not be cleaned up. /// @@ -39,18 +40,23 @@ class Tag { /// /// [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. + /// [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]. + /// [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. + /// [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. + /// [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. + /// [force] determines whether existing reference with the same [tagName] + /// should be replaced. /// /// Throws a [LibGit2Error] if error occured. static Oid create({ @@ -100,9 +106,14 @@ class Tag { /// Tagged object (commit, tree, blob, tag) of a tag. /// - /// This method performs a repository lookup for the given object and returns it. + /// This method performs a repository lookup for the given object and returns + /// it. /// - /// Returned object should be explicitly downcasted to one of four of git object types. + /// Returned object should be explicitly downcasted to one of four of git + /// object types. + /// + /// **IMPORTANT**: returned object should be freed to release allocated + /// memory. /// /// ```dart /// final commit = tag.target as Commit; @@ -151,6 +162,7 @@ class Tag { @override String toString() { - return 'Tag{oid: $oid, name: $name, message: $message, target: $target, tagger: $tagger}'; + return 'Tag{oid: $oid, name: $name, message: $message, target: $target, ' + 'tagger: $tagger}'; } } diff --git a/lib/src/tree.dart b/lib/src/tree.dart index efc2af9..b80e9ad 100644 --- a/lib/src/tree.dart +++ b/lib/src/tree.dart @@ -44,7 +44,8 @@ class Tree { /// Lookups a tree entry in the tree. /// - /// If integer [value] is provided, lookup is done by entry position in the tree. + /// If integer [value] is provided, lookup is done by entry position in the + /// tree. /// /// If string [value] is provided, lookup is done by entry filename. /// diff --git a/lib/src/treebuilder.dart b/lib/src/treebuilder.dart index f957cba..19e3784 100644 --- a/lib/src/treebuilder.dart +++ b/lib/src/treebuilder.dart @@ -44,8 +44,8 @@ class TreeBuilder { /// Adds or updates an entry to the tree builder with the given attributes. /// - /// If an entry with [filename] already exists, its attributes will be updated with - /// the given ones. + /// 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. diff --git a/lib/src/worktree.dart b/lib/src/worktree.dart index f6c26dd..c8b67d5 100644 --- a/lib/src/worktree.dart +++ b/lib/src/worktree.dart @@ -6,8 +6,8 @@ import 'bindings/worktree.dart' as bindings; class Worktree { /// Creates new worktree. /// - /// If [ref] is provided, no new branch will be created but specified [ref] will - /// be used instead. + /// If [ref] is provided, no new branch will be created but specified [ref] + /// will be used instead. /// /// [repo] is the repository to create working tree for. /// @@ -57,8 +57,8 @@ class Worktree { /// Whether worktree is locked. /// - /// A worktree may be locked if the linked working tree is stored on a portable - /// device which is not available. + /// A worktree may be locked if the linked working tree is stored on a + /// portable device which is not available. bool get isLocked => bindings.isLocked(_worktreePointer); /// Locks worktree if not already locked. @@ -83,8 +83,8 @@ class Worktree { /// 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. + /// A valid worktree requires both the git data structures inside the linked + /// parent repository and the linked working copy to be present. bool get isValid => bindings.isValid(_worktreePointer); /// Releases memory allocated for worktree object. diff --git a/test/blame_test.dart b/test/blame_test.dart index 4ebd9e3..4c270f7 100644 --- a/test/blame_test.dart +++ b/test/blame_test.dart @@ -98,8 +98,8 @@ void main() { }); test( - 'successfully gets the blame for provided file with minMatchCharacters set', - () { + 'successfully gets the blame for provided file with ' + 'minMatchCharacters set', () { final blame = repo.blame( path: 'feature_file', minMatchCharacters: 1, @@ -165,8 +165,8 @@ void main() { }); test( - 'successfully gets the blame for provided file with newestCommit argument', - () { + 'successfully gets the blame for provided file with ' + 'newestCommit argument', () { final blame = repo.blame( path: 'feature_file', newestCommit: repo['fc38877'], @@ -194,8 +194,8 @@ void main() { }); test( - 'successfully gets the blame for provided file with minLine and maxLine set', - () { + 'successfully gets the blame for provided file with minLine and ' + 'maxLine set', () { final blame = repo.blame( path: 'feature_file', minLine: 1, diff --git a/test/checkout_test.dart b/test/checkout_test.dart index 8d46d56..5aaa3ff 100644 --- a/test/checkout_test.dart +++ b/test/checkout_test.dart @@ -34,8 +34,8 @@ void main() { }); test( - 'throws when trying to checkout head with invalid alternative directory', - () { + 'throws when trying to checkout head with invalid alternative ' + 'directory', () { expect( () => repo.checkout( refName: 'HEAD', @@ -66,8 +66,8 @@ void main() { }); test( - 'throws when trying to checkout index with invalid alternative directory', - () { + 'throws when trying to checkout index with invalid alternative ' + 'directory', () { expect( () => repo.checkout(directory: 'not/there'), throwsA( @@ -111,8 +111,8 @@ void main() { }); test( - 'throws when trying to checkout tree with invalid alternative directory', - () { + 'throws when trying to checkout tree with invalid alternative ' + 'directory', () { expect( () => repo.checkout( refName: 'refs/heads/feature', diff --git a/test/config_test.dart b/test/config_test.dart index e1478f5..2fd424a 100644 --- a/test/config_test.dart +++ b/test/config_test.dart @@ -42,8 +42,8 @@ void main() { }); test( - 'opens the global, XDG and system configuration files (if they are present) ' - 'if no path provided', () { + 'opens the global, XDG and system configuration files ' + '(if they are present) if no path provided', () { try { final config = Config.open(); expect(config, isA()); diff --git a/test/credentials_test.dart b/test/credentials_test.dart index a9ff2f7..70b4938 100644 --- a/test/credentials_test.dart +++ b/test/credentials_test.dart @@ -153,7 +153,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "Failed to authenticate SSH session: Unable to open public key file", + 'Failed to authenticate SSH session: Unable to open public key ' + 'file', ), ), ); diff --git a/test/describe_test.dart b/test/describe_test.dart index 9a97fe2..7b210f3 100644 --- a/test/describe_test.dart +++ b/test/describe_test.dart @@ -56,7 +56,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "cannot describe - no tags can describe 'f17d0d48eae3aa08cecf29128a35e310c97b3521'.", + "cannot describe - no tags can describe " + "'f17d0d48eae3aa08cecf29128a35e310c97b3521'.", ), ), ); diff --git a/test/index_test.dart b/test/index_test.dart index 519f2e1..f620462 100644 --- a/test/index_test.dart +++ b/test/index_test.dart @@ -112,7 +112,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "could not find '${repo.workdir}not_there' to stat: No such file or directory", + "could not find '${repo.workdir}not_there' to stat: No such file " + "or directory", ), ), ); @@ -141,7 +142,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "cannot create blob from file. This operation is not allowed against bare repositories.", + "cannot create blob from file. This operation is not allowed " + "against bare repositories.", ), ), ); @@ -184,7 +186,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "cannot index add all. This operation is not allowed against bare repositories.", + "cannot index add all. This operation is not allowed against " + "bare repositories.", ), ), ); diff --git a/test/rebase_test.dart b/test/rebase_test.dart index 2d2a703..79a1367 100644 --- a/test/rebase_test.dart +++ b/test/rebase_test.dart @@ -148,8 +148,8 @@ void main() { }); test( - 'throws when trying to initialize rebase without upstream and onto provided', - () { + 'throws when trying to initialize rebase without upstream and onto ' + 'provided', () { expect( () => Rebase.init(repo: repo), throwsA( @@ -218,7 +218,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "object not found - failed to find pack entry (790b86f5fb50db485586370f27c5f90bada97d83)", + "object not found - failed to find pack entry " + "(790b86f5fb50db485586370f27c5f90bada97d83)", ), ), ); diff --git a/test/reference_test.dart b/test/reference_test.dart index 6736322..81206e4 100644 --- a/test/reference_test.dart +++ b/test/reference_test.dart @@ -201,7 +201,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - 'Invalid argument: "0 must be either Oid or String reference name"', + 'Invalid argument: "0 must be either Oid or String reference ' + 'name"', ), ), ); @@ -462,7 +463,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - 'Invalid argument: "0 must be either Oid or String reference name"', + 'Invalid argument: "0 must be either Oid or String reference ' + 'name"', ), ), ); diff --git a/test/remote_test.dart b/test/remote_test.dart index c2871e5..16b97d8 100644 --- a/test/remote_test.dart +++ b/test/remote_test.dart @@ -337,8 +337,8 @@ void main() { }); test( - 'throws when trying to get remote repo\'s reference list with invalid url', - () { + 'throws when trying to get remote repo\'s reference list with ' + 'invalid url', () { Remote.setUrl(repo: repo, remote: 'libgit2', url: 'invalid'); final remote = repo.lookupRemote('libgit2'); @@ -455,7 +455,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "failed to resolve address for wrong.url: Name or service not known", + "failed to resolve address for wrong.url: Name or service " + "not known", ), ), ); @@ -604,7 +605,8 @@ Total 69 (delta 0), reused 1 (delta 0), pack-reused 68 isA().having( (e) => e.toString(), 'error', - "failed to resolve address for wrong.url: Name or service not known", + "failed to resolve address for wrong.url: Name or service " + "not known", ), ), ); diff --git a/test/repository_test.dart b/test/repository_test.dart index 6a07dd5..b738d7b 100644 --- a/test/repository_test.dart +++ b/test/repository_test.dart @@ -183,7 +183,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - 'Invalid argument: "0 must be either Oid or String reference name"', + 'Invalid argument: "0 must be either Oid or String reference ' + 'name"', ), ), ); @@ -305,7 +306,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - "cannot status. This operation is not allowed against bare repositories.", + "cannot status. This operation is not allowed against bare " + "repositories.", ), ), ); diff --git a/test/revparse_test.dart b/test/revparse_test.dart index 1b9c5eb..c148be8 100644 --- a/test/revparse_test.dart +++ b/test/revparse_test.dart @@ -119,8 +119,8 @@ void main() { }); test( - '.range returns revspec with correct fields values based on provided spec', - () { + '.range returns revspec with correct fields values based on ' + 'provided spec', () { var revspec = repo.revParse('master'); expect(revspec.from.oid.sha, headSHA); @@ -165,12 +165,12 @@ void main() { ), ); expect( - () => repo.revParse('master........5aecfa'), + () => repo.revParse('master.......5aecfa'), throwsA( isA().having( (e) => e.toString(), 'error', - "failed to parse revision specifier - Invalid pattern '.....5aecfa'", + "failed to parse revision specifier - Invalid pattern '....5aecfa'", ), ), ); diff --git a/test/signature_test.dart b/test/signature_test.dart index 4578f00..bc7e9e4 100644 --- a/test/signature_test.dart +++ b/test/signature_test.dart @@ -32,22 +32,24 @@ void main() { isA().having( (e) => e.toString(), 'error', - "failed to parse signature - Signature cannot have an empty name or email", + "failed to parse signature - Signature cannot have an empty name " + "or email", ), ), ); }); test( - 'throws when trying to create with empty name and email and default time', - () { + 'throws when trying to create with empty name and email and ' + 'default time', () { expect( () => Signature.create(name: '', email: ''), throwsA( isA().having( (e) => e.toString(), 'error', - "failed to parse signature - Signature cannot have an empty name or email", + "failed to parse signature - Signature cannot have an empty name " + "or email", ), ), ); diff --git a/test/submodule_test.dart b/test/submodule_test.dart index 6aec63f..10ebebe 100644 --- a/test/submodule_test.dart +++ b/test/submodule_test.dart @@ -153,7 +153,8 @@ void main() { isA().having( (e) => e.toString(), 'error', - 'failed to resolve address for wrong.url: Name or service not known', + 'failed to resolve address for wrong.url: Name or service ' + 'not known', ), ), ); diff --git a/test/worktree_test.dart b/test/worktree_test.dart index 27b8308..0a2b84c 100644 --- a/test/worktree_test.dart +++ b/test/worktree_test.dart @@ -53,8 +53,8 @@ void main() { }); test( - 'successfully creates worktree at provided path from provided reference', - () { + 'successfully creates worktree at provided path from ' + 'provided reference', () { final head = repo.revParseSingle('HEAD'); final worktreeBranch = repo.createBranch(name: 'v1', target: head); final ref = repo.lookupReference('refs/heads/v1');