Base.LibGit2

Abstract credentials payload

LibGit2.Buffer

A data buffer for exporting data from libgit2. Matches the git_buf struct.

When fetching data from LibGit2, a typical usage would look like:

buf_ref = Ref(Buffer())
@check ccall(..., (Ptr{Buffer},), buf_ref)
# operation on buf_ref
free(buf_ref)

In particular, note that LibGit2.free should be called afterward on the Ref object.

Credentials that support caching

LibGit2.CheckoutOptions

Matches the git_checkout_options struct.

LibGit2.CloneOptions

Matches the git_clone_options struct.

LibGit2.DiffDelta

Description of changes to one entry. Matches the git_diff_delta struct.

The fields represent:

• status: One of Consts.DELTA_STATUS, indicating whether the file has been added/modified/deleted.

• flags: Flags for the delta and the objects on each side. Determines whether to treat the file(s) as binary/text, whether they exist on each side of the diff, and whether the object ids are known to be correct.

• similarity: Used to indicate if a file has been renamed or copied.

• nfiles: The number of files in the delta (for instance, if the delta was run on a submodule commit id, it may contain more than one file).

• old_file: A DiffFile containing information about the file(s) before the changes.

• new_file: A DiffFile containing information about the file(s) after the changes.

LibGit2.DiffFile

Description of one side of a delta. Matches the git_diff_file struct.

LibGit2.DiffOptionsStruct

Matches the git_diff_options struct.

LibGit2.FetchHead

Contains the information about HEAD during a fetch, including the name and URL of the branch fetched from, the oid of the HEAD, and whether the fetched HEAD has been merged locally.

LibGit2.FetchOptions

Matches the git_fetch_options struct.

GitBlob(repo::GitRepo, hash::AbstractGitHash)
GitBlob(repo::GitRepo, spec::AbstractString)

Return a GitBlob object from repo specified by hash/spec.

• hash is a full (GitHash) or partial (GitShortHash) hash.

• spec is a textual specification: see the git docs for a full list.

GitCommit(repo::GitRepo, hash::AbstractGitHash)
GitCommit(repo::GitRepo, spec::AbstractString)

Return a GitCommit object from repo specified by hash/spec.

• hash is a full (GitHash) or partial (GitShortHash) hash.

• spec is a textual specification: see the git docs for a full list.

GitHash

A git object identifier, based on the sha-1 hash. It is a 20 byte string (40 hex digits) used to identify a GitObject in a repository.

GitObject(repo::GitRepo, hash::AbstractGitHash)
GitObject(repo::GitRepo, spec::AbstractString)

Return the specified object (GitCommit, GitBlob, GitTree or GitTag) from repo specified by hash/spec.

• hash is a full (GitHash) or partial (GitShortHash) hash.

• spec is a textual specification: see the git docs for a full list.

GitRemote(repo::GitRepo, rmt_name::AbstractString, rmt_url::AbstractString) -> GitRemote

Look up a remote git repository using its name and URL. Uses the default fetch refspec.

Example

repo = LibGit2.init(repo_path)
remote = LibGit2.GitRemote(repo, "upstream", repo_url)

GitRemote(repo::GitRepo, rmt_name::AbstractString, rmt_url::AbstractString, fetch_spec::AbstractString) -> GitRemote

Look up a remote git repository using the repository's name and URL, as well as specifications for how to fetch from the remote (e.g. which remote branch to fetch from).

Example

repo = LibGit2.init(repo_path)
refspec = "+refs/heads/mybranch:refs/remotes/origin/mybranch"
remote = LibGit2.GitRemote(repo, "upstream", repo_url, refspec)

GitRemoteAnon(repo::GitRepo, url::AbstractString) -> GitRemote

Look up a remote git repository using only its URL, not its name.

Example

repo = LibGit2.init(repo_path)
remote = LibGit2.GitRemoteAnon(repo, repo_url)

LibGit2.GitRepo(path::AbstractString)

Opens a git repository at path.

LibGit2.GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))

Opens a git repository at path with extended controls (for instance, if the current user must be a member of a special access group to read path).

GitShortHash

This is a shortened form of GitHash, which can be used to identify a git object when it is unique.

Internally it is stored as two fields: a full-size GitHash (hash) and a length (len). Only the initial len hex digits of hash are used.

