Struct git2::Repository

pub struct Repository {
    // some fields omitted
}

An owned git repository, representing all state associated with the underlying filesystem.

This structure corresponds to a git_repository in libgit2. Many other types in git2-rs are derivative from this structure and are attached to its lifetime.

When a repository goes out of scope it is freed in memory but not deleted from the filesystem.

Methods

impl Repository

fn open<P: AsRef<Path>>(path: P) -> Result<Repository, Error>

Attempt to open an already-existing repository at path.

The path can point to either a normal or bare repository.

fn discover<P: AsRef<Path>>(path: P) -> Result<Repository, Error>

Attempt to open an already-existing repository at or above path

This starts at path and looks up the filesystem hierarchy until it finds a repository.

fn init<P: AsRef<Path>>(path: P) -> Result<Repository, Error>

Creates a new repository in the specified folder.

This by default will create any necessary directories to create the repository, and it will read any user-specified templates when creating the repository. This behavior can be configured through init_opts.

fn init_bare<P: AsRef<Path>>(path: P) -> Result<Repository, Error>

Creates a new --bare repository in the specified folder.

The folder must exist prior to invoking this function.

fn init_opts<P: AsRef<Path>>(path: P, opts: &RepositoryInitOptions) -> Result<Repository, Error>

Creates a new --bare repository in the specified folder.

The folder must exist prior to invoking this function.

fn clone<P: AsRef<Path>>(url: &str, into: P) -> Result<Repository, Error>

Clone a remote repository.

See the RepoBuilder struct for more information. This function will delegate to a fresh RepoBuilder

fn revparse(&self, spec: &str) -> Result<Revspec, Error>

Execute a rev-parse operation against the spec listed.

The resulting revision specification is returned, or an error is returned if one occurs.

fn revparse_single(&self, spec: &str) -> Result<Object, Error>

Find a single object, as specified by a revision string.

fn revparse_ext(&self, spec: &str) -> Result<(Object, Option<Reference>), Error>

Find a single object and intermediate reference by a revision string.

See man gitrevisions, or http://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, this intermediate reference is returned.

fn is_bare(&self) -> bool

Tests whether this repository is a bare repository or not.

fn is_shallow(&self) -> bool

Tests whether this repository is a shallow clone.

fn is_empty(&self) -> Result<bool, Error>

Tests whether this repository is empty.

fn path(&self) -> &Path

Returns the path to the .git folder for normal repositories or the repository itself for bare repositories.

fn state(&self) -> RepositoryState

Returns the current state of this repository

fn workdir(&self) -> Option<&Path>

Get the path of the working directory for this repository.

If this repository is bare, then None is returned.

fn namespace(&self) -> Option<&str>

Get the currently active namespace for this repository.

If there is no namespace, or the namespace is not a valid utf8 string, None is returned.

fn namespace_bytes(&self) -> Option<&[u8]>

Get the currently active namespace for this repository as a byte array.

If there is no namespace, None is returned.

fn remotes(&self) -> Result<StringArray, Error>

List all remotes for a given repository

fn find_remote(&self, name: &str) -> Result<Remote, Error>

Get the information for a particular remote

fn remote(&self, name: &str, url: &str) -> Result<Remote, Error>

Add a remote with the default fetch refspec to the repository's configuration.

fn remote_anonymous(&self, url: &str) -> Result<Remote, Error>

Create an anonymous remote

Create a remote with the given url and refspec in memory. You can use this when you have a URL instead of a remote's name. Note that anonymous remotes cannot be converted to persisted remotes.

fn remote_rename(&self, name: &str, new_name: &str) -> Result<StringArray, Error>

Give a remote a new name

All remote-tracking branches and configuration settings for the remote are updated.

A temporary in-memory remote cannot be given a name with this method.

No loaded instances of the remote with the old name will change their name or their list of refspecs.

The returned array of strings is a list of the non-default refspecs which cannot be renamed and are returned for further processing by the caller.

fn remote_delete(&self, name: &str) -> Result<(), Error>

Delete an existing persisted remote.

All remote-tracking branches and configuration settings for the remote will be removed.

