Crate git2

Expand description

§libgit2 bindings for Rust

This library contains bindings to the libgit2 C library which is used to manage git repositories. The library itself is a work in progress and is likely lacking some bindings here and there, so be warned.

The git2-rs library strives to be as close to libgit2 as possible, but also strives to make using libgit2 as safe as possible. All resource management is automatic as well as adding strong types to all interfaces (including Result)

§Creating a `Repository`

The Repository is the source from which almost all other objects in git-rs are spawned. A repository can be created through opening, initializing, or cloning.

§Initializing a new repository

The init method will create a new repository, assuming one does not already exist.

use git2::Repository;

let repo = match Repository::init("/path/to/a/repo") {
    Ok(repo) => repo,
    Err(e) => panic!("failed to init: {}", e),
};

§Opening an existing repository

use git2::Repository;

let repo = match Repository::open("/path/to/a/repo") {
    Ok(repo) => repo,
    Err(e) => panic!("failed to open: {}", e),
};

§Cloning an existing repository

use git2::Repository;

let url = "https://github.com/alexcrichton/git2-rs";
let repo = match Repository::clone(url, "/path/to/a/repo") {
    Ok(repo) => repo,
    Err(e) => panic!("failed to clone: {}", e),
};

To clone using SSH, refer to RepoBuilder.

§Working with a `Repository`

All derivative objects, references, etc are attached to the lifetime of the source Repository, to ensure that they do not outlive the repository itself.

Modules§

build: Builder-pattern objects for configuration various git operations.
cert: Certificate types which are passed to CertificateCheck in RemoteCallbacks.
oid_array: Bindings to libgit2’s raw git_oidarray type
opts: Bindings to libgit2’s git_libgit2_opts function.
string_array: Bindings to libgit2’s raw git_strarray type
transport: Interfaces for adding custom transports to libgit2

Structs§

