Struct git2::Repository

pub struct Repository { /* private fields */ }

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.

Implementations

impl Repository

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

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

Attempt to open an already-existing bare repository at path.

The path can point to only a bare repository.

pub fn open_from_env() -> Result<Repository, Error>

Find and open an existing repository, respecting git environment variables. This acts like open_ext with the REPOSITORY_OPEN_FROM_ENV flag, but additionally respects $GIT_DIR. With $GIT_DIR unset, this will search for a repository starting in the current directory.

pub fn open_ext<P, O, I>(
    path: P,
    flags: RepositoryOpenFlags,
    ceiling_dirs: I
) -> Result<Repository, Error>where
    P: AsRef<Path>,
    O: AsRef<OsStr>,
    I: IntoIterator<Item = O>,

Find and open an existing repository, with additional options.

If flags contains REPOSITORY_OPEN_NO_SEARCH, the path must point directly to a repository; otherwise, this may point to a subdirectory of a repository, and open_ext will search up through parent directories.

If flags contains REPOSITORY_OPEN_CROSS_FS, the search through parent directories will not cross a filesystem boundary (detected when the stat st_dev field changes).

If flags contains REPOSITORY_OPEN_BARE, force opening the repository as bare even if it isn’t, ignoring any working directory, and defer loading the repository configuration for performance.

If flags contains REPOSITORY_OPEN_NO_DOTGIT, don’t try appending /.git to path.

If flags contains REPOSITORY_OPEN_FROM_ENV, open_ext will ignore other flags and ceiling_dirs, and respect the same environment variables git does. Note, however, that path overrides $GIT_DIR; to respect $GIT_DIR as well, use open_from_env.

ceiling_dirs specifies a list of paths that the search through parent directories will stop before entering. Use the functions in std::env to construct or manipulate such a path list.

pub fn open_from_worktree(worktree: &Worktree) -> Result<Repository, Error>

Attempt to open an already-existing repository from a worktree.

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

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

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

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

Creates a new repository in the specified folder with the given options.

See RepositoryInitOptions struct for more information.

pub 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

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

Clone a remote repository, initialize and update its submodules recursively.

This is similar to git clone --recursive.

