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.

`Base.LibGit2.AbstractCredentials` — Type.

Abstract credentials payload

source
`Base.LibGit2.Buffer` — Type.

    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
`Base.LibGit2.CachedCredentials` — Type.

Credentials that support caching

source
`Base.LibGit2.CheckoutOptions` — Type.

    LibGit2.CheckoutOptions

Matches the `git_checkout_options` struct.

source
`Base.LibGit2.CloneOptions` — Type.

    LibGit2.CloneOptions

Matches the `git_clone_options` struct.

source
`Base.LibGit2.DiffDelta` — Type.

    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
`Base.LibGit2.DiffFile` — Type.

    LibGit2.DiffFile

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

source
`Base.LibGit2.DiffOptionsStruct` — Type.

    LibGit2.DiffOptionsStruct

Matches the `git_diff_options` struct.

source
`Base.LibGit2.FetchHead` — Type.

    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
`Base.LibGit2.FetchOptions` — Type.

    LibGit2.FetchOptions

Matches the `git_fetch_options` struct.

source
`Base.LibGit2.GitBlob` — Type.

    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
`Base.LibGit2.GitCommit` — Type.

    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
`Base.LibGit2.GitHash` — Type.

    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
`Base.LibGit2.GitObject` — Type.

    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
`Base.LibGit2.GitRemote` — Type.

    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
`Base.LibGit2.GitRemoteAnon` — Function.

    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
`Base.LibGit2.GitRepo` — Type.

    LibGit2.GitRepo(path::AbstractString)

Opens a git repository at `path`.

source
`Base.LibGit2.GitRepoExt` — Function.

    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
`Base.LibGit2.GitShortHash` — Type.

    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
`Base.LibGit2.GitSignature` — Type.

    LibGit2.GitSignature

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

source
`Base.LibGit2.GitStatus` — Type.

    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
`Base.LibGit2.GitTag` — Type.

    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
`Base.LibGit2.GitTree` — Type.

    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
`Base.LibGit2.IndexEntry` — Type.

    LibGit2.IndexEntry

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

source
`Base.LibGit2.IndexTime` — Type.

    LibGit2.IndexTime

Matches the `git_index_time` struct.

source
`Base.LibGit2.MergeOptions` — Type.

    LibGit2.MergeOptions

Matches the `git_merge_options` struct.

source
`Base.LibGit2.ProxyOptions` — Type.

    LibGit2.ProxyOptions

Options for connecting through a proxy.

Matches the `git_proxy_options` struct.

source
`Base.LibGit2.PushOptions` — Type.

    LibGit2.PushOptions

Matches the `git_push_options` struct.

source
`Base.LibGit2.RebaseOperation` — Type.

    LibGit2.RebaseOperation

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

source
`Base.LibGit2.RebaseOptions` — Type.

    LibGit2.RebaseOptions

Matches the `git_rebase_options` struct.

source
`Base.LibGit2.RemoteCallbacks` — Type.

    LibGit2.RemoteCallbacks

Callback settings. Matches the `git_remote_callbacks` struct.

source
`Base.LibGit2.SSHCredentials` — Type.

SSH credentials type

source
`Base.LibGit2.SignatureStruct` — Type.

    LibGit2.SignatureStruct

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

source
`Base.LibGit2.StatusEntry` — Type.

    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
`Base.LibGit2.StatusOptions` — Type.

    LibGit2.StatusOptions

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

source
`Base.LibGit2.StrArrayStruct` — Type.

    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
`Base.LibGit2.TimeStruct` — Type.

    LibGit2.TimeStruct

Time in a signature. Matches the `git_time` struct.

source
`Base.LibGit2.UserPasswordCredentials` — Type.

Credentials that support only `user` and `password` parameters

source
`Base.LibGit2.add_fetch!` — Function.

    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
`Base.LibGit2.add_push!` — Function.

    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.authors` — Function.

    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.branch` — Function.

    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
`Base.LibGit2.checkout!` — Function.

    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
`Base.LibGit2.checkused!` — Function.

Checks if credentials were used

source

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

source
`Base.LibGit2.clone` — Function.

    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.commit` — Function.

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
`Base.LibGit2.create_branch` — Function.

    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
`Base.LibGit2.credentials_callback` — Function.

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 `pass`word 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
`Base.LibGit2.credentials_cb` — Function.

C function pointer for `credentials_callback`

source
`Base.LibGit2.default_signature` — Function.

Return signature object. Free it after use.

source
`Base.LibGit2.delete_branch` — Function.

    LibGit2.delete_branch(branch::GitReference)

Delete the branch pointed to by `branch`.

source
`Base.LibGit2.diff_files` — Function.

    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.fetch` — Function.

    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
`Base.LibGit2.fetch_refspecs` — Function.

    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
`Base.LibGit2.fetchhead_foreach_cb` — Function.

C function pointer for `fetchhead_foreach_callback`

source
`Base.LibGit2.ffmerge!` — Function.

Fastforward merge changes into current head

source
`Base.LibGit2.fullname` — Function.

    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
`Base.LibGit2.get_creds!` — Function.

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

source
`Base.LibGit2.gitdir` — Function.

    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.head` — Function.

    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_oid` — Function.

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

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

source
`Base.LibGit2.headname` — Function.

    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.init` — Function.

    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
`Base.LibGit2.is_ancestor_of` — Function.

    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.isbinary` — Function.

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.iscommit` — Function.

    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.isdiff` — Function.

    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.isdirty` — Function.

    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.isorphan` — Function.

    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
`Base.LibGit2.lookup_branch` — Function.

    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
`Base.LibGit2.mirror_callback` — Function.

Mirror callback function

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

source
`Base.LibGit2.mirror_cb` — Function.

C function pointer for `mirror_callback`

source
`Base.LibGit2.name` — Function.

    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
`Base.LibGit2.need_update` — Function.

    need_update(repo::GitRepo)

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

source
`Base.LibGit2.objtype` — Function.

    objtype(obj_type::Consts.OBJECT)

Returns the type corresponding to the enum value.

source
`Base.LibGit2.path` — Function.

    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.peel` — Function.

    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
`Base.LibGit2.posixpath` — Function.

    LibGit2.posixpath(path)

Standardise the path string `path` to use POSIX separators.

source
`Base.LibGit2.push` — Function.

    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
`Base.LibGit2.push_refspecs` — Function.

    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
`Base.LibGit2.read_tree!` — Function.

    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_list` — Function.

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

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

source
`Base.LibGit2.reftype` — Function.

    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.remotes` — Function.

    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.restore` — Function.

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

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

source
`Base.LibGit2.revcount` — 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 `Int`s - 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
`Base.LibGit2.set_remote_url` — Function.

    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
`Base.LibGit2.shortname` — Function.

    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.snapshot` — Function.

    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.status` — Function.

    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
`Base.LibGit2.tag_create` — Function.

    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
`Base.LibGit2.tag_delete` — Function.

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

Remove the git tag `tag` from the repository `repo`.

source
`Base.LibGit2.tag_list` — Function.

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

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

source
`Base.LibGit2.target` — Function.

    LibGit2.target(tag::GitTag)

The `GitHash` of the target object of `tag`.

source
`Base.LibGit2.treewalk` — Function.

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.upstream` — Function.

    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.url` — Function.

    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.with` — Function.

Resource management helper function

source
`Base.LibGit2.workdir` — Function.

    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