AnnotatedCommit: A structure to represent an annotated commit, the input to merge and rebase.
ApplyOptions: Options to specify when applying a diff
AttrCheckFlags
Blame: Opaque structure to hold blame results.
BlameHunk: Structure that represents a blame hunk.
BlameIter: An iterator over the hunks in a blame.
BlameOptions: Blame options
Blob: A structure to represent a git blob
BlobWriter: A structure to represent a git writestream for blobs
Branch: A structure to represent a git branch
Branches: An iterator over the branches inside of a repository.
Buf: A structure to wrap an intermediate buffer used by libgit2.
CheckoutNotificationType: Types of notifications emitted from checkouts.
CherrypickOptions: Options to specify when cherry picking
Commit: A structure to represent a git commit
Config: A structure representing a git configuration key/value store
ConfigEntries: An iterator over the ConfigEntry values of a Config structure.
ConfigEntry: A struct representing a certain entry owned by a Config instance.
Cred: A structure to represent git credentials in libgit2.
CredentialHelper: Management of the gitcredentials(7) interface.
CredentialType: Types of credentials that can be requested by a credential callback.
Deltas: An iterator over the diffs in a delta
Describe: The result of a describe operation on either an Describe or a Repository.
DescribeFormatOptions: Options which can be used to customize how a description is formatted.
DescribeOptions: Options which indicate how a Describe is created.
Diff: The diff object that contains all individual file deltas.
DiffBinary: Structure describing the binary contents of a diff.
DiffBinaryFile: The contents of one of the files in a binary diff.
DiffDelta: Description of changes to one entry.
DiffFile: Description of one side of a delta.
DiffFindOptions: Control behavior of rename and copy detection
DiffFlags
DiffHunk: Structure describing a hunk of a diff.
DiffLine: Structure describing a line (or data span) of a diff.
DiffOptions: Structure describing options about how the diff should be executed.
DiffPatchidOptions: Control behavior of formatting emails
DiffStats: Structure describing a hunk of a diff.
DiffStatsFormat: Formatting options for diff stats
Email: A structure to represent patch in mbox format for sending via email
EmailCreateOptions: Options for controlling the formatting of the generated e-mail.
Error: A structure to represent errors coming out of libgit2.
FetchOptions: Options which can be specified to various fetch operations.
Index: A structure to represent a git index
IndexAddOption: Flags for APIs that add files matching pathspec
IndexConflict: A structure to represent the information returned when a conflict is detected in an index entry
IndexConflicts: An iterator over the conflicting entries in an index
IndexEntries: An iterator over the entries in an index
IndexEntry: A structure to represent an entry or a file inside of an index.
IndexEntryExtendedFlag: Flags for the extended_flags field of an IndexEntry.
IndexEntryFlag: Flags for the flags field of an IndexEntry.
IndexTime: Time structure used in a git index entry.
Indexer: A stream to write and index a packfile
Mailmap: A structure to represent a repository’s .mailmap file.
Mempack: A structure to represent a mempack backend for the object database. The Mempack is bound to the Odb that it was created from, and cannot outlive that Odb.
MergeAnalysis: The results of merge_analysis indicating the merge opportunities.
MergeFileOptions: Options for merging a file.
MergeFileResult: Information about file-level merging.
MergeOptions: Options to specify when merging.
MergePreference: The user’s stated preference for merges.
MessageTrailersBytes: Collection of unencoded (bytes) trailers.
MessageTrailersBytesIterator: Borrowed iterator over the raw (bytes) trailers.
MessageTrailersStrs: Collection of UTF-8-encoded trailers.
MessageTrailersStrsIterator: Borrowed iterator over the UTF-8-encoded trailers.
Note: A structure representing a note in git.
Notes: An iterator over all of the notes within a repository.
Object: A structure to represent a git object
Odb: A structure to represent a git object database
OdbLookupFlags: Flags controlling the behavior of ODB lookup operations
OdbObject: An object from the Object Database.
OdbPackwriter: A stream to write a packfile to the ODB
OdbReader: A structure to represent a git ODB rstream
OdbWriter: A structure to represent a git ODB wstream
Oid: Unique identity of any object (commit, tree, blob, tag).
PackBuilder: A builder for creating a packfile
Parents: An iterator over the parent commits of a commit.
Patch: A structure representing the text changes in a single diff delta.
Pathspec: Structure representing a compiled pathspec used for matching against various structures.
PathspecDiffEntries: Iterator over the matching diff deltas.
PathspecEntries: Iterator over the matched paths in a pathspec.
PathspecFailedEntries: Iterator over the failed list of pathspec items that did not match.
PathspecFlags: …
PathspecMatchList: List of filenames matching a pathspec.
Progress: Struct representing the progress by an in-flight transfer.
ProxyOptions: Options which can be specified to various fetch operations.
PushOptions: Options to control the behavior of a git push.
PushUpdate: Represents an update which will be performed on the remote during push.
Rebase: Representation of a rebase
RebaseOperation: A rebase operation
RebaseOptions: Rebase options
Reference: A structure to represent a git reference.
ReferenceFormat: Options for Reference::normalize_name.
ReferenceNames: An iterator over the names of references in a repository.
References: An iterator over the references in a repository.
Reflog: A reference log of a git repository.
ReflogEntry: An entry inside the reflog of a repository
ReflogIter: An iterator over the entries inside of a reflog.
Refspec: A structure to represent a git refspec.
Refspecs: An iterator over the refspecs that a remote contains.
Remote: A structure representing a remote of a git repository.
RemoteCallbacks: A structure to contain the callbacks which are invoked when a repository is being updated or downloaded.
RemoteConnection: Holds callbacks for a connection to a Remote. Disconnects when dropped
RemoteHead: Description of a reference advertised by a remote server, given out on calls to list.
RemoteUpdateFlags: How to handle reference updates.
Repository: An owned git repository, representing all state associated with the underlying filesystem.
RepositoryInitMode: Mode options for RepositoryInitOptions
RepositoryInitOptions: Options which can be used to configure how a repository is initialized
RepositoryOpenFlags: Flags for Repository::open_ext
RevertOptions: Options to specify when reverting
RevparseMode: Flags for the return value of Repository::revparse
Revspec: A revspec represents a range of revisions within a repository.
Revwalk: A revwalk allows traversal of the commit graph defined by including one or more leaves and excluding one or more roots.
Signature: A Signature is used to indicate authorship of various actions throughout the library.
Sort: Orderings that may be specified for Revwalk iteration.
StashApplyFlags
StashApplyOptions: Stash application options structure
StashFlags
StashSaveOptions: Stash application options structure
Status: Status flags for a single file
StatusEntry: A structure representing an entry in the Statuses structure.
StatusIter: An iterator over the statuses in a Statuses instance.
StatusOptions: Options that can be provided to repo.statuses() to control how the status information is gathered.
Statuses: A container for a list of status information about a repository.
Submodule: A structure to represent a git submodule
SubmoduleStatus: Return codes for submodule status.
SubmoduleUpdateOptions: Options to update a submodule.
Tag: A structure to represent a git tag
Time: Time in a signature
Transaction: A structure representing a transactional update of a repository’s references.
Tree: A structure to represent a git tree
TreeBuilder: Constructor for in-memory trees (low-level)
TreeEntry: A structure representing an entry inside of a tree. An entry is borrowed from a tree.
TreeIter: An iterator over the entries in a tree.
Version: Version information about libgit2 and the capabilities it supports.
Worktree: An owned git worktree
WorktreeAddOptions: Options which can be used to configure how a worktree is initialized
WorktreePruneOptions: Options to configure how worktree pruning is performed