LibGit2.GitSignature

This is a Julia wrapper around a pointer to a git_signature object.

LibGit2.GitStatus(repo::GitRepo; status_opts=StatusOptions())

Collect information about the status of each file in the git repository repo (e.g. is the file modified, staged, etc.). status_opts can be used to set various options, for instance whether or not to look at untracked files or whether to include submodules or not.

GitTag(repo::GitRepo, hash::AbstractGitHash)
GitTag(repo::GitRepo, spec::AbstractString)

Return a GitTag object from repo specified by hash/spec.

• hash is a full (GitHash) or partial (GitShortHash) hash.

• spec is a textual specification: see the git docs for a full list.

GitTree(repo::GitRepo, hash::AbstractGitHash)
GitTree(repo::GitRepo, spec::AbstractString)

Return a GitTree object from repo specified by hash/spec.

• hash is a full (GitHash) or partial (GitShortHash) hash.

• spec is a textual specification: see the git docs for a full list.

LibGit2.IndexEntry

In-memory representation of a file entry in the index. Matches the git_index_entry struct.

LibGit2.IndexTime

Matches the git_index_time struct.

LibGit2.MergeOptions

Matches the git_merge_options struct.

LibGit2.ProxyOptions

Options for connecting through a proxy.

Matches the git_proxy_options struct.

LibGit2.PushOptions

Matches the git_push_options struct.

LibGit2.RebaseOperation

Describes a single instruction/operation to be performed during the rebase. Matches the git_rebase_operation struct.

LibGit2.RebaseOptions

Matches the git_rebase_options struct.

LibGit2.RemoteCallbacks

Callback settings. Matches the git_remote_callbacks struct.

SSH credentials type

LibGit2.SignatureStruct

An action signature (e.g. for committers, taggers, etc). Matches the git_signature struct.

LibGit2.StatusEntry

Providing the differences between the file as it exists in HEAD and the index, and providing the differences between the index and the working directory. Matches the git_status_entry struct.

LibGit2.StatusOptions

Options to control how git_status_foreach_ext() will issue callbacks. Matches the git_status_opt_t struct.

LibGit2.StrArrayStruct

A LibGit2 representation of an array of strings. Matches the git_strarray struct.

When fetching data from LibGit2, a typical usage would look like:

sa_ref = Ref(StrArrayStruct())
@check ccall(..., (Ptr{StrArrayStruct},), sa_ref)
res = convert(Vector{String}, sa_ref[])
free(sa_ref)

In particular, note that LibGit2.free should be called afterward on the Ref object.

Conversely, when passing a vector of strings to LibGit2, it is generally simplest to rely on implicit conversion:

strs = String[...]
@check ccall(..., (Ptr{StrArrayStruct},), strs)

Note that no call to free is required as the data is allocated by Julia.

LibGit2.TimeStruct

Time in a signature. Matches the git_time struct.

Credentials that support only user and password parameters

add_fetch!(repo::GitRepo, rmt::GitRemote, fetch_spec::String)

Add a fetch refspec for the specified rmt. This refspec will contain information about which branch(es) to fetch from.

Example

julia> LibGit2.add_fetch!(repo, remote, "upstream");

julia> LibGit2.fetch_refspecs(remote)
String["+refs/heads/*:refs/remotes/upstream/*"]

add_push!(repo::GitRepo, rmt::GitRemote, push_spec::String)

Add a push refspec for the specified rmt. This refspec will contain information about which branch(es) to push to.

Example

julia> LibGit2.add_push!(repo, remote, "refs/heads/master");

julia> remote = LibGit2.get(LibGit2.GitRemote, repo, branch);

julia> LibGit2.push_refspecs(remote)
String["refs/heads/master"]

LibGit2.addblob!(repo::GitRepo, path::AbstractString)

Reads the file at path and adds it to the object database of repo as a loose blob. Returns the GitHash of the resulting blob.

Example

hash_str = hex(commit_oid)
blob_file = joinpath(repo_path, ".git", "objects", hash_str[1:2], hash_str[3:end])
id = LibGit2.addblob!(repo, blob_file)

authors(repo::GitRepo) -> Vector{Signature}

Returns all authors of commits to the repo repository.

Example