fn remote_add_fetch(&self, name: &str, spec: &str) -> Result<(), Error>

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.

fn remote_add_push(&self, name: &str, spec: &str) -> Result<(), Error>

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.

fn remote_set_url(&self, name: &str, url: &str) -> Result<(), Error>

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.

fn remote_set_pushurl(&self, name: &str, pushurl: Option<&str>) -> Result<(), Error>

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.

None indicates that it should be cleared.

fn reset(&self, target: &Object, kind: ResetType, checkout: Option<&mut CheckoutBuilder>) -> Result<(), Error>

Sets the current head to the specified object and optionally resets the index and working tree to match.

A soft reset means the head will be moved to the commit.

A mixed reset will trigger a soft reset, plus the index will be replaced with the content of the commit tree.

A 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.)

The target is a commit-ish to which the head should be moved to. The object can either be a commit or a tag, but tags must be derefernceable to a commit.

The checkout options will only be used for a hard reset.

fn reset_default<T, I>(&self, target: Option<&Object>, paths: I) -> Result<(), Error> where T: IntoCString, I: IntoIterator<Item=T>

Updates some entries in the index from the target commit tree.

The scope of the updated entries is determined by the paths being in the iterator provided.

Passing a None target will result in removing entries in the index matching the provided pathspecs.

fn head(&self) -> Result<Reference, Error>

Retrieve and resolve the reference pointed at by HEAD.

fn set_head(&self, refname: &str) -> Result<(), Error>

Make the repository HEAD point to the specified reference.

If the provided reference points to a tree or a blob, the HEAD is unaltered and an error is returned.

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, no error will be returned. The HEAD will then be attached to an unborn branch.

Otherwise, the HEAD will be detached and will directly point to the commit.

fn set_head_detached(&self, commitish: Oid) -> Result<(), Error>

Make the repository HEAD directly point to the commit.

If the provided committish cannot be found in the repository, the HEAD is unaltered and an error is returned.

If the provided commitish cannot be peeled into a commit, the HEAD is unaltered and an error is returned.

Otherwise, the HEAD will eventually be detached and will directly point to the peeled commit.

fn references(&self) -> Result<References, Error>

Create an iterator for the repo's references

fn references_glob(&self, glob: &str) -> Result<References, Error>

Create an iterator for the repo's references that match the specified glob

fn submodules(&self) -> Result<Vec<Submodule>, Error>

Load all submodules for this repository and return them.

fn statuses(&self, options: Option<&mut StatusOptions>) -> Result<Statuses, Error>

Gather file status information and populate the returned structure.

Note that if a pathspec is given in the options to filter the status, then the results from rename detection (if you enable it) may not be accurate. To do rename detection properly, this must be called with no pathspec so that all files can be considered.

fn status_should_ignore(&self, path: &Path) -> Result<bool, Error>

Test if the ignore rules apply to a given file.

This function checks the ignore rules to see if they would apply to the given file. This indicates if the file would be ignored regardless of whether the file is already in the index or committed to the repository.

One way to think of this is if you were to do "git add ." on the directory containing the file, would it be added or not?

fn status_file(&self, path: &Path) -> Result<Status, Error>

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 NotFound.

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 Ambiguous 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 statuses and scan through looking for the path that you are interested in.

fn branches(&self, filter: Option<BranchType>) -> Result<Branches, Error>

Create an iterator which loops over the requested branches.

fn index(&self) -> Result<Index, Error>

Get the Index file for this repository.

If a custom index has not been set, the default index for the repository will be returned (the one located in .git/index).

fn config(&self) -> Result<Config, Error>

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).

fn blob(&self, data: &[u8]) -> Result<Oid, Error>

Write an in-memory buffer to the ODB as a blob.

The Oid returned can in turn be passed to find_blob to get a handle to the blob.

fn blob_path(&self, path: &Path) -> Result<Oid, Error>

Read a file from the filesystem and write its content to the Object Database as a loose blob

The Oid returned can in turn be passed to find_blob to get a handle to the blob.

fn find_blob(&self, oid: Oid) -> Result<Blob, Error>

Lookup a reference to one of the objects in a repository.