pub fn from_odb(odb: Odb<'_>) -> Result<Repository, Error>

Attempt to wrap an object database as a repository.

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

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

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

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

pub fn is_bare(&self) -> bool

Tests whether this repository is a bare repository or not.

pub fn is_shallow(&self) -> bool

Tests whether this repository is a shallow clone.

pub fn is_worktree(&self) -> bool

Tests whether this repository is a worktree.

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

Tests whether this repository is empty.

pub fn path(&self) -> &Path

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

pub fn state(&self) -> RepositoryState

Returns the current state of this repository

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

Get the path of the working directory for this repository.

If this repository is bare, then None is returned.

pub fn set_workdir(&self, path: &Path, update_gitlink: bool) -> Result<(), Error>

Set the path to the working directory for this repository.

If update_link is true, create/update the gitlink file in the workdir and set config “core.worktree” (if workdir is not the parent of the .git directory).

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

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

pub fn set_namespace(&self, namespace: &str) -> Result<(), Error>

Set the active namespace for this repository.

pub fn set_namespace_bytes(&self, namespace: &[u8]) -> Result<(), Error>

Set the active namespace for this repository as a byte array.

pub fn remove_namespace(&self) -> Result<(), Error>

Remove the active namespace for this repository.

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

Retrieves the Git merge message. Remember to remove the message when finished.

pub fn remove_message(&self) -> Result<(), Error>

Remove the Git merge message.

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

List all remotes for a given repository

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

Get the information for a particular remote

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

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

pub fn remote_with_fetch(
    &self,
    name: &str,
    url: &str,
    fetch: &str
) -> Result<Remote<'_>, Error>

Add a remote with the provided fetch refspec to the repository’s configuration.

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

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

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

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

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

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

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

pub 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 dereferenceable to a commit.

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

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

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

Retrieve and resolve the reference pointed at by HEAD.

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

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

Determines whether the repository HEAD is detached.

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

Make the repository HEAD directly point to the commit.

If the provided commitish 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.

pub fn set_head_detached_from_annotated(
    &self,
    commitish: AnnotatedCommit<'_>
) -> Result<(), Error>

Make the repository HEAD directly point to the commit.

If the provided commitish 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.

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

Create an iterator for the repo’s references

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

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

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

Load all submodules for this repository and return them.

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

pub 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?

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

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

Create an iterator which loops over the requested branches.

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

pub fn set_index(&self, index: &mut Index) -> Result<(), Error>

Set the Index file for this repository.

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

pub fn get_attr(
    &self,
    path: &Path,
    name: &str,
    flags: AttrCheckFlags
) -> Result<Option<&str>, Error>

Get the value of a git attribute for a path as a string.

This function will return a special string if the attribute is set to a special value. Interpreting the special string is discouraged. You should always use AttrValue::from_string to interpret the return value and avoid the special string.

As such, the return type of this function will probably be changed in the next major version to prevent interpreting the returned string without checking whether it’s special.

pub fn get_attr_bytes(
    &self,
    path: &Path,
    name: &str,
    flags: AttrCheckFlags
) -> Result<Option<&[u8]>, Error>

Get the value of a git attribute for a path as a byte slice.

This function will return a special byte slice if the attribute is set to a special value. Interpreting the special byte slice is discouraged. You should always use AttrValue::from_bytes to interpret the return value and avoid the special string.

As such, the return type of this function will probably be changed in the next major version to prevent interpreting the returned byte slice without checking whether it’s special.

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

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

pub fn blob_writer(
    &self,
    hintpath: Option<&Path>
) -> Result<BlobWriter<'_>, Error>

Create a stream to write blob

This function may need to buffer the data on disk and will in general not be the right choice if you know the size of the data to write.

Use BlobWriter::commit() to commit the write to the object db and get the object id.

If the hintpath parameter is filled, it will be used to determine what git filters should be applied to the object before it is written to the object database.

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

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

pub fn odb(&self) -> Result<Odb<'_>, Error>

Get the object database for this repository

pub fn set_odb(&self, odb: &Odb<'_>) -> Result<(), Error>

Override the object database for this repository

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

pub fn branch_from_annotated_commit(
    &self,
    branch_name: &str,
    target: &AnnotatedCommit<'_>,
    force: bool
) -> Result<Branch<'_>, Error>

Create a new branch pointing at a target commit

This behaves like Repository::branch() but takes an annotated commit, which lets you specify which extended sha syntax string was specified by a user, allowing for more exact reflog messages.

See the documentation for Repository::branch()

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

Lookup a branch by its name in a repository.

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

pub fn commit_create_buffer(
    &self,
    author: &Signature<'_>,
    committer: &Signature<'_>,
    message: &str,
    tree: &Tree<'_>,
    parents: &[&Commit<'_>]
) -> Result<Buf, Error>

Create a commit object and return that as a Buf.

That can be converted to a string like this str::from_utf8(&buf).unwrap().to_string(). And that string can be passed to the commit_signed function, the arguments behave the same as in the commit function.

pub fn commit_signed(
    &self,
    commit_content: &str,
    signature: &str,
    signature_field: Option<&str>
) -> Result<Oid, Error>

Create a commit object from the given buffer and signature

Given the unsigned commit object’s contents, its signature and the header field in which to store the signature, attach the signature to the commit and write it into the given repository.

Use None in signature_field to use the default of gpgsig, which is almost certainly what you want.

Returns the resulting (signed) commit id.

pub fn extract_signature(
    &self,
    commit_id: &Oid,
    signature_field: Option<&str>
) -> Result<(Buf, Buf), Error>

Extract the signature from a commit

Returns a tuple containing the signature in the first value and the signed data in the second.

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

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

pub fn find_annotated_commit(
    &self,
    id: Oid
) -> Result<AnnotatedCommit<'_>, Error>

Creates an AnnotatedCommit from the given commit id.

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

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

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

pub fn reference_matching(
    &self,
    name: &str,
    id: Oid,
    force: bool,
    current_id: Oid,
    log_message: &str
) -> Result<Reference<'_>, Error>

Conditionally create 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.

The direct reference will be created in the repository and written to the disk.

Valid reference names must follow one of two patterns:

1. Top-level names must contain only capital letters and underscores, and must begin and end with a letter. (e.g. “HEAD”, “ORIG_HEAD”).
2. 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 return an error 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.

It will return GIT_EMODIFIED if the reference’s value at the time of updating does not match the one passed through current_id (i.e. if the ref has changed since the user read it).

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

pub fn reference_symbolic_matching(
    &self,
    name: &str,
    target: &str,
    force: bool,
    current_value: &str,
    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.

It will return GIT_EMODIFIED if the reference’s value at the time of updating does not match the one passed through current_value (i.e. if the ref has changed since the user read it).

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

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

pub fn resolve_reference_from_short_name(
    &self,
    refname: &str
) -> Result<Reference<'_>, Error>

Lookup a reference to one of the objects in a repository. Repository::find_reference with teeth; give the method your reference in human-readable format e.g. ‘main’ instead of ‘refs/heads/main’, and it will do-what-you-mean, returning the Reference.

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

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

Creates a git_annotated_commit from the given reference.

pub fn annotated_commit_from_fetchhead(
    &self,
    branch_name: &str,
    remote_url: &str,
    id: &Oid
) -> Result<AnnotatedCommit<'_>, Error>

Creates a git_annotated_commit from FETCH_HEAD.

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

pub 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 add_finalize() to wrap up adding the new submodule and .gitmodules to the index to be ready to commit.

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

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

pub fn submodule_set_ignore(
    &mut self,
    name: &str,
    ignore: SubmoduleIgnore
) -> Result<(), Error>

Set the ignore rule for the submodule in the configuration

This does not affect any currently-loaded instances.

pub fn submodule_set_update(
    &mut self,
    name: &str,
    update: SubmoduleUpdate
) -> Result<(), Error>

Set the update rule for the submodule in the configuration

This setting won’t affect any existing instances.

pub fn submodule_set_url(&mut self, name: &str, url: &str) -> Result<(), Error>

Set the URL for the submodule in the configuration

After calling this, you may wish to call Submodule::sync to write the changes to the checked out submodule repository.

pub fn submodule_set_branch(
    &mut self,
    name: &str,
    branch_name: &str
) -> Result<(), Error>

Set the branch for the submodule in the configuration

After calling this, you may wish to call Submodule::sync to write the changes to the checked out submodule repository.

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

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

pub fn treebuilder(
    &self,
    tree: Option<&Tree<'_>>
) -> Result<TreeBuilder<'_>, Error>

Create a new TreeBuilder, optionally initialized with the entries of the given Tree.

The tree builder can be used to create or modify trees in memory and write them as tree objects to the database.

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

pub fn tag_annotation_create(
    &self,
    name: &str,
    target: &Object<'_>,
    tagger: &Signature<'_>,
    message: &str
) -> Result<Oid, Error>

Create a new tag in the repository from an object without creating a reference.

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.

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

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

Lookup a tag object from the repository.

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

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

pub fn tag_foreach<T>(&self, cb: T) -> Result<(), Error>where
    T: FnMut(Oid, &[u8]) -> bool,

iterate over all tags calling cb on each. the callback is provided the tag id and name

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

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

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

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

For compatibility with git, the repository is put into a merging state. Once the commit is done (or if the user wishes to abort), you should clear this state by calling cleanup_state().

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

pub fn merge_trees(
    &self,
    ancestor_tree: &Tree<'_>,
    our_tree: &Tree<'_>,
    their_tree: &Tree<'_>,
    opts: Option<&MergeOptions>
) -> Result<Index, Error>

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

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

pub fn merge_analysis(
    &self,
    their_heads: &[&AnnotatedCommit<'_>]
) -> Result<(MergeAnalysis, MergePreference), Error>

Analyzes the given branch(es) and determines the opportunities for merging them into the HEAD of the repository.

pub fn merge_analysis_for_ref(
    &self,
    our_ref: &Reference<'_>,
    their_heads: &[&AnnotatedCommit<'_>]
) -> Result<(MergeAnalysis, MergePreference), Error>

Analyzes the given branch(es) and determines the opportunities for merging them into a reference.

pub fn rebase(
    &self,
    branch: Option<&AnnotatedCommit<'_>>,
    upstream: Option<&AnnotatedCommit<'_>>,
    onto: Option<&AnnotatedCommit<'_>>,
    opts: Option<&mut RebaseOptions<'_>>
) -> Result<Rebase<'_>, Error>

Initializes a rebase operation to rebase the changes in branch relative to upstream onto another branch. To begin the rebase process, call next().

pub fn open_rebase(
    &self,
    opts: Option<&mut RebaseOptions<'_>>
) -> Result<Rebase<'_>, Error>

Opens an existing rebase that was previously started by either an invocation of rebase() or by another client.

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

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

Get the default notes reference for this repository

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

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

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

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

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

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

Get the blame for a single file.

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

Find a merge base between two commits

pub fn merge_base_many(&self, oids: &[Oid]) -> Result<Oid, Error>

Find a merge base given a list of commits

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

Find all merge bases between two commits

pub fn merge_bases_many(&self, oids: &[Oid]) -> Result<OidArray, Error>

Find all merge bases given a list of commits

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

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

Determine if a commit is the descendant of another commit

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

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

Delete the reflog for the given reference

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

pub fn reference_has_log(&self, name: &str) -> Result<bool, Error>

Check if the given reference has a reflog.

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

Ensure that the given reference has a reflog.

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

pub fn diff_blobs(
    &self,
    old_blob: Option<&Blob<'_>>,
    old_as_path: Option<&str>,
    new_blob: Option<&Blob<'_>>,
    new_as_path: Option<&str>,
    opts: Option<&mut DiffOptions>,
    file_cb: Option<&mut (dyn FnMut(DiffDelta<'_>, f32) -> bool + '_)>,
    binary_cb: Option<&mut (dyn FnMut(DiffDelta<'_>, DiffBinary<'_>) -> bool + '_)>,
    hunk_cb: Option<&mut (dyn FnMut(DiffDelta<'_>, DiffHunk<'_>) -> bool + '_)>,
    line_cb: Option<&mut (dyn FnMut(DiffDelta<'_>, Option<DiffHunk<'_>>, DiffLine<'_>) -> bool + '_)>
) -> Result<(), Error>

Directly run a diff on two blobs.

Compared to a file, a blob lacks some contextual information. As such, the DiffFile given to the callback will have some fake data; i.e. mode will be 0 and path will be None.

None is allowed for either old_blob or new_blob and will be treated as an empty blob, with the oid set to zero in the DiffFile. Passing None for both blobs is a noop; no callbacks will be made at all.

We do run a binary content check on the blob content and if either blob looks like binary data, the DiffFile binary attribute will be set to 1 and no call to the hunk_cb nor line_cb will be made (unless you set the force_text option).

pub fn diff_tree_to_tree(
    &self,
    old_tree: Option<&Tree<'_>>,
    new_tree: Option<&Tree<'_>>,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff with the difference between two tree objects.

This is equivalent to git diff <old-tree> <new-tree>

The first tree will be used for the “old_file” side of the delta and the second tree will be used for the “new_file” side of the delta. You can pass None to indicate an empty tree, although it is an error to pass None for both the old_tree and new_tree.

pub fn diff_tree_to_index(
    &self,
    old_tree: Option<&Tree<'_>>,
    index: Option<&Index>,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff between a tree and repository index.

This is equivalent to git diff --cached <treeish> or if you pass the HEAD tree, then like git diff --cached.

The tree you pass will be used for the “old_file” side of the delta, and the index will be used for the “new_file” side of the delta.

If you pass None for the index, then the existing index of the repo will be used. In this case, the index will be refreshed from disk (if it has changed) before the diff is generated.

If the tree is None, then it is considered an empty tree.

pub fn diff_index_to_index(
    &self,
    old_index: &Index,
    new_index: &Index,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff between two index objects.

The first index will be used for the “old_file” side of the delta, and the second index will be used for the “new_file” side of the delta.

pub fn diff_index_to_workdir(
    &self,
    index: Option<&Index>,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff between the repository index and the workdir directory.

This matches the git diff command. See the note below on tree_to_workdir for a discussion of the difference between git diff and git diff HEAD and how to emulate a git diff <treeish> using libgit2.

The index will be used for the “old_file” side of the delta, and the working directory will be used for the “new_file” side of the delta.

If you pass None for the index, then the existing index of the repo will be used. In this case, the index will be refreshed from disk (if it has changed) before the diff is generated.

pub fn diff_tree_to_workdir(
    &self,
    old_tree: Option<&Tree<'_>>,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff between a tree and the working directory.

The tree you provide will be used for the “old_file” side of the delta, and the working directory will be used for the “new_file” side.

This is not the same as git diff <treeish> or git diff-index <treeish>. Those commands use information from the index, whereas this function strictly returns the differences between the tree and the files in the working directory, regardless of the state of the index. Use tree_to_workdir_with_index to emulate those commands.

To see difference between this and tree_to_workdir_with_index, consider the example of a staged file deletion where the file has then been put back into the working dir and further modified. The tree-to-workdir diff for that file is ‘modified’, but git diff would show status ‘deleted’ since there is a staged delete.

If None is passed for tree, then an empty tree is used.

pub fn diff_tree_to_workdir_with_index(
    &self,
    old_tree: Option<&Tree<'_>>,
    opts: Option<&mut DiffOptions>
) -> Result<Diff<'_>, Error>

Create a diff between a tree and the working directory using index data to account for staged deletes, tracked files, etc.

This emulates git diff <tree> by diffing the tree to the index and the index to the working directory and blending the results into a single diff that includes staged deleted, etc.

pub fn packbuilder(&self) -> Result<PackBuilder<'_>, Error>

Create a PackBuilder

pub fn stash_save(
    &mut self,
    stasher: &Signature<'_>,
    message: &str,
    flags: Option<StashFlags>
) -> Result<Oid, Error>

Save the local modifications to a new stash.

pub fn stash_save2(
    &mut self,
    stasher: &Signature<'_>,
    message: Option<&str>,
    flags: Option<StashFlags>
) -> Result<Oid, Error>

Save the local modifications to a new stash. unlike stash_save it allows to pass a null message

pub fn stash_apply(
    &mut self,
    index: usize,
    opts: Option<&mut StashApplyOptions<'_>>
) -> Result<(), Error>

Apply a single stashed state from the stash list.

pub fn stash_foreach<C>(&mut self, callback: C) -> Result<(), Error>where
    C: FnMut(usize, &str, &Oid) -> bool,

Loop over all the stashed states and issue a callback for each one.

Return true to continue iterating or false to stop.

pub fn stash_drop(&mut self, index: usize) -> Result<(), Error>

Remove a single stashed state from the stash list.

pub fn stash_pop(
    &mut self,
    index: usize,
    opts: Option<&mut StashApplyOptions<'_>>
) -> Result<(), Error>

Apply a single stashed state from the stash list and remove it from the list if successful.

pub fn add_ignore_rule(&self, rules: &str) -> Result<(), Error>

Add ignore rules for a repository.

The format of the rules is the same one of the .gitignore file.

pub fn clear_ignore_rules(&self) -> Result<(), Error>

Clear ignore rules that were explicitly added.

pub fn is_path_ignored<P: AsRef<Path>>(&self, path: P) -> Result<bool, Error>

Test if the ignore rules apply to a given path.

pub fn cherrypick(
    &self,
    commit: &Commit<'_>,
    options: Option<&mut CherrypickOptions<'_>>
) -> Result<(), Error>

Perform a cherrypick

pub fn cherrypick_commit(
    &self,
    cherrypick_commit: &Commit<'_>,
    our_commit: &Commit<'_>,
    mainline: u32,
    options: Option<&MergeOptions>
) -> Result<Index, Error>

Create an index of uncommitted changes, representing the result of cherry-picking.

pub fn branch_remote_name(&self, refname: &str) -> Result<Buf, Error>

Find the remote name of a remote-tracking branch

pub fn branch_upstream_name(&self, refname: &str) -> Result<Buf, Error>

Retrieves the name of the reference supporting the remote tracking branch, given the name of a local branch reference.

pub fn branch_upstream_remote(&self, refname: &str) -> Result<Buf, Error>

Retrieve the name of the upstream remote of a local branch.

pub fn apply(
    &self,
    diff: &Diff<'_>,
    location: ApplyLocation,
    options: Option<&mut ApplyOptions<'_>>
) -> Result<(), Error>

Apply a Diff to the given repo, making changes directly in the working directory, the index, or both.

pub fn apply_to_tree(
    &self,
    tree: &Tree<'_>,
    diff: &Diff<'_>,
    options: Option<&mut ApplyOptions<'_>>
) -> Result<Index, Error>

Apply a Diff to the provided tree, and return the resulting Index.

pub fn revert(
    &self,
    commit: &Commit<'_>,
    options: Option<&mut RevertOptions<'_>>
) -> Result<(), Error>

Reverts the given commit, producing changes in the index and working directory.

pub fn revert_commit(
    &self,
    revert_commit: &Commit<'_>,
    our_commit: &Commit<'_>,
    mainline: u32,
    options: Option<&MergeOptions>
) -> Result<Index, Error>

Reverts the given commit against the given “our” commit, producing an index that reflects the result of the revert.

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

Lists all the worktrees for the repository

pub fn find_worktree(&self, name: &str) -> Result<Worktree, Error>

Opens a worktree by name for the given repository

This can open any worktree that the worktrees method returns.

pub fn worktree<'a>(
    &'a self,
    name: &str,
    path: &Path,
    opts: Option<&WorktreeAddOptions<'a>>
) -> Result<Worktree, Error>

Creates a new worktree for the repository

pub fn transaction<'a>(&'a self) -> Result<Transaction<'a>, Error>

Create a new transaction

pub fn mailmap(&self) -> Result<Mailmap, Error>

Gets this repository’s mailmap.

pub fn mergehead_foreach<C>(&mut self, callback: C) -> Result<(), Error>where
    C: FnMut(&Oid) -> bool,

If a merge is in progress, invoke ‘callback’ for each commit ID in the MERGE_HEAD file.

pub fn fetchhead_foreach<C>(&self, callback: C) -> Result<(), Error>where
    C: FnMut(&str, &[u8], &Oid, bool) -> bool,

Invoke ‘callback’ for each entry in the given FETCH_HEAD file.

callback will be called with with following arguments:

• &str: the reference name
• &[u8]: the remote url
• &Oid: the reference target OID
• bool: was the reference the result of a merge

Trait Implementations

impl Drop for Repository

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Repository