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

style: avoid lines longer than 80 characters

Browse source
This commit is contained in:
Aleksey Kulikov 2021-10-22 17:13:42 +03:00
parent a806d0a312
commit 7b14ee6b9b
76 changed files with 1246 additions and 972 deletions
Download patch file Download diff file Expand all files Collapse all files

532
lib/src/repository.dart
View file

@ -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<git_repository> 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<Commit> 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 <branchname>@{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 <branchname>@{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<GitStatus> 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<GitCheckout> 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<String> 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<String> 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.
///