Enums§

ApplyLocation: Possible application locations for git_apply see https://libgit2.org/libgit2/#HEAD/type/git_apply_options
AttrValue: All possible states of an attribute.
AutotagOption: Automatic tag following options.
BranchType: An enumeration for the possible types of branches
CertificateCheckStatus: The return value for the RemoteCallbacks::certificate_check callback.
ConfigLevel: An enumeration of the possible priority levels of a config file.
Delta: What type of change is described by a DiffDelta?
DiffBinaryKind: When producing a binary diff, the binary data returned will be either the deflated full (“literal”) contents of the file, or the deflated binary delta between the two sides (whichever is smaller).
DiffFormat: Possible output formats for diff data
DiffLineType: Line origin constants.
Direction: An enumeration of the possible directions for a remote.
ErrorClass: An enumeration of possible categories of things that can have errors when working with a git repository.
ErrorCode: An enumeration of possible errors that can happen when working with a git repository.
FetchPrune: Configuration for how pruning is done on a fetch
FileFavor: Merge file favor options for MergeOptions instruct the file-level merging functionality how to deal with conflicting regions of the files.
FileMode: Valid modes for index and tree entries.
ObjectType: An enumeration all possible kinds objects may have.
PackBuilderStage: Stages that are reported by the PackBuilder progress callback.
RebaseOperationType: A rebase operation
ReferenceType: An enumeration of all possible kinds of references.
RemoteRedirect: Remote redirection settings; whether redirects to another host are permitted.
RepositoryState: A listing of the possible states that a repository can be in.
ResetType: An enumeration of the operations that can be performed for the reset method on a Repository.
StashApplyProgress
StatusShow: Enumeration of possible methods of what can be shown through a status operation.
SubmoduleIgnore: Submodule ignore values
SubmoduleUpdate: Submodule update values
TraceLevel: Available tracing levels. When tracing is set to a particular level, callers will be provided tracing at the given level and all lower levels.
TreeWalkMode: A binary indicator of whether a tree walk should be performed in pre-order or post-order.
TreeWalkResult: Possible return codes for tree walking callback functions.
WorktreeLockStatus: Lock Status of a worktree

Constants§

DEFAULT_COMMENT_CHAR: The default comment character for message_prettify (‘#’)

Traits§

IntoCString: A class of types that can be converted to C strings.

Functions§

message_prettify: Clean up a message, removing extraneous whitespace, and ensure that the message ends with a newline. If comment_char is Some, also remove comment lines starting with that character.
message_trailers_bytes: Get the trailers for the given message.
message_trailers_strs: Get the trailers for the given message.
trace_set: Set the global subscriber called when libgit2 produces a tracing message.

Type Aliases§

Credentials: Callback used to acquire credentials for when a remote is fetched.
IndexMatchedPath: A callback function to filter index matches.
IndexerProgress: Callback to be invoked while indexing is in progress.
StashApplyProgressCb: Stash application progress notification function.
StashCb: This is a callback function you can provide to iterate over all the stashed states that will be invoked per entry.
TransportMessage: Callback for receiving messages delivered by the transport.
UpdateTips: Callback for whenever a reference is updated locally.

Crate git2Copy item path