Class LocalRepoApi

Implements easy-to-use local git repository related APIs.

Inheritance

object

LocalRepoApi

Namespace: Neon.GitHub

Assembly: Neon.GitHub.dll

Syntax

public class LocalRepoApi

Properties

CurrentBranch

Returns the current branch.

Declaration

public Branch CurrentBranch { get; }

Property Value

Type	Description
Branch

Folder

Returns the path to the local repository folder.

Declaration

public string Folder { get; }

Property Value

Type	Description
string

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

IsDirty

Returns true when the local repos has uncommitted changes.

Declaration

public bool IsDirty { get; }

Property Value

Type	Description
bool

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

Methods

AnnotatedTagExistsAsync(string)

Determines whether a specific annotated tag exists.

Declaration

public Task<bool> AnnotatedTagExistsAsync(string tagName)

Parameters

Type	Name	Description
string	tagName	Specfies the target tag's friendly name.

Returns

Type	Description
Task<bool>	true when the annotated tag exists.

ApplyAnnotatedTagAsync(string, Branch, string, bool)

Creates an annotated tag from the HEAD commit for the specified or current local branch, optionally pushing the new tag to GitHub.

Declaration

public Task<Tag> ApplyAnnotatedTagAsync(string tagName, Branch branch = null, string message = null, bool push = false)

Parameters

Type	Name	Description
string	tagName	The new tag name.
Branch	branch	Optionally specifies the source branch, overriding the current branch default.
string	message	Optional tag commit message.
bool	push	Optionally push the tag to GitHub.

Returns

Type	Description
Task<Tag>	The new LibGit2Sharp.Tag.

BranchExistsAsync(string)

Determines whether a specific branch exists by friendly name.

Declaration

public Task<bool> BranchExistsAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specfies the friendly name of the target branch.

Returns

Type	Description
Task<bool>	true when the branch exists.

CheckoutAsync(string)

Checks out a local repository branch.

Declaration

public Task CheckoutAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specifies the local branch to be checked out.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

CheckoutOriginAsync(string, string, bool)

Creates a local branch from a named GitHub repository origin branch and then checks out the branch. By default, the local branch will have the same name as the origin, but this can be customized.

Declaration

public Task<bool> CheckoutOriginAsync(string originBranchName, string localBranchName = null, bool detached = false)

Parameters

Type	Name	Description
string	originBranchName	Specifies the GitHub origin repository branch name.
string	localBranchName	Optionally specifies the local branch name. This defaults to originBranchName.
bool	detached	Optionally detach the local branch from the remote. This means you won't be able to push changes back to the remote but this is useful for situations where you just need the current snapshot of a remote branch rather than the entire branch history (i.e. for a build).

Returns

Type	Description
Task<bool>	true if the local branch didn't already exist and was created from the GitHub origin repository, false if it already existed.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

CherryPickAsync(string, IEnumerable<Commit>)

Cherry-picks commits from a target branch and adds them to the current branch.

Declaration

public Task CherryPickAsync(string sourceBranchName, IEnumerable<Commit> commits)

Parameters

Type	Name	Description
string	sourceBranchName	Specifies the friendly name of the local source branch.
IEnumerable<Commit>	commits	Specifies the commits to be cherry-picked from the source branch and added to the target. The commits will be applied in the order they appear here.

Returns

Type	Description
Task	The tracking Task.

Remarks

Before applying the commits from the source branch, this method verifies that the source branch actually includes all of the specifies commits and the current branch includes none of these commits.

Cherry-picking will stop if one of the operations fails due to a conflict.

Exceptions

Type	Condition
LibGit2SharpException	Thrown when the source branch doesn't include any of the commits, the target branch already includes one or more, or when there was a conflict cherry-picking a commit.

CommitAsync(string, bool)

Commits any staged and non-staged changes to the local git repository by default. You can also just commit staged changes by passing autoStage=false.

Declaration

public Task<Commit> CommitAsync(string message = null, bool autoStage = true)

Parameters

Type	Name	Description
string	message	Optionally specifies the commit message. This defaults to unspecified changes".
bool	autoStage	Optionally disable automatic staging of new and changed files. This defaults to true.

Returns