repo = LibGit2.GitRepo(repo_path)
repo_file = open(joinpath(repo_path, test_file), "a")

println(repo_file, commit_msg)
flush(repo_file)
LibGit2.add!(repo, test_file)
sig = LibGit2.Signature("TEST", "TEST@TEST.COM", round(time(), 0), 0)
commit_oid1 = LibGit2.commit(repo, "commit1"; author=sig, committer=sig)
println(repo_file, randstring(10))
flush(repo_file)
LibGit2.add!(repo, test_file)
commit_oid2 = LibGit2.commit(repo, "commit2"; author=sig, committer=sig)

# will be a Vector of [sig, sig]
auths = LibGit2.authors(repo)

branch(repo::GitRepo)

Equivalent to git branch. Create a new branch from the current HEAD.

branch!(repo::GitRepo, branch_name::AbstractString, commit::AbstractString=""; kwargs...)

Checkout a new git branch in the repo repository. commit is the GitHash, in string form, which will be the start of the new branch. If commit is an empty string, the current HEAD will be used.

The keyword arguments are:

• track::AbstractString="": the name of the remote branch this new branch should track, if any. If empty (the default), no remote branch will be tracked.

• force::Bool=false: if true, branch creation will be forced.

• set_head::Bool=true: if true, after the branch creation finishes the branch head will be set as the HEAD of repo.

Equivalent to git checkout [-b|-B] <branch_name> [<commit>] [--track <track>].

Example

repo = LibGit2.GitRepo(repo_path)
LibGit2.branch!(repo, "new_branch", set_head=false)

checkout!(repo::GitRepo, commit::AbstractString=""; force::Bool=true)

Equivalent to git checkout [-f] --detach <commit>. Checkout the git commit commit (a GitHash in string form) in repo. If force is true, force the checkout and discard any current changes. Note that this detaches the current HEAD.

Example

