Base.LibGit2

Base.LibGit2

The LibGit2 module provides bindings to libgit2, a portable C library that implements core functionality for the Git version control system. These bindings are currently used to power Julia's package manager. It is expected that this module will eventually be moved into a separate package.

Functionality

Some of this documentation assumes some prior knowledge of the libgit2 API. For more information on some of the objects and methods referenced here, consult the upstream libgit2 API reference.

Abstract credentials payload

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

source

Credentials that support caching

source
LibGit2.CheckoutOptions

Matches the git_checkout_options struct.

source
LibGit2.CloneOptions

Matches the git_clone_options struct.

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

source
LibGit2.DiffFile

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

source
LibGit2.DiffOptionsStruct

Matches the git_diff_options struct.

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

source
LibGit2.FetchOptions

Matches the git_fetch_options struct.

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

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

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

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

source
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)
source
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)
source
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)
source
LibGit2.GitRepo(path::AbstractString)

Opens a git repository at path.

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

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

source
LibGit2.GitSignature

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

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

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

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

source
LibGit2.IndexEntry

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

source
LibGit2.IndexTime

Matches the git_index_time struct.

source
LibGit2.MergeOptions

Matches the git_merge_options struct.

source
LibGit2.ProxyOptions

Options for connecting through a proxy.

Matches the git_proxy_options struct.

source
LibGit2.PushOptions

Matches the git_push_options struct.

source
LibGit2.RebaseOperation

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

source
LibGit2.RebaseOptions

Matches the git_rebase_options struct.

source
LibGit2.RemoteCallbacks

Callback settings. Matches the git_remote_callbacks struct.

source

SSH credentials type

source
LibGit2.SignatureStruct

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

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

source
LibGit2.StatusOptions

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

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

source
LibGit2.TimeStruct

Time in a signature. Matches the git_time struct.

source

Credentials that support only user and password parameters

source
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/*"]
source
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"]
Note

You may need to close and reopen the GitRemote in question after updating its push refspecs in order for the change to take effect and for calls to push to work.

source
Base.LibGit2.addblob!Function.
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)
source
Base.LibGit2.authorsFunction.
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)
source
Base.LibGit2.branchFunction.
branch(repo::GitRepo)

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

source
Base.LibGit2.branch!Function.
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)
source
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)
source

Checks if credentials were used

source

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

source
Base.LibGit2.cloneFunction.
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")
source
Base.LibGit2.commitFunction.

Wrapper around git_commit_create

source

Commit changes to repository

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

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

source

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.

source

C function pointer for credentials_callback

source

Return signature object. Free it after use.

source
LibGit2.delete_branch(branch::GitReference)

Delete the branch pointed to by branch.

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

source
Base.LibGit2.fetchFunction.
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.

source
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>].

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

source

C function pointer for fetchhead_foreach_callback

source
Base.LibGit2.ffmerge!Function.

Fastforward merge changes into current head

source
Base.LibGit2.fullnameFunction.
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.

source

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

source
Base.LibGit2.gitdirFunction.
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.

source
Base.LibGit2.headFunction.
LibGit2.head(repo::GitRepo) -> GitReference

Returns a GitReference to the current HEAD of repo.

source
head(pkg::AbstractString) -> String

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

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

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

source
Base.LibGit2.head_oidFunction.
LibGit2.head_oid(repo::GitRepo) -> GitHash

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

source
Base.LibGit2.headnameFunction.
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.

source
Base.LibGit2.initFunction.
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.

source
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
source
Base.LibGit2.isbinaryFunction.

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.

source
Base.LibGit2.iscommitFunction.
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
source
Base.LibGit2.isdiffFunction.
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>].

source
Base.LibGit2.isdirtyFunction.
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>].

source
Base.LibGit2.isorphanFunction.
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.

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

source

Mirror callback function

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

source

C function pointer for mirror_callback

source
Base.LibGit2.nameFunction.
LibGit2.name(ref::GitReference)

Return the full name of ref.

source
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"
source
LibGit2.name(tag::GitTag)

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

source
need_update(repo::GitRepo)

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

source
Base.LibGit2.objtypeFunction.
objtype(obj_type::Consts.OBJECT)

Returns the type corresponding to the enum value.

source
Base.LibGit2.pathFunction.
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.

source
Base.LibGit2.peelFunction.
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.

Note

Only annotated tags can be peeled to GitTag objects. Lightweight tags (the default) are references under refs/tags/ which point directly to GitCommit objects.

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

source
LibGit2.posixpath(path)

Standardise the path string path to use POSIX separators.

source
Base.LibGit2.pushFunction.
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.

Note

You can add information about the push refspecs in two other ways: by setting an option in the repository's GitConfig (with push.default as the key) or by calling add_push!. Otherwise you will need to explicitly specify a push refspec in the call to push for it to have any effect, like so: LibGit2.push(repo, refspecs=["refs/heads/master"]).

source
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>].

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

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

source
Base.LibGit2.rebase!Function.
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
source
Base.LibGit2.ref_listFunction.
LibGit2.ref_list(repo::GitRepo) -> Vector{String}

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

source
Base.LibGit2.reftypeFunction.
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

source
Base.LibGit2.remotesFunction.
LibGit2.remotes(repo::GitRepo)

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

source
Base.LibGit2.reset!Function.

Resets credentials for another use

source

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

source

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

source

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

source
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)
source
Base.LibGit2.restoreFunction.
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.

source
Base.LibGit2.revcountFunction.
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>.

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

source
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"
source
Base.LibGit2.snapshotFunction.
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.

source
Base.LibGit2.statusFunction.
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.

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

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

Remove the git tag tag from the repository repo.

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

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

source
Base.LibGit2.targetFunction.
LibGit2.target(tag::GitTag)

The GitHash of the target object of tag.

source
Base.LibGit2.treewalkFunction.

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
source
Base.LibGit2.upstreamFunction.
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.

source
Base.LibGit2.urlFunction.
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"
source
Base.LibGit2.withFunction.

Resource management helper function

source
Base.LibGit2.workdirFunction.
LibGit2.workdir(repo::GitRepo)

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

Note

This will typically be the parent directory of gitdir(repo), but can be different in some cases: e.g. if either the core.worktree configuration variable or the GIT_WORK_TREE environment variable is set.

See also gitdir, path.

source