Type	Description
Task<Commit>	The new LibGit2Sharp.Commit when changes were committed, null when there were no pending changes.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

CreateBranchAsync(string, string)

Creates a new local branch from the tip of a source branch if the new branch doesn't already exist and then checks out the new branch.

Declaration

public Task<bool> CreateBranchAsync(string branchName, string sourceBranchName)

Parameters

Type	Name	Description
string	branchName	Identifies the branch to being created.
string	sourceBranchName	Identifies the source branch.

Returns

Type	Description
Task<bool>	true if the branch didn't already exist and was created, false if it already existed.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

CreatePushOptions()

Returns a LibGit2Sharp.PushOptions instance initialized with the credentials provider.

Declaration

public PushOptions CreatePushOptions()

Returns

Type	Description
PushOptions	The new LibGit2Sharp.PushOptions.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
LibGit2SharpException	Thrown when the operation fails.

CreateSignature()

Creates a LibGit2Sharp.Signature from the repository's credentials.

Declaration

public Signature CreateSignature()

Returns

Type	Description
Signature	The new LibGit2Sharp.Signature.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.

FetchAsync()

Fetches information from the associated GitHub origin repository.

Declaration

public Task FetchAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

FindAnnotatedTagAsync(string)

Attempts to retrieve an annotated tag by friendly name.

Declaration

public Task<Tag> FindAnnotatedTagAsync(string tagName)

Parameters

Type	Name	Description
string	tagName	Specifies target tag's friendly name.

Returns

Type	Description
Task<Tag>	The annotated LibGit2Sharp.Tag if it exists, null otherwise.

FindBranchAsync(string)

Attempts to retrieve a branch by friendly name.

Declaration

public Task<Branch> FindBranchAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specifies the friendly name of the target branch.

Returns

Type	Description
Task<Branch>	The LibGit2Sharp.Branch if it exists, null otherwise.

GetAnnotatedTagAsync(string)

Returns an annotated tag by friendly name.

Declaration

public Task<Tag> GetAnnotatedTagAsync(string tagName)

Parameters

Type	Name	Description
string	tagName	Specifies target tag's friendly name.

Returns

Type	Description
Task<Tag>	The annotated LibGit2Sharp.Tag.

Exceptions

Type	Condition
NotFoundException	Thrown if the annotated tag doesn't exist.

GetBranchAsync(string)

Returns the branch by friendly name

Declaration

public Task<Branch> GetBranchAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specifies the friendly name of the target branch.

Returns

Type	Description
Task<Branch>	The LibGit2Sharp.Branch.

Exceptions

Type	Condition
NotFoundException	Thrown if the branch doesn't exist.

GetBranchCommitsAsync(string)

Returns the commits for a local branch by friendly name.

Declaration

public Task<IEnumerable<Commit>> GetBranchCommitsAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specifies the friendly name of the target branch.

Returns

Type	Description
Task<IEnumerable<Commit>>	The commits.

Exceptions

Type	Condition
NotFoundException	Thrown if the branch doesn't exist.

GetCommitsAsync()

Returns the local commits in decending order by commit date/time.

Declaration

public Task<IEnumerable<Commit>> GetCommitsAsync()

Returns

Type	Description
Task<IEnumerable<Commit>>	The local commits in decending order by commit date/time.

GetLocalFilePathAsync(string)

Converts a relative local repository file path like "/my-folder/test.txt" or "my-folder/test.txt into the actual local file system path for the file.

note

The local file doesn't need to actually exist.

Declaration

public Task<string> GetLocalFilePathAsync(string relativePath)

Parameters

Type	Name	Description
string	relativePath	Specifies the path to the file relative to the local repository root folder. This may include a leading slash and both forward and backslashes are allowed as path separators.

Returns

Type	Description
Task<string>	The fully qualified file system path to the specified repo file.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

GetRemoteFileUriAsync(string, bool)

Converts a relative local repository file path like "/my-folder/test.txt" or "my-folder/test.txt to the remote GitHub URI for the file within the the currently checked out branch.

note

The local or remote file doesn't need to actually exist.

Declaration

public Task<string> GetRemoteFileUriAsync(string relativePath, bool raw = false)