repo = LibGit2.init(repo_path)
open(joinpath(LibGit2.path(repo), "file1"), "w") do f
    write(f, "111
")
end
LibGit2.add!(repo, "file1")
commit_oid = LibGit2.commit(repo, "add file1")
open(joinpath(LibGit2.path(repo), "file1"), "w") do f
    write(f, "112
")
end
# would fail without the force=true
# since there are modifications to the file
LibGit2.checkout!(repo, string(commit_oid), force=true)

Checks if credentials were used

Checks if credentials were used or failed authentication, see LibGit2.credentials_callback

clone(repo_url::AbstractString, repo_path::AbstractString; kwargs...)

Clone a remote repository located at repo_url to the local filesystem location repo_path.

The keyword arguments are:

• branch::AbstractString="": which branch of the remote to clone, if not the default repository branch (usually master).

• isbare::Bool=false: if true, clone the remote as a bare repository, which will make repo_path itself the git directory instead of repo_path/.git. This means that a working tree cannot be checked out. Plays the role of the git CLI argument --bare.

• remote_cb::Ptr{Void}=C_NULL: a callback which will be used to create the remote before it is cloned. If C_NULL (the default), no attempt will be made to create the remote - it will be assumed to already exist.

• payload::Nullable{P<:AbstractCredentials}=Nullable{AbstractCredentials}(): provides credentials if necessary, for instance if the remote is a private repository.

Equivalent to git clone [-b <branch>] [--bare] <repo_url> <repo_path>.

Examples

repo_url = "https://github.com/JuliaLang/Example.jl"
repo1 = LibGit2.clone(repo_url, "test_path")
repo2 = LibGit2.clone(repo_url, "test_path", isbare=true)
julia_url = "https://github.com/JuliaLang/julia"
julia_repo = LibGit2.clone(julia_url, "julia_path", branch="release-0.6")

Wrapper around git_commit_create

Commit changes to repository

LibGit2.commit(rb::GitRebase, sig::GitSignature)

Commits the current patch to the rebase rb, using sig as the committer. Is silent if the commit has already been applied.

LibGit2.create_branch(repo::GitRepo, bname::AbstractString, commit_obj::GitCommit; force::Bool=false)

Create a new branch in the repository repo with name bname, which points to commit commit_obj (which has to be part of repo). If force is true, overwrite an existing branch named bname if it exists. If force is false and a branch already exists named bname, this function will throw an error.

Credentials callback function

Function provides different credential acquisition functionality w.r.t. a connection protocol. If a payload is provided then payload_ptr should contain a LibGit2.AbstractCredentials object.

For LibGit2.Consts.CREDTYPE_USERPASS_PLAINTEXT type, if the payload contains fields: user & pass, they are used to create authentication credentials. Empty user name and password trigger an authentication error.

For LibGit2.Consts.CREDTYPE_SSH_KEY type, if the payload contains fields: user, prvkey, pubkey & pass, they are used to create authentication credentials. Empty user name triggers an authentication error.

Credentials are checked in the following order (if supported):

• ssh key pair (ssh-agent if specified in payload's usesshagent field)

• plain text

Note: Due to the specifics of the libgit2 authentication procedure, when authentication fails, this function is called again without any indication whether authentication was successful or not. To avoid an infinite loop from repeatedly using the same faulty credentials, the checkused! function can be called. This function returns true if the credentials were used. Using credentials triggers a user prompt for (re)entering required information. UserPasswordCredentials and CachedCredentials are implemented using a call counting strategy that prevents repeated usage of faulty credentials.

C function pointer for credentials_callback

Return signature object. Free it after use.

LibGit2.delete_branch(branch::GitReference)

Delete the branch pointed to by branch.

diff_files(repo::GitRepo, branch1::AbstractString, branch2::AbstractString; kwarg...) -> Vector{AbstractString}

Show which files have changed in the git repository repo between branches branch1 and branch2.

The keyword argument is:

• filter::Set{Consts.DELTA_STATUS}=Set([Consts.DELTA_ADDED, Consts.DELTA_MODIFIED, Consts.DELTA_DELETED])), and it sets options for the diff. The default is to show files added, modified, or deleted.

Returns only the names of the files which have changed, not their contents.

Example

LibGit2.branch!(repo, "branch/a")
LibGit2.branch!(repo, "branch/b")
# add a file to repo
open(joinpath(LibGit2.path(repo),"file"),"w") do f
    write(f, "hello repo
")
end
LibGit2.add!(repo, "file")
LibGit2.commit(repo, "add file")
# returns ["file"]
filt = Set([LibGit2.Consts.DELTA_ADDED])
files = LibGit2.diff_files(repo, "branch/a", "branch/b", filter=filt)
# returns [] because existing files weren't modified
filt = Set([LibGit2.Consts.DELTA_MODIFIED])
files = LibGit2.diff_files(repo, "branch/a", "branch/b", filter=filt)

Equivalent to git diff --name-only --diff-filter=<filter> <branch1> <branch2>.

fetch(rmt::GitRemote, refspecs; options::FetchOptions=FetchOptions(), msg="")

Fetch from the specified rmt remote git repository, using refspecs to determine which remote branch(es) to fetch. The keyword arguments are:

• options: determines the options for the fetch, e.g. whether to prune afterwards.

• msg: a message to insert into the reflogs.

fetch(repo::GitRepo; kwargs...)

Fetches updates from an upstream of the repository repo.

The keyword arguments are:

• remote::AbstractString="origin": which remote, specified by name, of repo to fetch from. If this is empty, the URL will be used to construct an anonymous remote.

• remoteurl::AbstractString="": the URL of remote. If not specified, will be assumed based on the given name of remote.

• refspecs=AbstractString[]: determines properties of the fetch.

• payload=Nullable{AbstractCredentials}(): provides credentials, if necessary, for instance if remote is a private repository.

Equivalent to git fetch [<remoteurl>|<repo>] [<refspecs>].

fetch_refspecs(rmt::GitRemote) -> Vector{String}

Get the fetch refspecs for the specified rmt. These refspecs contain information about which branch(es) to fetch from.

C function pointer for fetchhead_foreach_callback

Fastforward merge changes into current head

LibGit2.fullname(ref::GitReference)

Return the name of the reference pointed to by the symbolic reference ref. If ref is not a symbolic reference, returns an empty string.

Obtain the cached credentials for the given host+protocol (credid), or return and store the default if not found

LibGit2.gitdir(repo::GitRepo)

Returns the location of the "git" files of repo:

• for normal repositories, this is the location of the .git folder.

• for bare repositories, this is the location of the repository itself.

See also workdir, path.

LibGit2.head(repo::GitRepo) -> GitReference

Returns a GitReference to the current HEAD of repo.

head(pkg::AbstractString) -> String

Return current HEAD GitHash of the pkg repo as a string.

LibGit2.head!(repo::GitRepo, ref::GitReference) -> GitReference

Set the HEAD of repo to the object pointed to by ref.

LibGit2.head_oid(repo::GitRepo) -> GitHash

Lookup the object id of the current HEAD of git repository repo.

LibGit2.headname(repo::GitRepo)

Lookup the name of the current HEAD of git repository repo. If repo is currently detached, returns the name of the HEAD it's detached from.

LibGit2.init(path::AbstractString, bare::Bool=false) -> GitRepo

Opens a new git repository at path. If bare is false, the working tree will be created in path/.git. If bare is true, no working directory will be created.

is_ancestor_of(a::AbstractString, b::AbstractString, repo::GitRepo) -> Bool

Returns true if a, a GitHash in string form, is an ancestor of b, a GitHash in string form.

Example

julia> repo = LibGit2.GitRepo(repo_path);

julia> LibGit2.add!(repo, test_file1);

julia> commit_oid1 = LibGit2.commit(repo, "commit1");

julia> LibGit2.add!(repo, test_file2);

julia> commit_oid2 = LibGit2.commit(repo, "commit2");

julia> LibGit2.is_ancestor_of(string(commit_oid1), string(commit_oid2), repo)
true

Use a heuristic to guess if a file is binary: searching for NULL bytes and looking for a reasonable ratio of printable to non-printable characters among the first 8000 bytes.

iscommit(id::AbstractString, repo::GitRepo) -> Bool

Checks if commit id (which is a GitHash in string form) is in the repository.

Example

julia> repo = LibGit2.GitRepo(repo_path);

julia> LibGit2.add!(repo, test_file);

julia> commit_oid = LibGit2.commit(repo, "add test_file");

julia> LibGit2.iscommit(string(commit_oid), repo)
true

LibGit2.isdiff(repo::GitRepo, treeish::AbstractString, pathspecs::AbstractString=""; cached::Bool=false)

Checks if there are any differences between the tree specified by treeish and the tracked files in the working tree (if cached=false) or the index (if cached=true). pathspecs are the specifications for options for the diff.

Example

repo = LibGit2.GitRepo(repo_path)
LibGit2.isdiff(repo, "HEAD") # should be false
open(joinpath(repo_path, new_file), "a") do f
    println(f, "here's my cool new file")
end
LibGit2.isdiff(repo, "HEAD") # now true

Equivalent to git diff-index <treeish> [-- <pathspecs>].

LibGit2.isdirty(repo::GitRepo, pathspecs::AbstractString=""; cached::Bool=false) -> Bool

Checks if there have been any changes to tracked files in the working tree (if cached=false) or the index (if cached=true). pathspecs are the specifications for options for the diff.

Example

repo = LibGit2.GitRepo(repo_path)
LibGit2.isdirty(repo) # should be false
open(joinpath(repo_path, new_file), "a") do f
    println(f, "here's my cool new file")
end
LibGit2.isdirty(repo) # now true
LibGit2.isdirty(repo, new_file) # now true

Equivalent to git diff-index HEAD [-- <pathspecs>].

LibGit2.isorphan(repo::GitRepo)

Checks if the current branch is an "orphan" branch, i.e. has no commits. The first commit to this branch will have no parents.

lookup_branch(repo::GitRepo, branch_name::AbstractString, remote::Bool=false) -> Nullable{GitReference}

Determine if the branch specified by branch_name exists in the repository repo. If remote is true, repo is assumed to be a remote git repository. Otherwise, it is part of the local filesystem.

lookup_branch returns a Nullable, which will be null if the requested branch does not exist yet. If the branch does exist, the Nullable contains a GitReference to the branch.

Mirror callback function

Function sets +refs/*:refs/* refspecs and mirror flag for remote reference.

C function pointer for mirror_callback

LibGit2.name(ref::GitReference)

Return the full name of ref.

name(rmt::GitRemote)

Get the name of a remote repository, for instance "origin". If the remote is anonymous (see GitRemoteAnon) the name will be an empty string "".

Example

julia> repo_url = "https://github.com/JuliaLang/Example.jl";

julia> repo = LibGit2.clone(cache_repo, "test_directory");

julia> remote = LibGit2.GitRemote(repo, "origin", repo_url);

julia> name(remote)
"origin"

LibGit2.name(tag::GitTag)

The name of tag (e.g. "v0.5").

need_update(repo::GitRepo)

Equivalent to git update-index. Returns true if repo needs updating.

objtype(obj_type::Consts.OBJECT)

Returns the type corresponding to the enum value.

LibGit2.path(repo::GitRepo)

The base file path of the repository repo.

• for normal repositories, this will typically be the parent directory of the ".git" directory (note: this may be different than the working directory, see workdir for more details).

• for bare repositories, this is the location of the "git" files.

See also gitdir, workdir.

peel([T,] ref::GitReference)

Recursively peel ref until an object of type T is obtained. If no T is provided, then ref will be peeled until an object other than a GitTag is obtained.

• A GitTag will be peeled to the object it references.

• A GitCommit will be peeled to a GitTree.

peel([T,] obj::GitObject)

Recursively peel obj until an object of type T is obtained. If no T is provided, then obj will be peeled until the type changes.

• A GitTag will be peeled to the object it references.

• A GitCommit will be peeled to a GitTree.

LibGit2.posixpath(path)

Standardise the path string path to use POSIX separators.

push(rmt::GitRemote, refspecs; force::Bool=false, options::PushOptions=PushOptions())

Push to the specified rmt remote git repository, using refspecs to determine which remote branch(es) to push to. The keyword arguments are:

• force: if true, a force-push will occur, disregarding conflicts.

• options: determines the options for the push, e.g. which proxy headers to use.

push(repo::GitRepo; kwargs...)

Pushes updates to an upstream of repo.

The keyword arguments are:

• remote::AbstractString="origin": the name of the upstream remote to push to.

• remoteurl::AbstractString="": the URL of remote.

• refspecs=AbstractString[]: determines properties of the push.

• force::Bool=false: determines if the push will be a force push, overwriting the remote branch.

• payload=Nullable{AbstractCredentials}(): provides credentials, if necessary, for instance if remote is a private repository.

Equivalent to git push [<remoteurl>|<repo>] [<refspecs>].

push_refspecs(rmt::GitRemote) -> Vector{String}

Get the push refspecs for the specified rmt. These refspecs contain information about which branch(es) to push to.

LibGit2.read_tree!(idx::GitIndex, tree::GitTree)
LibGit2.read_tree!(idx::GitIndex, treehash::AbstractGitHash)

Read the tree tree (or the tree pointed to by treehash in the repository owned by idx) into the index idx. The current index contents will be replaced.

LibGit2.rebase!(repo::GitRepo, upstream::AbstractString="", newbase::AbstractString="")

Attempt an automatic merge rebase of the current branch, from upstream if provided, or otherwise from the upstream tracking branch. newbase is the branch to rebase onto. By default this is upstream.

If any conflicts arise which cannot be automatically resolved, the rebase will abort, leaving the repository and working tree in its original state, and the function will throw a GitError. This is roughly equivalent to the following command line statement:

git rebase --merge [<upstream>]
if [ -d ".git/rebase-merge" ]; then
    git rebase --abort
fi

LibGit2.ref_list(repo::GitRepo) -> Vector{String}

Get a list of all reference names in the repo repository.

LibGit2.reftype(ref::GitReference) -> Cint

Returns a Cint corresponding to the type of ref:

• 0 if the reference is invalid

• 1 if the reference is an object id

• 2 if the reference is symbolic

LibGit2.remotes(repo::GitRepo)

Returns a vector of the names of the remotes of repo.

Resets credentials for another use

Updates some entries, determined by the pathspecs, in the index from the target commit tree.

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

git reset [<committish>] [–] <pathspecs>...

reset!(repo::GitRepo, id::GitHash, mode::Cint = Consts.RESET_MIXED)

Reset the repository repo to its state at id, using one of three modes set by mode:

1. Consts.RESET_SOFT - move HEAD to id.

2. Consts.RESET_MIXED - default, move HEAD to id and reset the index to id.

3. Consts.RESET_HARD - move HEAD to id, reset the index to id, and discard all working changes.

Equivalent to git reset [--soft | --mixed | --hard] <id>.

Example

repo = LibGit2.GitRepo(repo_path)
head_oid = LibGit2.head_oid(repo)
open(joinpath(repo_path, "file1"), "w") do f
    write(f, "111
")
end
LibGit2.add!(repo, "file1")
mode = LibGit2.Consts.RESET_HARD
# will discard the changes to file1
# and unstage it
new_head = LibGit2.reset!(repo, head_oid, mode)

restore(s::State, repo::GitRepo)

Return a repository repo to a previous States, for example the HEAD of a branch before a merge attempt. s can be generated using the snapshot function.

LibGit2.revcount(repo::GitRepo, commit1::AbstractString, commit2::AbstractString)

List the number of revisions between commit1 and commit2 (committish OIDs in string form). Since commit1 and commit2 may be on different branches, revcount performs a "left-right" revision list (and count), returning a tuple of Ints - the number of left and right commits, respectively. A left (or right) commit refers to which side of a symmetric difference in a tree the commit is reachable from.

Equivalent to git rev-list --left-right --count <commit1> <commit2>.

set_remote_url(repo::GitRepo, url::AbstractString; remote::AbstractString="origin")

Set the url for remote for the git repository repo. The default name of the remote is "origin".

Examples

repo_path = joinpath("test_directory", "Example")
repo = LibGit2.init(repo_path)
url1 = "https://github.com/JuliaLang/Example.jl"
LibGit2.set_remote_url(repo, url1, remote="upstream")
url2 = "https://github.com/JuliaLang/Example2.jl"
LibGit2.set_remote_url(repo_path, url2, remote="upstream2")

set_remote_url(path::AbstractString, url::AbstractString; remote::AbstractString="origin")

Set the url for remote for the git repository located at path. The default name of the remote is "origin".

LibGit2.shortname(ref::GitReference)

Returns a shortened version of the name of ref that's "human-readable".

julia> repo = LibGit2.GitRepo(path_to_repo);

julia> branch_ref = LibGit2.head(repo);

julia> LibGit2.name(branch_ref)
"refs/heads/master"

julia> LibGit2.shortname(branch_ref)
"master"

snapshot(repo::GitRepo) -> State

Take a snapshot of the current state of the repository repo, storing the current HEAD, index, and any uncommitted work. The output State can be used later during a call to restore to return the repository to the snapshotted state.

LibGit2.status(repo::GitRepo, path::String)

Lookup the status of the file at path in the git repository repo. For instance, this can be used to check if the file at path has been modified and needs to be staged and committed.

LibGit2.tag_create(repo::GitRepo, tag::AbstractString, commit; kwargs...)

Create a new git tag tag (e.g. "v0.5") in the repository repo, at the commit commit.

The keyword arguments are:

• msg::AbstractString="": the message for the tag.

• force::Bool=false: if true, existing references will be overwritten.

• sig::Signature=Signature(repo): the tagger's signature.

LibGit2.tag_delete(repo::GitRepo, tag::AbstractString)

Remove the git tag tag from the repository repo.

LibGit2.tag_list(repo::GitRepo) -> Vector{String}

Get a list of all tags in the git repository repo.

LibGit2.target(tag::GitTag)

The GitHash of the target object of tag.

Traverse the entries in a tree and its subtrees in post or pre order.

Function parameter should have following signature:

(Cstring, Ptr{Void}, Ptr{Void}) -> Cint

upstream(ref::GitReference) -> Nullable{GitReference}

Determine if the branch containing ref has a specified upstream branch.

upstream returns a Nullable, which will be null if the requested branch does not have an upstream counterpart. If the upstream branch does exist, the Nullable contains a GitReference to the upstream branch.

url(rmt::GitRemote)

Get the fetch URL of a remote git repository.

Example

julia> repo_url = "https://github.com/JuliaLang/Example.jl";

julia> repo = LibGit2.init(mktempdir());

julia> remote = LibGit2.GitRemote(repo, "origin", repo_url);

julia> LibGit2.url(remote)
"https://github.com/JuliaLang/Example.jl"

Resource management helper function

LibGit2.workdir(repo::GitRepo)

The location of the working directory of repo. This will throw an error for bare repositories.

See also gitdir, path.