fn branch(&self, branch_name: &str, target: &Commit, force: bool) -> Result<Branch, Error>

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.

fn find_branch(&self, name: &str, branch_type: BranchType) -> Result<Branch, Error>

Lookup a branch by its name in a repository.

fn commit(&self, update_ref: Option<&str>, author: &Signature, committer: &Signature, message: &str, tree: &Tree, parents: &[&Commit]) -> Result<Oid, Error>

Create new commit in the repository

If the update_ref is not None, 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.

fn find_commit(&self, oid: Oid) -> Result<Commit, Error>

Lookup a reference to one of the commits in a repository.

fn find_object(&self, oid: Oid, kind: Option<ObjectType>) -> Result<Object, Error>

Lookup a reference to one of the objects in a repository.

fn reference(&self, name: &str, id: Oid, force: bool, log_message: &str) -> Result<Reference, Error>

Create a new direct reference.

This function will return an error if a reference already exists with the given name unless force is true, in which case it will be overwritten.

fn reference_symbolic(&self, name: &str, target: &str, force: bool, log_message: &str) -> Result<Reference, Error>

Create a new symbolic reference.

This function will return an error if a reference already exists with the given name unless force is true, in which case it will be overwritten.

fn find_reference(&self, name: &str) -> Result<Reference, Error>

Lookup a reference to one of the objects in a repository.

fn refname_to_id(&self, name: &str) -> Result<Oid, Error>

Lookup a reference by name and resolve immediately to OID.

This function provides a quick way to resolve a reference name straight through to the object id that it refers to. This avoids having to allocate or free any Reference objects for simple situations.

fn reference_to_annotated_commit(&self, reference: &Reference) -> Result<AnnotatedCommit, Error>

Creates a git_annotated_commit from the given reference.

fn signature(&self) -> Result<Signature<'static>, Error>

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. It will return NotFound if either the user.name or user.email are not set.

fn submodule(&self, url: &str, path: &Path, use_gitlink: bool) -> Result<Submodule, Error>

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.

To fully emulate "git submodule add" call this function, then open() the submodule repo and perform the clone step as needed. Lastly, call finalize() to wrap up adding the new submodule and .gitmodules to the index to be ready to commit.

fn find_submodule(&self, name: &str) -> Result<Submodule, Error>

Lookup submodule information by name or path.

Given either the submodule name or path (they are usually the same), this returns a structure describing the submodule.

fn submodule_status(&self, name: &str, ignore: SubmoduleIgnore) -> Result<SubmoduleStatus, Error>

Get the status for a submodule.

This looks at a submodule and tries to determine the status. It will return a combination of the SubmoduleStatus values.

fn find_tree(&self, oid: Oid) -> Result<Tree, Error>

Lookup a reference to one of the objects in a repository.

fn tag(&self, name: &str, target: &Object, tagger: &Signature, message: &str, force: bool) -> Result<Oid, Error>

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.

The message will not be cleaned up.

The tag name will be checked for validity. You must avoid the characters '~', '^', ':', ' \ ', '?', '[', and '*', and the sequences ".." and " @ {" which have special meaning to revparse.

fn tag_lightweight(&self, name: &str, target: &Object, force: bool) -> Result<Oid, Error>

Create a new lightweight tag pointing at a target object

A new direct reference will be created pointing to this target object. If force is true and a reference already exists with the given name, it'll be replaced.

fn find_tag(&self, id: Oid) -> Result<Tag, Error>

Lookup a tag object from the repository.

fn tag_delete(&self, name: &str) -> Result<(), Error>

Delete an existing tag reference.

The tag name will be checked for validity, see tag for some rules about valid names.

fn tag_names(&self, pattern: Option<&str>) -> Result<StringArray, Error>

Get a list with all the tags in the repository.

An optional fnmatch pattern can also be specified.

fn checkout_head(&self, opts: Option<&mut CheckoutBuilder>) -> Result<(), Error>

Updates files in the index and the working tree to match the content of the commit pointed at by HEAD.

fn checkout_index(&self, index: Option<&mut Index>, opts: Option<&mut CheckoutBuilder>) -> Result<(), Error>