Parameters

Type	Name	Description
string	relativePath	Specifies the path to the file relative to the local repository root folder. This may include a leading slash (which is assumed when not present) and both forward and backslashes are allowed as path separators.
bool	raw	Optionally returns the link to the raw file bytes as opposed to the URL for the GitHub HTML page for the file.

Returns

Type	Description
Task<string>	The GitHub URI for the file from the current branch.

Remarks

note

This method does not ensure that the target file actually exists in the repo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

IsAheadAsync()

Determines whether the local repo is ahead of the remote banch.

Declaration

public Task<bool> IsAheadAsync()

Returns

Type	Description
Task<bool>	true when the local repo is ahead of the remote branch.

IsBehindAsync()

Determines whether the local repo is behind the remote banch.

Declaration

public Task<bool> IsBehindAsync()

Returns

Type	Description
Task<bool>	true when the local repo is behind the remote branch.

IsPathIgnoredAsync(string)

Determines whether the file system path will be ignored by Git due to the repo's current .gitignore file state. Note that the path does not need to exist within the repo.

Declaration

public Task<bool> IsPathIgnoredAsync(string path)

Parameters

Type	Name	Description
string	path	Specifies the relative file path (relative to the local repo root directory) to be tested. note You may use either forward or back slashes in the path as directory separators.

Returns

Type	Description
Task<bool>	true when the path will be ignored.

ListAllTagsAsync()

Lists all tags (lightweight and annotated) from the local repo.

note

You can use the LibGit2Sharp.Tag.IsAnnotated property to distinguish between annotated and lightweight tags.

Declaration

public Task<IEnumerable<Tag>> ListAllTagsAsync()

Returns

Type	Description
Task<IEnumerable<Tag>>	The tags.

ListAnnotatedTagsAsync()

Lists the annotated tags from the local repo.

Declaration

public Task<IEnumerable<Tag>> ListAnnotatedTagsAsync()

Returns

Type	Description
Task<IEnumerable<Tag>>	The annotated tag names.

ListBranchesAsync()

Enumerates the friendly names of the local branches.

Declaration

public Task<IEnumerable<Branch>> ListBranchesAsync()

Returns

Type	Description
Task<IEnumerable<Branch>>	The LibGit2Sharp.Branch instances.

ListLightweightTagsAsync()

Lists the lightweight tags from the local repo.

Declaration

public Task<IEnumerable<Tag>> ListLightweightTagsAsync()

Returns

Type	Description
Task<IEnumerable<Tag>>	The tags.

MergeAsync(string, bool)

Merges another local branch into the current branch.

note

The checked out branch must not included an non-committed changes.

Declaration

public Task<MergeResult> MergeAsync(string branchName, bool throwOnConflict = true)

Parameters

Type	Name	Description
string	branchName	Identifies the branch to be merged into the current branch.
bool	throwOnConflict	Optionally specifies that the method should not throw an exception for conflicts.

Returns

Type	Description
Task<MergeResult>	A LibGit2Sharp.MergeResult for successful merges or when the merged failed and throwOnConflict is false.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

PullAsync()

Fetches and pulls the changes from GitHub into the current checked-out branch within a local git repository.

note

The pull operation will be aborted and rolled back for merge conflicts. Check the result status to understand what happened.

Declaration

public Task<MergeStatus> PullAsync()

Returns

Type	Description
Task<MergeStatus>	The LibGit2Sharp.MergeStatus for the operation.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

PushAsync()

Pushes any pending local commits from the checked out branch to GitHub, creating the branch on GitHub and associating the local branch when the branch doesn't already exist on GitHub. Any GitHub origin repository branch created will have the same name as the local branch.

Declaration

public Task<bool> PushAsync()

Returns

Type	Description
Task<bool>	true when commits were pushed, false when there were no pending commits.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

PushTagAsync(Tag)

Pushes a local annotated tag to GitHub.

Declaration

public Task PushTagAsync(Tag tag)

Parameters

Type	Name	Description
Tag	tag	Specifies the tag being pushed.

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
InvalidOperationException	Thrown for non-anotated tags.

RemoveBranchAsync(string)

Removes a branch from the local repository if it exists.

Declaration

public Task RemoveBranchAsync(string branchName)

Parameters

Type	Name	Description
string	branchName	Specifies the branch to be removed.

Returns

Type	Description
Task	true if the branch existed and was removed, false otherwise.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

ResetAsync(ResetMode)

Resets the current repo branch to match the HEAD commit using the resetMode.

Declaration

public Task ResetAsync(ResetMode resetMode)

Parameters

Type	Name	Description
ResetMode	resetMode	Specifies the reset mode

Returns

Type	Description
Task	The tracking Task.

Remarks

This method is used to undo uncommitted changes to the local repository. This may impact the repo's working directory and staging index, depending on the resetMode passed.

LibGit2Sharp.ResetMode.Hard	Resets the working directory and staging index to match the current branch's HEAD commit. This effectively undoes all repo changes with any pending changes being lost. note Untracked files in the working directory are not impacted.
LibGit2Sharp.ResetMode.Mixed	Unstages any changes by moving them back to the working directory with any other changes to the working directory being left alone.
LibGit2Sharp.ResetMode.Soft	This mode doesn't make sense when working with the HEAD commit and does nothing.

See this for more details:

ResetAsync(ResetMode, Commit, CheckoutOptions)

Changes current branch HEAD commit to the specified commit and then applies any changes from this commit as specified by resetMode.

Declaration

public Task ResetAsync(ResetMode resetMode, Commit commit, CheckoutOptions options = null)

Parameters

Type	Name	Description
ResetMode	resetMode	Specifies the reset mode
Commit	commit	Specifies the target commit.
CheckoutOptions	options	Optionally specifies checkout options.

Returns

Type	Description
Task	The tracking Task.

Remarks

This method is used to undo uncommitted changes to the local repository. This may impact the repo's working directory and staging index, depending on the resetMode passed.

LibGit2Sharp.ResetMode.Hard	Moves the current branch HEAD to the specified commit and resets the working directory and staging index to match this commit. This effectively undoes changes to staged and tracked files. note Untracked files in the working directory are not impacted.
LibGit2Sharp.ResetMode.Mixed	Moves the current branch HEAD to the specified commit, applying any staged changes back to the working directory. No other modifications will be made to the working directory.
LibGit2Sharp.ResetMode.Soft	Moves the current branch HEAD to the specified commit. The working directory and any staged files will remain unchanged.

See this for more details:

RetrieveStatusAsync(StatusOptions)

Returns the status of a working file by comparing it against any staged file and the current commit.

Declaration

public Task<RepositoryStatus> RetrieveStatusAsync(StatusOptions options = null)

Parameters

Type	Name	Description
StatusOptions	options	Optionally specifies status retrieval options.

Returns

Type	Description
Task<RepositoryStatus>	The LibGit2Sharp.RepositoryStatus.

RetrieveStatusAsync(string)

Returns the status of a working file by comparing it against any staged file and the current commit.

Declaration

public Task<FileStatus> RetrieveStatusAsync(string path)

Parameters

Type	Name	Description
string	path	Path to the working file.

Returns

Type	Description
Task<FileStatus>	The LibGit2Sharp.FileStatus.

SetOriginUrlAsync(string)

Changes the upstream origin remote URL for the local repo. This works by editing the ~/.git/config file within the local repo.

Declaration

public Task SetOriginUrlAsync(string url)

Parameters

Type	Name	Description
string	url	Specifies the new remote URL.

Returns

Type	Description
Task	The tracking Task.

StageAsync(string)

Stages a file.

Declaration

public Task StageAsync(string path)

Parameters

Type	Name	Description
string	path	Path to the file. note You can pass "*" to stage all untracked files.

Returns

Type	Description
Task	The tracking Task.

UndoAsync()

Reverts any uncommitted changes in the current local repository branch, including untracked files.

Declaration

public Task UndoAsync()

Returns

Type	Description
Task	The tracking Task.

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the GitHubRepo has been disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the operation fails.

UnstageAsync(string)

Unstages a file.

Declaration

public Task UnstageAsync(string path)

Parameters

Type	Name	Description
string	path	Path to the file.

Returns

Type	Description
Task	The tracking Task.