Updates files in the working tree to match the content of the index.

If the index is None, the repository's index will be used.

fn checkout_tree(&self, treeish: &Object, opts: Option<&mut CheckoutBuilder>) -> Result<(), Error>

Updates files in the index and working tree to match the content of the tree pointed at by the treeish.

fn merge(&self, annotated_commits: &[&AnnotatedCommit], merge_opts: Option<&mut MergeOptions>, checkout_opts: Option<&mut CheckoutBuilder>) -> Result<(), Error>

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.

The merge performed uses the first common ancestor, unlike the git-merge-recursive strategy, which may produce an artificial common ancestor tree when there are multiple ancestors. For compatibility with git, the repository is put into a merging state. Once the commit is done (or if the uses wishes to abort), you should clear this state by calling git_repository_state_cleanup().

fn merge_commits(&self, our_commit: &Commit, their_commit: &Commit, opts: Option<&MergeOptions>) -> Result<Index, Error>

Merge 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.

The merge performed uses the first common ancestor, unlike the git-merge-recursive strategy, which may produce an artificial common ancestor tree when there are multiple ancestors.

The returned index must be freed explicitly with git_index_free.

fn cleanup_state(&self) -> Result<(), Error>

Remove all the metadata associated with an ongoing command like merge, revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, etc.

fn note(&self, author: &Signature, committer: &Signature, notes_ref: Option<&str>, oid: Oid, note: &str, force: bool) -> Result<Oid, Error>

Add a note for an object

The notes_ref argument is the canonical name of the reference to use, defaulting to "refs/notes/commits". If force is specified then previous notes are overwritten.

fn note_default_ref(&self) -> Result<String, Error>

Get the default notes reference for this repository

fn notes(&self, notes_ref: Option<&str>) -> Result<Notes, Error>

Creates a new iterator for notes in this repository.

The notes_ref argument is the canonical name of the reference to use, defaulting to "refs/notes/commits".

The iterator returned yields pairs of (Oid, Oid) where the first element is the id of the note and the second id is the id the note is annotating.

fn find_note(&self, notes_ref: Option<&str>, id: Oid) -> Result<Note, Error>

Read the note for an object.

The notes_ref argument is the canonical name of the reference to use, defaulting to "refs/notes/commits".

The id specified is the Oid of the git object to read the note from.

fn note_delete(&self, id: Oid, notes_ref: Option<&str>, author: &Signature, committer: &Signature) -> Result<(), Error>

Remove the note for an object.

The notes_ref argument is the canonical name of the reference to use, defaulting to "refs/notes/commits".

The id specified is the Oid of the git object to remove the note from.

fn revwalk(&self) -> Result<Revwalk, Error>

Create a revwalk that can be used to traverse the commit graph.

fn blame_file(&self, path: &Path, opts: Option<&mut BlameOptions>) -> Result<Blame, Error>

Get the blame for a single file.

fn merge_base(&self, one: Oid, two: Oid) -> Result<Oid, Error>

Find a merge base between two commits

fn merge_bases(&self, one: Oid, two: Oid) -> Result<OidArray, Error>

Find all merge bases between two commits

fn graph_ahead_behind(&self, local: Oid, upstream: Oid) -> Result<(usize, usize), Error>

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.

fn graph_descendant_of(&self, commit: Oid, ancestor: Oid) -> Result<bool, Error>

Determine if a commit is the descendant of another commit

fn reflog(&self, name: &str) -> Result<Reflog, Error>

Read the reflog for the given reference

If there is no reflog file for the given reference yet, an empty reflog object will be returned.

fn reflog_delete(&self, name: &str) -> Result<(), Error>

Delete the reflog for the given reference

fn reflog_rename(&self, old_name: &str, new_name: &str) -> Result<(), Error>

Rename a reflog

The reflog to be renamed is expected to already exist.

fn describe(&self, opts: &DescribeOptions) -> Result<Describe, Error>

Describes a commit

Performs a describe operation on the current commit and the worktree. After performing a describe on HEAD, a status is run and description is considered to be dirty if there are.

Trait Implementations

impl Send for Repository

impl Drop for Repository

fn drop(&mut self)