### [Functionality](#Functionality)
    -   `MERGE_SKIP_REUC`: do not write the REUC extension on the index resulting from the merge.
    -   `MERGE_NO_RECURSIVE`: if the commits being merged have multiple merge bases, use the first one, rather than trying to recursively merge the bases.
-   `rename_threshold`: how similar two files must to consider one a rename of the other. This is an integer that sets the percentage similarity. The default is 50.
-   `target_limit`: the maximum number of files to compare with to look for renames. The default is 200.
-   `metric`: optional custom function to use to determine the similarity between two files for rename detection.
-   `recursion_limit`: the upper limit on the number of merges of common ancestors to perform to try to build a new virtual merge base for the merge. The default is no limit. This field is only present on libgit2 versions newer than 0.24.0.
-   `default_driver`: the merge driver to use if both sides have changed. This field is only present on libgit2 versions newer than 0.25.0.
-   `file_favor`: how to handle conflicting file contents for the `text` driver.
    -   `MERGE_FILE_FAVOR_NORMAL`: if both sides of the merge have changes to a section, make a note of the conflict in the index which `git checkout` will use to create a merge file, which the user can then reference to resolve the conflicts. This is the default.
    -   `MERGE_FILE_FAVOR_OURS`: if both sides of the merge have changes to a section, use the version in the "ours" side of the merge in the index.


### [Functionality](#Functionality)
    -   `MERGE_FILE_FAVOR_THEIRS`: if both sides of the merge have changes to a section, use the version in the "theirs" side of the merge in the index.
    -   `MERGE_FILE_FAVOR_UNION`: if both sides of the merge have changes to a section, include each unique line from both sides in the file which is put into the index.
-   `file_flags`: guidelines for merging files.
```julia
LibGit2.ProxyOptions
```
Options for connecting through a proxy.
Matches the [`git_proxy_options`](https://libgit2.org/libgit2/#HEAD/type/git_proxy_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `proxytype`: an `enum` for the type of proxy to use. Defined in [`git_proxy_t`](https://libgit2.org/libgit2/#HEAD/type/git_proxy_t). The corresponding Julia enum is `GIT_PROXY` and has values:
    -   `PROXY_NONE`: do not attempt the connection through a proxy.
    -   `PROXY_AUTO`: attempt to figure out the proxy configuration from the git configuration.
    -   `PROXY_SPECIFIED`: connect using the URL given in the `url` field of this struct.
    Default is to auto-detect the proxy type.
-   `url`: the URL of the proxy.
-   `credential_cb`: a pointer to a callback function which will be called if the remote requires authentication to connect.


### [Functionality](#Functionality)
-   `certificate_cb`: a pointer to a callback function which will be called if certificate verification fails. This lets the user decide whether or not to keep connecting. If the function returns `1`, connecting will be allowed. If it returns `0`, the connection will not be allowed. A negative value can be used to return errors.
-   `payload`: the payload to be provided to the two callback functions.
**Examples**
```julia-repl
julia> fo = LibGit2.FetchOptions(
           proxy_opts = LibGit2.ProxyOptions(url = Cstring("https://my_proxy_url.com")))

julia> fetch(remote, "master", options=fo)
```
```julia
LibGit2.PushOptions
```
Matches the [`git_push_options`](https://libgit2.org/libgit2/#HEAD/type/git_push_options) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `parallelism`: if a pack file must be created, this variable sets the number of worker threads which will be spawned by the packbuilder. If `0`, the packbuilder will auto-set the number of threads to use. The default is `1`.
-   `callbacks`: the callbacks (e.g. for authentication with the remote) to use for the push.
-   `proxy_opts`: only relevant if the LibGit2 version is greater than or equal to `0.25.0`. Sets options for using a proxy to communicate with a remote. See [`ProxyOptions`](#LibGit2.ProxyOptions) for more information.
-   `custom_headers`: only relevant if the LibGit2 version is greater than or equal to `0.24.0`. Extra headers needed for the push operation.


### [Functionality](#Functionality)
```julia
LibGit2.RebaseOperation
```
Describes a single instruction/operation to be performed during the rebase. Matches the [`git_rebase_operation`](https://libgit2.org/libgit2/#HEAD/type/git_rebase_operation_t) struct.
The fields represent:
-   `optype`: the type of rebase operation currently being performed. The options are:
    -   `REBASE_OPERATION_PICK`: cherry-pick the commit in question.
    -   `REBASE_OPERATION_REWORD`: cherry-pick the commit in question, but rewrite its message using the prompt.
    -   `REBASE_OPERATION_EDIT`: cherry-pick the commit in question, but allow the user to edit the commit's contents and its message.
    -   `REBASE_OPERATION_SQUASH`: squash the commit in question into the previous commit. The commit messages of the two commits will be merged.
    -   `REBASE_OPERATION_FIXUP`: squash the commit in question into the previous commit. Only the commit message of the previous commit will be used.
    -   `REBASE_OPERATION_EXEC`: do not cherry-pick a commit. Run a command and continue if the command exits successfully.
-   `id`: the [`GitHash`](#LibGit2.GitHash) of the commit being worked on during this rebase step.
-   `exec`: in case `REBASE_OPERATION_EXEC` is used, the command to run during this step (for instance, running the test suite after each commit).
```julia
LibGit2.RebaseOptions
```
Matches the `git_rebase_options` struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.


### [Functionality](#Functionality)
-   `quiet`: inform other git clients helping with/working on the rebase that the rebase should be done "quietly". Used for interoperability. The default is `1`.
-   `inmemory`: start an in-memory rebase. Callers working on the rebase can go through its steps and commit any changes, but cannot rewind HEAD or update the repository. The [`workdir`](#LibGit2.workdir) will not be modified. Only present on libgit2 versions newer than or equal to 0.24.0.
-   `rewrite_notes_ref`: name of the reference to notes to use to rewrite the commit notes as the rebase is finished.
-   `merge_opts`: merge options controlling how the trees will be merged at each rebase step. Only present on libgit2 versions newer than or equal to 0.24.0.
-   `checkout_opts`: checkout options for writing files when initializing the rebase, stepping through it, and aborting it. See [`CheckoutOptions`](#LibGit2.CheckoutOptions) for more information.
```julia
LibGit2.RemoteCallbacks
```
Callback settings. Matches the [`git_remote_callbacks`](https://libgit2.org/libgit2/#HEAD/type/git_remote_callbacks) struct.
```julia
LibGit2.SignatureStruct
```
An action signature (e.g. for committers, taggers, etc). Matches the [`git_signature`](https://libgit2.org/libgit2/#HEAD/type/git_signature) struct.
The fields represent:
-   `name`: The full name of the committer or author of the commit.
-   `email`: The email at which the committer/author can be contacted.
-   `when`: a [`TimeStruct`](#LibGit2.TimeStruct) indicating when the commit was authored/committed into the repository.


### [Functionality](#Functionality)
```julia
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.
The fields represent:
-   `status`: contains the status flags for the file, indicating if it is current, or has been changed in some way in the index or work tree.
-   `head_to_index`: a pointer to a [`DiffDelta`](#LibGit2.DiffDelta) which encapsulates the difference(s) between the file as it exists in HEAD and in the index.
-   `index_to_workdir`: a pointer to a `DiffDelta` which encapsulates the difference(s) between the file as it exists in the index and in the [`workdir`](#LibGit2.workdir).
```julia
LibGit2.StatusOptions
```
Options to control how `git_status_foreach_ext()` will issue callbacks. Matches the [`git_status_opt_t`](https://libgit2.org/libgit2/#HEAD/type/git_status_opt_t) struct.
The fields represent:
-   `version`: version of the struct in use, in case this changes later. For now, always `1`.
-   `show`: a flag for which files to examine and in which order. The default is `Consts.STATUS_SHOW_INDEX_AND_WORKDIR`.
-   `flags`: flags for controlling any callbacks used in a status call.
-   `pathspec`: an array of paths to use for path-matching. The behavior of the path-matching will vary depending on the values of `show` and `flags`.
-   The `baseline` is the tree to be used for comparison to the working directory and index; defaults to HEAD.
```julia
LibGit2.StrArrayStruct
```


### [Functionality](#Functionality)
A LibGit2 representation of an array of strings. Matches the [`git_strarray`](https://libgit2.org/libgit2/#HEAD/type/git_strarray) struct.
When fetching data from LibGit2, a typical usage would look like:
```julia
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:
```julia
strs = String[...]
@check ccall(..., (Ptr{StrArrayStruct},), strs)
```
Note that no call to `free` is required as the data is allocated by Julia.
```julia
LibGit2.TimeStruct
```
Time in a signature. Matches the [`git_time`](https://libgit2.org/libgit2/#HEAD/type/git_time) struct.
```julia
addfile(cfg::GitConfig, path::AbstractString,
        level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_APP,
        repo::Union{GitRepo, Nothing} = nothing,
        force::Bool=false)
```
Add an existing git configuration file located at `path` to the current `GitConfig` `cfg`. If the file does not exist, it will be created.
-   `level` sets the git configuration priority level and is determined by
[`Consts.GIT_CONFIG`](#LibGit2.Consts.GIT_CONFIG).
-   `repo` is an optional repository to allow parsing of conditional includes.
-   If `force` is `false` and a configuration for the given priority level already exists,


### [Functionality](#Functionality)
`addfile` will error. If `force` is `true`, the existing configuration will be replaced by the one in the file at `path`.
```julia
add!(repo::GitRepo, files::AbstractString...; flags::Cuint = Consts.INDEX_ADD_DEFAULT)
add!(idx::GitIndex, files::AbstractString...; flags::Cuint = Consts.INDEX_ADD_DEFAULT)
```
Add all the files with paths specified by `files` to the index `idx` (or the index of the `repo`). If the file already exists, the index entry will be updated. If the file does not exist already, it will be newly added into the index. `files` may contain glob patterns which will be expanded and any matching files will be added (unless `INDEX_ADD_DISABLE_PATHSPEC_MATCH` is set, see below). If a file has been ignored (in `.gitignore` or in the config), it *will not* be added, *unless* it is already being tracked in the index, in which case it *will* be updated. The keyword argument `flags` is a set of bit-flags which control the behavior with respect to ignored files:
-   `Consts.INDEX_ADD_DEFAULT` - default, described above.
-   `Consts.INDEX_ADD_FORCE` - disregard the existing ignore rules and force addition of the file to the index even if it is already ignored.
-   `Consts.INDEX_ADD_CHECK_PATHSPEC` - cannot be used at the same time as `INDEX_ADD_FORCE`. Check that each file in `files` which exists on disk is not in the ignore list. If one of the files *is* ignored, the function will return `EINVALIDSPEC`.


### [Functionality](#Functionality)
-   `Consts.INDEX_ADD_DISABLE_PATHSPEC_MATCH` - turn off glob matching, and only add files to the index which exactly match the paths specified in `files`.
```julia
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.
**Examples**
```julia-repl
julia> LibGit2.add_fetch!(repo, remote, "upstream");

julia> LibGit2.fetch_refspecs(remote)
String["+refs/heads/*:refs/remotes/upstream/*"]
```
```julia
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.
**Examples**
```julia-repl
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"]
```
You may need to [`close`](../../base/io-network/#Base.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`](#LibGit2.push) to work.
```julia
LibGit2.addblob!(repo::GitRepo, path::AbstractString)
```
Read the file at `path` and adds it to the object database of `repo` as a loose blob. Return the [`GitHash`](#LibGit2.GitHash) of the resulting blob.
**Examples**
```julia
hash_str = string(commit_oid)
blob_file = joinpath(repo_path, ".git", "objects", hash_str[1:2], hash_str[3:end])
id = LibGit2.addblob!(repo, blob_file)
```


### [Functionality](#Functionality)
```julia
author(c::GitCommit)
```
Return the `Signature` of the author of the commit `c`. The author is the person who made changes to the relevant file(s). See also [`committer`](#LibGit2.committer).
```julia
authors(repo::GitRepo) -> Vector{Signature}
```
Return all authors of commits to the `repo` repository.
**Examples**
```julia
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)
```
```julia
branch(repo::GitRepo)
```
Equivalent to `git branch`. Create a new branch from the current HEAD.
```julia
branch!(repo::GitRepo, branch_name::AbstractString, commit::AbstractString=""; kwargs...)
```
Checkout a new git branch in the `repo` repository. `commit` is the [`GitHash`](#LibGit2.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.


### [Functionality](#Functionality)
-   `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>]`.
**Examples**
```julia
repo = LibGit2.GitRepo(repo_path)
LibGit2.branch!(repo, "new_branch", set_head=false)
```
```julia
checkout!(repo::GitRepo, commit::AbstractString=""; force::Bool=true)
```
Equivalent to `git checkout [-f] --detach <commit>`. Checkout the git commit `commit` (a [`GitHash`](#LibGit2.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.
**Examples**
```julia
repo = LibGit2.GitRepo(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)
```
```julia
clone(repo_url::AbstractString, repo_path::AbstractString, clone_opts::CloneOptions)
```
Clone the remote repository at `repo_url` (which can be a remote URL or a path on the local filesystem) to `repo_path` (which must be a path on the local filesystem). Options for the clone, such as whether to perform a bare clone or not, are set by [`CloneOptions`](#LibGit2.CloneOptions).
**Examples**


### [Functionality](#Functionality)
```julia
repo_url = "https://github.com/JuliaLang/Example.jl"
repo = LibGit2.clone(repo_url, "/home/me/projects/Example")
```
```julia
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{Cvoid}=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.
-   `credentials::Creds=nothing`: provides credentials and/or settings when authenticating against a private repository.
-   `callbacks::Callbacks=Callbacks()`: user provided callbacks and payloads.
Equivalent to `git clone [-b <branch>] [--bare] <repo_url> <repo_path>`.
**Examples**
```julia
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")
```


### [Functionality](#Functionality)
```julia
commit(repo::GitRepo, msg::AbstractString; kwargs...) -> GitHash
```
Wrapper around [`git_commit_create`](https://libgit2.org/libgit2/#HEAD/group/commit/git_commit_create). Create a commit in the repository `repo`. `msg` is the commit message. Return the OID of the new commit.
The keyword arguments are:
-   `refname::AbstractString=Consts.HEAD_FILE`: if not NULL, the name of the reference to update to point to the new commit. For example, `"HEAD"` will update the HEAD of the current branch. If the reference does not yet exist, it will be created.
-   `author::Signature = Signature(repo)` is a `Signature` containing information about the person who authored the commit.
-   `committer::Signature = Signature(repo)` is a `Signature` containing information about the person who committed the commit to the repository. Not necessarily the same as `author`, for instance if `author` emailed a patch to `committer` who committed it.
-   `tree_id::GitHash = GitHash()` is a git tree to use to create the commit, showing its ancestry and relationship with any other history. `tree` must belong to `repo`.
-   `parent_ids::Vector{GitHash}=GitHash[]` is a list of commits by [`GitHash`](#LibGit2.GitHash) to use as parent commits for the new one, and may be empty. A commit might have multiple parents if it is a merge commit, for example.
```julia
LibGit2.commit(rb::GitRebase, sig::GitSignature)
```
Commit the current patch to the rebase `rb`, using `sig` as the committer. Is silent if the commit has already been applied.


### [Functionality](#Functionality)
```julia
committer(c::GitCommit)
```
Return the `Signature` of the committer of the commit `c`. The committer is the person who committed the changes originally authored by the [`author`](#LibGit2.author), but need not be the same as the `author`, for example, if the `author` emailed a patch to a `committer` who committed it.
```julia
LibGit2.count(f::Function, walker::GitRevWalker; oid::GitHash=GitHash(), by::Cint=Consts.SORT_NONE, rev::Bool=false)
```
Using the [`GitRevWalker`](#LibGit2.GitRevWalker) `walker` to "walk" over every commit in the repository's history, find the number of commits which return `true` when `f` is applied to them. The keyword arguments are: \* `oid`: The [`GitHash`](#LibGit2.GitHash) of the commit to begin the walk from. The default is to use [`push_head!`](#LibGit2.push_head!) and therefore the HEAD commit and all its ancestors. \* `by`: The sorting method. The default is not to sort. Other options are to sort by topology (`LibGit2.Consts.SORT_TOPOLOGICAL`), to sort forwards in time (`LibGit2.Consts.SORT_TIME`, most ancient first) or to sort backwards in time (`LibGit2.Consts.SORT_REVERSE`, most recent first). \* `rev`: Whether to reverse the sorted order (for instance, if topological sorting is used).
**Examples**
```julia
cnt = LibGit2.with(LibGit2.GitRevWalker(repo)) do walker
    LibGit2.count((oid, repo)->(oid == commit_oid1), walker, oid=commit_oid1, by=LibGit2.Consts.SORT_TIME)
end
```


### [Functionality](#Functionality)
`LibGit2.count` finds the number of commits along the walk with a certain `GitHash` `commit_oid1`, starting the walk from that commit and moving forwards in time from it. Since the `GitHash` is unique to a commit, `cnt` will be `1`.
```julia
counthunks(blame::GitBlame)
```
Return the number of distinct "hunks" with a file. A hunk may contain multiple lines. A hunk is usually a piece of a file that was added/changed/removed together, for example, a function added to a source file or an inner loop that was optimized out of that function later.
```julia
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.
```julia
credential_callback(...) -> Cint
```
A LibGit2 credential callback function which provides different credential acquisition functionality w.r.t. a connection protocol. The `payload_ptr` is required to contain a `LibGit2.CredentialPayload` object which will keep track of state and settings.
The `allowed_types` contains a bitmask of `LibGit2.Consts.GIT_CREDTYPE` values specifying which authentication methods should be attempted.
Credential authentication is done in the following order (if supported):
-   SSH agent
-   SSH private/public key pair


### [Functionality](#Functionality)
-   Username/password plain text
If a user is presented with a credential prompt they can abort the prompt by typing `^D` (pressing the control key together with the `d` key).
**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, we will keep track of state using the payload.
For addition details see the LibGit2 guide on [authenticating against a server](https://libgit2.org/docs/guides/authentication/).
C function pointer for `credentials_callback`
Return signature object. Free it after use.
```julia
LibGit2.delete_branch(branch::GitReference)
```
Delete the branch pointed to by `branch`.
```julia
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.
Return only the *names* of the files which have changed, *not* their contents.
**Examples**


### [Functionality](#Functionality)
```julia
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>`.
```julia
entryid(te::GitTreeEntry)
```
Return the [`GitHash`](#LibGit2.GitHash) of the object to which `te` refers.
```julia
entrytype(te::GitTreeEntry)
```
Return the type of the object to which `te` refers. The result will be one of the types which [`objtype`](#LibGit2.objtype) returns, e.g. a `GitTree` or `GitBlob`.
```julia
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. See [`FetchOptions`](#LibGit2.FetchOptions) for more information.
-   `msg`: a message to insert into the reflogs.
```julia
fetch(repo::GitRepo; kwargs...)
```
Fetches updates from an upstream of the repository `repo`.
The keyword arguments are:


### [Functionality](#Functionality)
-   `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.
-   `credentials=nothing`: provides credentials and/or settings when authenticating against a private `remote`.
-   `callbacks=Callbacks()`: user provided callbacks and payloads.
Equivalent to `git fetch [<remoteurl>|<repo>] [<refspecs>]`.
```julia
fetchheads(repo::GitRepo) -> Vector{FetchHead}
```
Return the list of all the fetch heads for `repo`, each represented as a [`FetchHead`](#LibGit2.FetchHead), including their names, URLs, and merge statuses.
**Examples**
```julia-repl
julia> fetch_heads = LibGit2.fetchheads(repo);

julia> fetch_heads[1].name
"refs/heads/master"

julia> fetch_heads[1].ismerge
true

julia> fetch_heads[2].name
"refs/heads/test_branch"

julia> fetch_heads[2].ismerge
false
```
```julia
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.
**Examples**
```julia-repl
julia> remote = LibGit2.get(LibGit2.GitRemote, repo, "upstream");

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

julia> LibGit2.fetch_refspecs(remote)
String["+refs/heads/*:refs/remotes/upstream/*"]
```
C function pointer for `fetchhead_foreach_callback`


### [Functionality](#Functionality)
```julia
merge_base(repo::GitRepo, one::AbstractString, two::AbstractString) -> GitHash
```
Find a merge base (a common ancestor) between the commits `one` and `two`. `one` and `two` may both be in string form. Return the `GitHash` of the merge base.
```julia
merge!(repo::GitRepo; kwargs...) -> Bool
```
Perform a git merge on the repository `repo`, merging commits with diverging history into the current branch. Return `true` if the merge succeeded, `false` if not.
The keyword arguments are:
-   `committish::AbstractString=""`: Merge the named commit(s) in `committish`.
-   `branch::AbstractString=""`: Merge the branch `branch` and all its commits since it diverged from the current branch.
-   `fastforward::Bool=false`: If `fastforward` is `true`, only merge if the merge is a fast-forward (the current branch head is an ancestor of the commits to be merged), otherwise refuse to merge and return `false`. This is equivalent to the git CLI option `--ff-only`.
-   `merge_opts::MergeOptions=MergeOptions()`: `merge_opts` specifies options for the merge, such as merge strategy in case of conflicts.
-   `checkout_opts::CheckoutOptions=CheckoutOptions()`: `checkout_opts` specifies options for the checkout step.
Equivalent to `git merge [--ff-only] [<committish> | <branch>]`.
If you specify a `branch`, this must be done in reference format, since the string will be turned into a `GitReference`. For example, if you wanted to merge branch `branch_a`, you would call `merge!(repo, branch="refs/heads/branch_a")`.


### [Functionality](#Functionality)
```julia
merge!(repo::GitRepo, anns::Vector{GitAnnotated}; kwargs...) -> Bool
```
Merge changes from the annotated commits (captured as [`GitAnnotated`](#LibGit2.GitAnnotated) objects) `anns` into the HEAD of the repository `repo`. The keyword arguments are:
-   `merge_opts::MergeOptions = MergeOptions()`: options for how to perform the merge, including whether fastforwarding is allowed. See [`MergeOptions`](#LibGit2.MergeOptions) for more information.
-   `checkout_opts::CheckoutOptions = CheckoutOptions()`: options for how to perform the checkout. See [`CheckoutOptions`](#LibGit2.CheckoutOptions) for more information.
`anns` may refer to remote or local branch heads. Return `true` if the merge is successful, otherwise return `false` (for instance, if no merge is possible because the branches have no common ancestor).
**Examples**
```julia
upst_ann = LibGit2.GitAnnotated(repo, "branch/a")

# merge the branch in
LibGit2.merge!(repo, [upst_ann])
```
```julia
merge!(repo::GitRepo, anns::Vector{GitAnnotated}, fastforward::Bool; kwargs...) -> Bool
```
Merge changes from the annotated commits (captured as [`GitAnnotated`](#LibGit2.GitAnnotated) objects) `anns` into the HEAD of the repository `repo`. If `fastforward` is `true`, *only* a fastforward merge is allowed. In this case, if conflicts occur, the merge will fail. Otherwise, if `fastforward` is `false`, the merge may produce a conflict file which the user will need to resolve.
The keyword arguments are:


### [Functionality](#Functionality)
-   `merge_opts::MergeOptions = MergeOptions()`: options for how to perform the merge, including whether fastforwarding is allowed. See [`MergeOptions`](#LibGit2.MergeOptions) for more information.
-   `checkout_opts::CheckoutOptions = CheckoutOptions()`: options for how to perform the checkout. See [`CheckoutOptions`](#LibGit2.CheckoutOptions) for more information.
`anns` may refer to remote or local branch heads. Return `true` if the merge is successful, otherwise return `false` (for instance, if no merge is possible because the branches have no common ancestor).
**Examples**
```julia
upst_ann_1 = LibGit2.GitAnnotated(repo, "branch/a")

# merge the branch in, fastforward
LibGit2.merge!(repo, [upst_ann_1], true)

# merge conflicts!
upst_ann_2 = LibGit2.GitAnnotated(repo, "branch/b")
# merge the branch in, try to fastforward
LibGit2.merge!(repo, [upst_ann_2], true) # will return false
LibGit2.merge!(repo, [upst_ann_2], false) # will return true
```
```julia
ffmerge!(repo::GitRepo, ann::GitAnnotated)
```
Fastforward merge changes into current HEAD. This is only possible if the commit referred to by `ann` is descended from the current HEAD (e.g. if pulling changes from a remote branch which is simply ahead of the local branch tip).
```julia
LibGit2.fullname(ref::GitReference)
```
Return the name of the reference pointed to by the symbolic reference `ref`. If `ref` is not a symbolic reference, return an empty string.
```julia
features()
```


### [Functionality](#Functionality)
Return a list of git features the current version of libgit2 supports, such as threading or using HTTPS or SSH.
```julia
filename(te::GitTreeEntry)
```
Return the filename of the object on disk to which `te` refers.
```julia
filemode(te::GitTreeEntry) -> Cint
```
Return the UNIX filemode of the object on disk to which `te` refers as an integer.
```julia
LibGit2.gitdir(repo::GitRepo)
```
Return 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`](#LibGit2.workdir), [`path`](#LibGit2.path).
```julia
LibGit2.git_url(; kwargs...) -> String
```
Create a string based upon the URL components provided. When the `scheme` keyword is not provided the URL produced will use the alternative [scp-like syntax](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a).
**Keywords**
-   `scheme::AbstractString=""`: the URL scheme which identifies the protocol to be used. For HTTP use "http", SSH use "ssh", etc. When `scheme` is not provided the output format will be "ssh" but using the scp-like syntax.
-   `username::AbstractString=""`: the username to use in the output if provided.
-   `password::AbstractString=""`: the password to use in the output if provided.
-   `host::AbstractString=""`: the hostname to use in the output. A hostname is required to be specified.


### [Functionality](#Functionality)
-   `port::Union{AbstractString,Integer}=""`: the port number to use in the output if provided. Cannot be specified when using the scp-like syntax.
-   `path::AbstractString=""`: the path to use in the output if provided.
Avoid using passwords in URLs. Unlike the credential objects, Julia is not able to securely zero or destroy the sensitive data after use and the password may remain in memory; possibly to be exposed by an uninitialized memory.
**Examples**
```julia-repl
julia> LibGit2.git_url(username="git", host="github.com", path="JuliaLang/julia.git")
"git@github.com:JuliaLang/julia.git"

julia> LibGit2.git_url(scheme="https", host="github.com", path="/JuliaLang/julia.git")
"https://github.com/JuliaLang/julia.git"

julia> LibGit2.git_url(scheme="ssh", username="git", host="github.com", port=2222, path="JuliaLang/julia.git")
"ssh://git@github.com:2222/JuliaLang/julia.git"
```
```julia
@githash_str -> AbstractGitHash
```
Construct a git hash object from the given string, returning a `GitShortHash` if the string is shorter than 40 hexadecimal digits, otherwise a `GitHash`.
**Examples**
```julia-repl
julia> LibGit2.githash"d114feb74ce633"
GitShortHash("d114feb74ce633")

julia> LibGit2.githash"d114feb74ce63307afe878a5228ad014e0289a85"
GitHash("d114feb74ce63307afe878a5228ad014e0289a85")
```
```julia
LibGit2.head(repo::GitRepo) -> GitReference
```
Return a `GitReference` to the current HEAD of `repo`.
```julia
head(pkg::AbstractString) -> String
```
Return current HEAD [`GitHash`](#LibGit2.GitHash) of the `pkg` repo as a string.


### [Functionality](#Functionality)
```julia
LibGit2.head!(repo::GitRepo, ref::GitReference) -> GitReference
```
Set the HEAD of `repo` to the object pointed to by `ref`.
```julia
LibGit2.head_oid(repo::GitRepo) -> GitHash
```
Lookup the object id of the current HEAD of git repository `repo`.
```julia
LibGit2.headname(repo::GitRepo)
```
Lookup the name of the current HEAD of git repository `repo`. If `repo` is currently detached, return the name of the HEAD it's detached from.
```julia
LibGit2.init(path::AbstractString, bare::Bool=false) -> GitRepo
```
Open 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.
```julia
is_ancestor_of(a::AbstractString, b::AbstractString, repo::GitRepo) -> Bool
```
Return `true` if `a`, a [`GitHash`](#LibGit2.GitHash) in string form, is an ancestor of `b`, a [`GitHash`](#LibGit2.GitHash) in string form.
**Examples**
```julia-repl
julia> repo = 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
```
```julia
isbinary(blob::GitBlob) -> Bool
```
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.
```julia
iscommit(id::AbstractString, repo::GitRepo) -> Bool
```


### [Functionality](#Functionality)
Check if commit `id` (which is a [`GitHash`](#LibGit2.GitHash) in string form) is in the repository.
**Examples**
```julia-repl
julia> repo = 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
```
```julia
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.
**Examples**
```julia
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>]`.
```julia
LibGit2.isdirty(repo::GitRepo, pathspecs::AbstractString=""; cached::Bool=false) -> Bool
```
Check 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.
**Examples**
```julia
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
```


### [Functionality](#Functionality)
Equivalent to `git diff-index HEAD [-- <pathspecs>]`.
```julia
LibGit2.isorphan(repo::GitRepo)
```
Check if the current branch is an "orphan" branch, i.e. has no commits. The first commit to this branch will have no parents.
```julia
isset(val::Integer, flag::Integer)
```
Test whether the bits of `val` indexed by `flag` are set (`1`) or unset (`0`).
```julia
iszero(id::GitHash) -> Bool
```
Determine whether all hexadecimal digits of the given [`GitHash`](#LibGit2.GitHash) are zero.
```julia
lookup_branch(repo::GitRepo, branch_name::AbstractString, remote::Bool=false) -> Union{GitReference, Nothing}
```
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.
Return either a `GitReference` to the requested branch if it exists, or [`nothing`](../../base/constants/#Core.nothing) if not.
```julia
LibGit2.map(f::Function, walker::GitRevWalker; oid::GitHash=GitHash(), range::AbstractString="", by::Cint=Consts.SORT_NONE, rev::Bool=false)
```


### [Functionality](#Functionality)
Using the [`GitRevWalker`](#LibGit2.GitRevWalker) `walker` to "walk" over every commit in the repository's history, apply `f` to each commit in the walk. The keyword arguments are: \* `oid`: The [`GitHash`](#LibGit2.GitHash) of the commit to begin the walk from. The default is to use [`push_head!`](#LibGit2.push_head!) and therefore the HEAD commit and all its ancestors. \* `range`: A range of `GitHash`s in the format `oid1..oid2`. `f` will be applied to all commits between the two. \* `by`: The sorting method. The default is not to sort. Other options are to sort by topology (`LibGit2.Consts.SORT_TOPOLOGICAL`), to sort forwards in time (`LibGit2.Consts.SORT_TIME`, most ancient first) or to sort backwards in time (`LibGit2.Consts.SORT_REVERSE`, most recent first). \* `rev`: Whether to reverse the sorted order (for instance, if topological sorting is used).
**Examples**
```julia
oids = LibGit2.with(LibGit2.GitRevWalker(repo)) do walker
    LibGit2.map((oid, repo)->string(oid), walker, by=LibGit2.Consts.SORT_TIME)
end
```
Here, `LibGit2.map` visits each commit using the `GitRevWalker` and finds its `GitHash`.
Mirror callback function
Function sets `+refs/*:refs/*` refspecs and `mirror` flag for remote reference.
C function pointer for `mirror_callback`
```julia
message(c::GitCommit, raw::Bool=false)
```
Return the commit message describing the changes made in commit `c`. If `raw` is `false`, return a slightly "cleaned up" message (which has any leading newlines removed). If `raw` is `true`, the message is not stripped of any such newlines.


### [Functionality](#Functionality)
```julia
merge_analysis(repo::GitRepo, anns::Vector{GitAnnotated}) -> analysis, preference
```
Run analysis on the branches pointed to by the annotated branch tips `anns` and determine under what circumstances they can be merged. For instance, if `anns[1]` is simply an ancestor of `ann[2]`, then `merge_analysis` will report that a fast-forward merge is possible.
Return two outputs, `analysis` and `preference`. `analysis` has several possible values: \* `MERGE_ANALYSIS_NONE`: it is not possible to merge the elements of `anns`. \* `MERGE_ANALYSIS_NORMAL`: a regular merge, when HEAD and the commits that the user wishes to merge have all diverged from a common ancestor. In this case the changes have to be resolved and conflicts may occur. \* `MERGE_ANALYSIS_UP_TO_DATE`: all the input commits the user wishes to merge can be reached from HEAD, so no merge needs to be performed. \* `MERGE_ANALYSIS_FASTFORWARD`: the input commit is a descendant of HEAD and so no merge needs to be performed - instead, the user can simply checkout the input commit(s). \* `MERGE_ANALYSIS_UNBORN`: the HEAD of the repository refers to a commit which does not exist. It is not possible to merge, but it may be possible to checkout the input commits. `preference` also has several possible values: \* `MERGE_PREFERENCE_NONE`: the user has no preference. \* `MERGE_PREFERENCE_NO_FASTFORWARD`: do not allow any fast-forward merges. \* `MERGE_PREFERENCE_FASTFORWARD_ONLY`: allow only fast-forward merges and no other type (which may introduce conflicts). `preference` can be controlled through the repository or global git configuration.


### [Functionality](#Functionality)
```julia
LibGit2.name(ref::GitReference)
```
Return the full name of `ref`.
```julia
name(rmt::GitRemote)
```
Get the name of a remote repository, for instance `"origin"`. If the remote is anonymous (see [`GitRemoteAnon`](#LibGit2.GitRemoteAnon)) the name will be an empty string `""`.
**Examples**
```julia-repl
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"
```
```julia
LibGit2.name(tag::GitTag)
```
The name of `tag` (e.g. `"v0.5"`).
```julia
need_update(repo::GitRepo)
```
Equivalent to `git update-index`. Return `true` if `repo` needs updating.
```julia
objtype(obj_type::Consts.OBJECT)
```
Return the type corresponding to the enum value.
```julia
LibGit2.path(repo::GitRepo)
```
Return 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`](#LibGit2.gitdir), [`workdir`](#LibGit2.workdir).
```julia
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`](#LibGit2.GitTag) is obtained.
-   A `GitTag` will be peeled to the object it references.


### [Functionality](#Functionality)
-   A [`GitCommit`](#LibGit2.GitCommit) will be peeled to a [`GitTree`](#LibGit2.GitTree).
Only annotated tags can be peeled to `GitTag` objects. Lightweight tags (the default) are references under `refs/tags/` which point directly to `GitCommit` objects.
```julia
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`.
```julia
LibGit2.posixpath(path)
```
Standardise the path string `path` to use POSIX separators.
```julia
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. See [`PushOptions`](#LibGit2.PushOptions) for more information.
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!`](#LibGit2.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"])`.
```julia
push(repo::GitRepo; kwargs...)
```
Pushes updates to an upstream of `repo`.


### [Functionality](#Functionality)
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.
-   `credentials=nothing`: provides credentials and/or settings when authenticating against a private `remote`.
-   `callbacks=Callbacks()`: user provided callbacks and payloads.
Equivalent to `git push [<remoteurl>|<repo>] [<refspecs>]`.
```julia
LibGit2.push!(w::GitRevWalker, cid::GitHash)
```
Start the [`GitRevWalker`](#LibGit2.GitRevWalker) `walker` at commit `cid`. This function can be used to apply a function to all commits since a certain year, by passing the first commit of that year as `cid` and then passing the resulting `w` to [`LibGit2.map`](#LibGit2.map).
```julia
LibGit2.push_head!(w::GitRevWalker)
```
Push the HEAD commit and its ancestors onto the [`GitRevWalker`](#LibGit2.GitRevWalker) `w`. This ensures that HEAD and all its ancestor commits will be encountered during the walk.
```julia
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.
**Examples**


### [Functionality](#Functionality)
```julia-repl
julia> remote = LibGit2.get(LibGit2.GitRemote, repo, "upstream");

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

julia> close(remote);

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

julia> LibGit2.push_refspecs(remote)
String["refs/heads/master"]
```
```julia
raw(id::GitHash) -> Vector{UInt8}
```
Obtain the raw bytes of the [`GitHash`](#LibGit2.GitHash) as a vector of length 20.
```julia
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.
```julia
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:
```julia
git rebase --merge [<upstream>]
if [ -d ".git/rebase-merge" ]; then
    git rebase --abort
fi
```
```julia
LibGit2.ref_list(repo::GitRepo) -> Vector{String}
```
Get a list of all reference names in the `repo` repository.


### [Functionality](#Functionality)
```julia
LibGit2.reftype(ref::GitReference) -> Cint
```
Return 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
```julia
LibGit2.remotes(repo::GitRepo)
```
Return a vector of the names of the remotes of `repo`.
```julia
remove!(repo::GitRepo, files::AbstractString...)
remove!(idx::GitIndex, files::AbstractString...)
```
Remove all the files with paths specified by `files` in the index `idx` (or the index of the `repo`).
```julia
reset(val::Integer, flag::Integer)
```
Unset the bits of `val` indexed by `flag`, returning them to `0`.
```julia
reset!(payload, [config]) -> CredentialPayload
```
Reset the `payload` state back to the initial values so that it can be used again within the credential callback. If a `config` is provided the configuration will also be updated.
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>...
```julia
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.
**Examples**


### [Functionality](#Functionality)
```julia
# fetch changes
LibGit2.fetch(repo)
isfile(joinpath(repo_path, our_file)) # will be false

# fastforward merge the changes
LibGit2.merge!(repo, fastforward=true)

# because there was not any file locally, but there is
# a file remotely, we need to reset the branch
head_oid = LibGit2.head_oid(repo)
new_head = LibGit2.reset!(repo, head_oid, LibGit2.Consts.RESET_HARD)
```
In this example, the remote which is being fetched from *does* have a file called `our_file` in its index, which is why we must reset.
Equivalent to `git reset [--soft | --mixed | --hard] <id>`.
**Examples**
```julia
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)
```
```julia
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`](#LibGit2.snapshot) function.
```julia
LibGit2.revcount(repo::GitRepo, commit1::AbstractString, commit2::AbstractString)
```


### [Functionality](#Functionality)
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>`.
**Examples**
```julia
repo = LibGit2.GitRepo(repo_path)
repo_file = open(joinpath(repo_path, test_file), "a")
println(repo_file, "hello world")
flush(repo_file)
LibGit2.add!(repo, test_file)
commit_oid1 = LibGit2.commit(repo, "commit 1")
println(repo_file, "hello world again")
flush(repo_file)
LibGit2.add!(repo, test_file)
commit_oid2 = LibGit2.commit(repo, "commit 2")
LibGit2.revcount(repo, string(commit_oid1), string(commit_oid2))
```
This will return `(-1, 0)`.
```julia
set_remote_url(repo::GitRepo, remote_name, url)
set_remote_url(repo::String, remote_name, url)
```
Set both the fetch and push `url` for `remote_name` for the [`GitRepo`](#LibGit2.GitRepo) or the git repository located at `path`. Typically git repos use `"origin"` as the remote name.
**Examples**
```julia
repo_path = joinpath(tempdir(), "Example")
repo = LibGit2.init(repo_path)
LibGit2.set_remote_url(repo, "upstream", "https://github.com/JuliaLang/Example.jl")
LibGit2.set_remote_url(repo_path, "upstream2", "https://github.com/JuliaLang/Example2.jl")
```


### [Functionality](#Functionality)
```julia
LibGit2.shortname(ref::GitReference)
```
Return a shortened version of the name of `ref` that's "human-readable".
```julia-repl
julia> repo = GitRepo(path_to_repo);

julia> branch_ref = LibGit2.head(repo);

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

julia> LibGit2.shortname(branch_ref)
"master"
```
```julia
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`](#LibGit2.restore) to return the repository to the snapshotted state.
```julia
LibGit2.split_cfg_entry(ce::LibGit2.ConfigEntry) -> Tuple{String,String,String,String}
```
Break the `ConfigEntry` up to the following pieces: section, subsection, name, and value.
**Examples**
Given the git configuration file containing:
```julia
[credential "https://example.com"]
    username = me
```
The `ConfigEntry` would look like the following:
```julia-repl
julia> entry
ConfigEntry("credential.https://example.com.username", "me")

julia> LibGit2.split_cfg_entry(entry)
("credential", "https://example.com", "username", "me")
```
Refer to the [git config syntax documentation](https://git-scm.com/docs/git-config#_syntax) for more details.
```julia
LibGit2.status(repo::GitRepo, path::String) -> Union{Cuint, Cvoid}
```
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.


### [Functionality](#Functionality)
```julia
stage(ie::IndexEntry) -> Cint
```
Get the stage number of `ie`. The stage number `0` represents the current state of the working tree, but other numbers can be used in the case of a merge conflict. In such a case, the various stage numbers on an `IndexEntry` describe which side(s) of the conflict the current state of the file belongs to. Stage `0` is the state before the attempted merge, stage `1` is the changes which have been made locally, stages `2` and larger are for changes from other branches (for instance, in the case of a multi-branch "octopus" merge, stages `2`, `3`, and `4` might be used).
```julia
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.
```julia
LibGit2.tag_delete(repo::GitRepo, tag::AbstractString)
```
Remove the git tag `tag` from the repository `repo`.
```julia
LibGit2.tag_list(repo::GitRepo) -> Vector{String}
```
Get a list of all tags in the git repository `repo`.
```julia
LibGit2.target(tag::GitTag)
```
The `GitHash` of the target object of `tag`.
```julia
toggle(val::Integer, flag::Integer)
```
Flip the bits of `val` indexed by `flag`, so that if a bit is `0` it will be `1` after the toggle, and vice-versa.
```julia
transact(f::Function, repo::GitRepo)
```


### [Functionality](#Functionality)
Apply function `f` to the git repository `repo`, taking a [`snapshot`](#LibGit2.snapshot) before applying `f`. If an error occurs within `f`, `repo` will be returned to its snapshot state using [`restore`](#LibGit2.restore). The error which occurred will be rethrown, but the state of `repo` will not be corrupted.
```julia
treewalk(f, tree::GitTree, post::Bool=false)
```
Traverse the entries in `tree` and its subtrees in post or pre order. Preorder means beginning at the root and then traversing the leftmost subtree (and recursively on down through that subtree's leftmost subtrees) and moving right through the subtrees. Postorder means beginning at the bottom of the leftmost subtree, traversing upwards through it, then traversing the next right subtree (again beginning at the bottom) and finally visiting the tree root last of all.
The function parameter `f` should have following signature:
```julia
(String, GitTreeEntry) -> Cint
```
A negative value returned from `f` stops the tree walk. A positive value means that the entry will be skipped if `post` is `false`.
```julia
upstream(ref::GitReference) -> Union{GitReference, Nothing}
```
Determine if the branch containing `ref` has a specified upstream branch.
Return either a `GitReference` to the upstream branch if it exists, or [`nothing`](../../base/constants/#Core.nothing) if the requested branch does not have an upstream counterpart.
```julia
update!(repo::GitRepo, files::AbstractString...)
update!(idx::GitIndex, files::AbstractString...)
```


### [Functionality](#Functionality)
Update all the files with paths specified by `files` in the index `idx` (or the index of the `repo`). Match the state of each file in the index with the current state on disk, removing it if it has been removed on disk, or updating its entry in the object database.
```julia
url(rmt::GitRemote)
```
Get the fetch URL of a remote git repository.
**Examples**
```julia-repl
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"
```
```julia
version() -> VersionNumber
```
Return the version of libgit2 in use, as a [`VersionNumber`](../../manual/strings/#man-version-number-literals).
```julia
with(f::Function, obj)
```
Resource management helper function. Applies `f` to `obj`, making sure to call `close` on `obj` after `f` successfully returns or throws an error. Ensures that allocated git resources are finalized as soon as they are no longer needed.
```julia
with_warn(f::Function, ::Type{T}, args...)
```
Resource management helper function. Apply `f` to `args`, first constructing an instance of type `T` from `args`. Makes sure to call `close` on the resulting object after `f` successfully returns or throws an error. Ensures that allocated git resources are finalized as soon as they are no longer needed. If an error is thrown by `f`, a warning is shown containing the error.
```julia
LibGit2.workdir(repo::GitRepo)
```


### [Functionality](#Functionality)
Return the location of the working directory of `repo`. This will throw an error for bare repositories.
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`](#LibGit2.gitdir), [`path`](#LibGit2.path).
```julia
(::Type{T})(te::GitTreeEntry) where T<:GitObject
```
Get the git object to which `te` refers and return it as its actual type (the type [`entrytype`](#LibGit2.entrytype) would show), for instance a `GitBlob` or `GitTag`.
**Examples**
```julia
tree = LibGit2.GitTree(repo, "HEAD^{tree}")
tree_entry = tree[1]
blob = LibGit2.GitBlob(tree_entry)
```
Credential that support only `user` and `password` parameters
SSH credential type
```julia
isfilled(cred::AbstractCredential) -> Bool
```
Verifies that a credential is ready for use in authentication.
Caches credential information for re-use
```julia
LibGit2.CredentialPayload
```
Retains the state between multiple calls to the credential callback for the same URL. A `CredentialPayload` instance is expected to be `reset!` whenever it will be used with a different URL.
```julia
approve(payload::CredentialPayload; shred::Bool=true) -> Nothing
```
Store the `payload` credential for re-use in a future authentication. Should only be called when authentication was successful.


### [Functionality](#Functionality)
The `shred` keyword controls whether sensitive information in the payload credential field should be destroyed. Should only be set to `false` during testing.
```julia
reject(payload::CredentialPayload; shred::Bool=true) -> Nothing
```
Discard the `payload` credential from begin re-used in future authentication. Should only be called when authentication was unsuccessful.
The `shred` keyword controls whether sensitive information in the payload credential field should be destroyed. Should only be set to `false` during testing.
Priority level of a config file.
These priority levels correspond to the natural escalation logic (from higher to lower) when searching for config entries in git.
-   `CONFIG_LEVEL_DEFAULT` - Open the global, XDG and system configuration files if any available.
-   `CONFIG_LEVEL_PROGRAMDATA` - System-wide on Windows, for compatibility with portable git
-   `CONFIG_LEVEL_SYSTEM` - System-wide configuration file; `/etc/gitconfig` on Linux systems
-   `CONFIG_LEVEL_XDG` - XDG compatible configuration file; typically `~/.config/git/config`
-   `CONFIG_LEVEL_GLOBAL` - User-specific configuration file (also called Global configuration file); typically `~/.gitconfig`
-   `CONFIG_LEVEL_LOCAL` - Repository specific configuration file; `$WORK_DIR/.git/config` on non-bare repos
-   `CONFIG_LEVEL_APP` - Application specific configuration file; freely defined by applications
-   `CONFIG_HIGHEST_LEVEL` - Represents the highest level available config file (i.e. the most specific config file available that actually is loaded)


### [Functionality](#Functionality)
------------------------------------------------------------------------


# Dynamic Linker · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/Libdl/
The Libdl module in Julia provides specialized and lower-level facilities for dynamic linking with shared libraries. While Julia inherently supports linking to runtime shared libraries through the `ccall` intrinsic, `Libdl` extends this capability by offering additional, more granular control. It enables users to search for shared libraries both in memory and the filesystem, manually load them with specific runtime linker options, and look up library symbols as low-level pointers.


# [Dynamic Linker](#Dynamic-Linker)
```julia
dlopen(libfile::AbstractString [, flags::Integer]; throw_error:Bool = true)
```
Load a shared library, returning an opaque handle.
The extension given by the constant `dlext` (`.so`, `.dll`, or `.dylib`) can be omitted from the `libfile` string, as it is automatically appended if needed. If `libfile` is not an absolute path name, then the paths in the array `DL_LOAD_PATH` are searched for `libfile`, followed by the system load path.
The optional flags argument is a bitwise-or of zero or more of `RTLD_LOCAL`, `RTLD_GLOBAL`, `RTLD_LAZY`, `RTLD_NOW`, `RTLD_NODELETE`, `RTLD_NOLOAD`, `RTLD_DEEPBIND`, and `RTLD_FIRST`. These are converted to the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default flags are platform specific. On MacOS the default `dlopen` flags are `RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL` while on other platforms the defaults are `RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL`. An important usage of these flags is to specify non default behavior for when the dynamic library loader binds library references to exported symbols and if the bound references are put into process local or global scope. For instance `RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL` allows the library's symbols to be available for usage in other shared libraries, addressing situations where there are dependencies between shared libraries.


# [Dynamic Linker](#Dynamic-Linker)
If the library cannot be found, this method throws an error, unless the keyword argument `throw_error` is set to `false`, in which case this method returns `nothing`.
From Julia 1.6 on, this method replaces paths starting with `@executable_path/` with the path to the Julia executable, allowing for relocatable relative-path loads. In Julia 1.5 and earlier, this only worked on macOS.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L82-L113)
```julia
dlopen_e(libfile::AbstractString [, flags::Integer])
```
Similar to [`dlopen`](#Base.Libc.Libdl.dlopen), except returns `C_NULL` instead of raising errors. This method is now deprecated in favor of `dlopen(libfile::AbstractString [, flags::Integer]; throw_error=false)`.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L154-L159)
```julia
RTLD_DEEPBIND
RTLD_FIRST
RTLD_GLOBAL
RTLD_LAZY
RTLD_LOCAL
RTLD_NODELETE
RTLD_NOLOAD
RTLD_NOW
```
Enum constant for [`dlopen`](#Base.Libc.Libdl.dlopen). See your platform man page for details, if applicable.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L33-L45)
```julia
dlsym(handle, sym; throw_error::Bool = true)
```
Look up a symbol from a shared library handle, return callable function pointer on success.
If the symbol cannot be found, this method throws an error, unless the keyword argument `throw_error` is set to `false`, in which case this method returns `nothing`.


# [Dynamic Linker](#Dynamic-Linker)
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L51-L58)
```julia
dlsym_e(handle, sym)
```
Look up a symbol from a shared library handle, silently return `C_NULL` on lookup failure. This method is now deprecated in favor of `dlsym(handle, sym; throw_error=false)`.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L72-L77)
```julia
dlclose(handle)
```
Close shared library referenced by handle.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L162-L166)
```julia
dlclose(::Nothing)
```
For the very common pattern usage pattern of
```julia
try
    hdl = dlopen(library_name)
    ... do something
finally
    dlclose(hdl)
end
```
We define a `dlclose()` method that accepts a parameter of type `Nothing`, so that user code does not have to change its behavior for the case that `library_name` was not found.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L171-L186)
```julia
dlext
```
File extension for dynamic libraries (e.g. dll, dylib, so) on the current platform.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L258-L262)
```julia
dllist()
```
Return the paths of dynamic libraries currently loaded in a `Vector{String}`.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L289-L293)
```julia
dlpath(handle::Ptr{Cvoid})
```


# [Dynamic Linker](#Dynamic-Linker)
Given a library `handle` from `dlopen`, return the full path.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L220-L224)
```julia
dlpath(libname::Union{AbstractString, Symbol})
```
Get the full path of the library `libname`.
**Examples**
```julia-repl
julia> dlpath("libjulia")
```
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L232-L241)
```julia
find_library(names [, locations])
```
Searches for the first library in `names` in the paths in the `locations` list, `DL_LOAD_PATH`, or system library paths (in that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a `global const` and used as the library name in future `ccall`'s. On failure, it returns the empty string.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L190-L198)
```julia
DL_LOAD_PATH
```
When calling [`dlopen`](#Base.Libc.Libdl.dlopen), the paths in this list will be searched first, in order, before searching the system locations for a valid library handle.
[source](https://github.com/JuliaLang/julia/blob/9615af0f269df4d371b8010e9507ed5bae86103b/base/libdl.jl#L14-L19)
------------------------------------------------------------------------


# Linear Algebra · The Julia Language
Source: https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/


# [Linear Algebra](#man-linalg)
In addition to (and as part of) its support for multi-dimensional arrays, Julia provides native implementations of many common and useful linear algebra operations which can be loaded with `using LinearAlgebra`. Basic operations, such as [`tr`](#LinearAlgebra.tr), [`det`](#LinearAlgebra.det), and [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D) are all supported:
```julia-repl
julia> A = [1 2 3; 4 1 6; 7 8 1]
3×3 Matrix{Int64}:
 1  2  3
 4  1  6
 7  8  1

julia> tr(A)
3

julia> det(A)
104.0

julia> inv(A)
3×3 Matrix{Float64}:
 -0.451923   0.211538    0.0865385
  0.365385  -0.192308    0.0576923
  0.240385   0.0576923  -0.0673077
```
As well as other useful operations, such as finding eigenvalues or eigenvectors:
```julia-repl
julia> A = [-4. -17.; 2. 2.]
2×2 Matrix{Float64}:
 -4.0  -17.0
  2.0    2.0

julia> eigvals(A)
2-element Vector{ComplexF64}:
 -1.0 - 5.0im
 -1.0 + 5.0im

julia> eigvecs(A)
2×2 Matrix{ComplexF64}:
  0.945905-0.0im        0.945905+0.0im
 -0.166924+0.278207im  -0.166924-0.278207im
```
In addition, Julia provides many [factorizations](#man-linalg-factorizations) which can be used to speed up problems such as linear solve or matrix exponentiation by pre-factorizing a matrix into a form more amenable (for performance or memory reasons) to the problem. See the documentation on [`factorize`](#LinearAlgebra.factorize) for more information. As an example:


# [Linear Algebra](#man-linalg)
```julia-repl
julia> A = [1.5 2 -4; 3 -1 -6; -10 2.3 4]
3×3 Matrix{Float64}:
   1.5   2.0  -4.0
   3.0  -1.0  -6.0
 -10.0   2.3   4.0

julia> factorize(A)
LU{Float64, Matrix{Float64}, Vector{Int64}}
L factor:
3×3 Matrix{Float64}:
  1.0    0.0       0.0
 -0.15   1.0       0.0
 -0.3   -0.132196  1.0
U factor:
3×3 Matrix{Float64}:
 -10.0  2.3     4.0
   0.0  2.345  -3.4
   0.0  0.0    -5.24947
```
Since `A` is not Hermitian, symmetric, triangular, tridiagonal, or bidiagonal, an LU factorization may be the best we can do. Compare with:
```julia-repl
julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5]
3×3 Matrix{Float64}:
  1.5   2.0  -4.0
  2.0  -1.0  -3.0
 -4.0  -3.0   5.0

julia> factorize(B)
BunchKaufman{Float64, Matrix{Float64}, Vector{Int64}}
D factor:
3×3 Tridiagonal{Float64, Vector{Float64}}:
 -1.64286   0.0   ⋅
  0.0      -2.8  0.0
   ⋅        0.0  5.0
U factor:
3×3 UnitUpperTriangular{Float64, Matrix{Float64}}:
 1.0  0.142857  -0.8
  ⋅   1.0       -0.6
  ⋅    ⋅         1.0
permutation:
3-element Vector{Int64}:
 1
 2
 3
```
Here, Julia was able to detect that `B` is in fact symmetric, and used a more appropriate factorization. Often it's possible to write more efficient code for a matrix that is known to have certain properties e.g. it is symmetric, or tridiagonal. Julia provides some special types so that you can "tag" matrices as having these properties. For instance:


# [Linear Algebra](#man-linalg)
```julia-repl
julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5]
3×3 Matrix{Float64}:
  1.5   2.0  -4.0
  2.0  -1.0  -3.0
 -4.0  -3.0   5.0

julia> sB = Symmetric(B)
3×3 Symmetric{Float64, Matrix{Float64}}:
  1.5   2.0  -4.0
  2.0  -1.0  -3.0
 -4.0  -3.0   5.0
```
`sB` has been tagged as a matrix that's (real) symmetric, so for later operations we might perform on it, such as eigenfactorization or computing matrix-vector products, efficiencies can be found by only referencing half of it. For example:
```julia-repl
julia> B = [1.5 2 -4; 2 -1 -3; -4 -3 5]
3×3 Matrix{Float64}:
  1.5   2.0  -4.0
  2.0  -1.0  -3.0
 -4.0  -3.0   5.0

julia> sB = Symmetric(B)
3×3 Symmetric{Float64, Matrix{Float64}}:
  1.5   2.0  -4.0
  2.0  -1.0  -3.0
 -4.0  -3.0   5.0

julia> x = [1; 2; 3]
3-element Vector{Int64}:
 1
 2
 3

julia> sB\x
3-element Vector{Float64}:
 -1.7391304347826084
 -1.1086956521739126
 -1.4565217391304346
```
The `\` operation here performs the linear solution. The left-division operator is pretty powerful and it's easy to write compact, readable code that is flexible enough to solve all sorts of systems of linear equations.


## [Special matrices](#Special-matrices)
[Matrices with special symmetries and structures](https://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=3274) arise often in linear algebra and are frequently associated with various matrix factorizations. Julia features a rich collection of special matrix types, which allow for fast computation with specialized routines that are specially developed for particular matrix types.
The following tables summarize the types of special matrices that have been implemented in Julia, as well as whether hooks to various optimized methods for them in LAPACK are available.


## [Special matrices](#Special-matrices)
| Type                                                        | Description                                                                                |
|:------------------------------------------------------------|:----------------------------------------------------------------------------------------------|
| [`Symmetric`](#LinearAlgebra.Symmetric)                     | [Symmetric matrix](https://en.wikipedia.org/wiki/Symmetric_matrix)                            |
| [`Hermitian`](#LinearAlgebra.Hermitian)                     | [Hermitian matrix](https://en.wikipedia.org/wiki/Hermitian_matrix)                            |
| [`UpperTriangular`](#LinearAlgebra.UpperTriangular)         | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix)                    |
| [`UnitUpperTriangular`](#LinearAlgebra.UnitUpperTriangular) | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) with unit diagonal |
| [`LowerTriangular`](#LinearAlgebra.LowerTriangular)         | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix)                    |
| [`UnitLowerTriangular`](#LinearAlgebra.UnitLowerTriangular) | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) with unit diagonal |
| [`UpperHessenberg`](#LinearAlgebra.UpperHessenberg)         | Upper [Hessenberg matrix](https://en.wikipedia.org/wiki/Hessenberg_matrix)                    |
| [`Tridiagonal`](#LinearAlgebra.Tridiagonal)                 | [Tridiagonal matrix](https://en.wikipedia.org/wiki/Tridiagonal_matrix)                        |
| [`SymTridiagonal`](#LinearAlgebra.SymTridiagonal)           | Symmetric tridiagonal matrix                                                                  |
| [`Bidiagonal`](#LinearAlgebra.Bidiagonal)                   | Upper/lower [bidiagonal matrix](https://en.wikipedia.org/wiki/Bidiagonal_matrix)              |
| [`Diagonal`](#LinearAlgebra.Diagonal)                       | [Diagonal matrix](https://en.wikipedia.org/wiki/Diagonal_matrix)                              |
| [`UniformScaling`](#LinearAlgebra.UniformScaling)           | [Uniform scaling operator](https://en.wikipedia.org/wiki/Uniform_scaling)                     |


### [Elementary operations](#Elementary-operations)
| Matrix type                                                 | `+` | `-` | `*` | `\` | Other functions with optimized methods                                                                                |
|:------------------------------------------------------------|:----|:----|:----|:----|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`Symmetric`](#LinearAlgebra.Symmetric)                     |     |     |     | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`sqrt`](../../base/math/#Base.sqrt-Tuple%7BNumber%7D), [`cbrt`](../../base/math/#Base.Math.cbrt-Tuple%7BAbstractFloat%7D), [`exp`](../../base/math/#Base.exp-Tuple%7BFloat64%7D) |
| [`Hermitian`](#LinearAlgebra.Hermitian)                     |     |     |     | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`sqrt`](../../base/math/#Base.sqrt-Tuple%7BNumber%7D), [`cbrt`](../../base/math/#Base.Math.cbrt-Tuple%7BAbstractFloat%7D), [`exp`](../../base/math/#Base.exp-Tuple%7BFloat64%7D) |
| [`UpperTriangular`](#LinearAlgebra.UpperTriangular)         |     |     | MV  | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det), [`logdet`](#LinearAlgebra.logdet)                                                                                |
| [`UnitUpperTriangular`](#LinearAlgebra.UnitUpperTriangular) |     |     | MV  | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det), [`logdet`](#LinearAlgebra.logdet)                                                                                |
| [`LowerTriangular`](#LinearAlgebra.LowerTriangular)         |     |     | MV  | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det), [`logdet`](#LinearAlgebra.logdet)                                                                                |
| [`UnitLowerTriangular`](#LinearAlgebra.UnitLowerTriangular) |     |     | MV  | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det), [`logdet`](#LinearAlgebra.logdet)                                                                                |
| [`UpperHessenberg`](#LinearAlgebra.UpperHessenberg)         |     |     |     | MM  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det)                                                                                |
| [`SymTridiagonal`](#LinearAlgebra.SymTridiagonal)           | M   | M   | MS  | MV  | [`eigmax`](#LinearAlgebra.eigmax), [`eigmin`](#LinearAlgebra.eigmin)                                                                                |
| [`Tridiagonal`](#LinearAlgebra.Tridiagonal)                 | M   | M   | MS  | MV  |                                                                                |
| [`Bidiagonal`](#LinearAlgebra.Bidiagonal)                   | M   | M   | MS  | MV  |                                                                                |
| [`Diagonal`](#LinearAlgebra.Diagonal)                       | M   | M   | MV  | MV  | [`inv`](../../base/math/#Base.inv-Tuple%7BNumber%7D), [`det`](#LinearAlgebra.det), [`logdet`](#LinearAlgebra.logdet), [`/`](../../base/math/#Base.:/)                                                                                |
| [`UniformScaling`](#LinearAlgebra.UniformScaling)           | M   | M   | MVS | MVS | [`/`](../../base/math/#Base.:/)                                                                                |


### [Elementary operations](#Elementary-operations)
Legend:
| Key        | Description                                                   |
|:-----------|:--------------------------------------------------------------|
| M (matrix) | An optimized method for matrix-matrix operations is available |
| V (vector) | An optimized method for matrix-vector operations is available |
| S (scalar) | An optimized method for matrix-scalar operations is available |


### [Matrix factorizations](#Matrix-factorizations)
| Matrix type                                                 | LAPACK | [`eigen`](#LinearAlgebra.eigen) | [`eigvals`](#LinearAlgebra.eigvals) | [`eigvecs`](#LinearAlgebra.eigvecs) | [`svd`](#LinearAlgebra.svd) | [`svdvals`](#LinearAlgebra.svdvals) |
|:------------------------------------------------------------|:-------|:--------------------------------|:------------------------------------|:------------------------------------|:----------------------------|:------------------------------------|
| [`Symmetric`](#LinearAlgebra.Symmetric)                     | SY     |                                 | ARI                                 |                                     |                             |                                     |
| [`Hermitian`](#LinearAlgebra.Hermitian)                     | HE     |                                 | ARI                                 |                                     |                             |                                     |
| [`UpperTriangular`](#LinearAlgebra.UpperTriangular)         | TR     | A                               | A                                   | A                                   |                             |                                     |
| [`UnitUpperTriangular`](#LinearAlgebra.UnitUpperTriangular) | TR     | A                               | A                                   | A                                   |                             |                                     |
| [`LowerTriangular`](#LinearAlgebra.LowerTriangular)         | TR     | A                               | A                                   | A                                   |                             |                                     |
| [`UnitLowerTriangular`](#LinearAlgebra.UnitLowerTriangular) | TR     | A                               | A                                   | A                                   |                             |                                     |
| [`SymTridiagonal`](#LinearAlgebra.SymTridiagonal)           | ST     | A                               | ARI                                 | AV                                  |                             |                                     |
| [`Tridiagonal`](#LinearAlgebra.Tridiagonal)                 | GT     |                                 |                                     |                                     |                             |                                     |
| [`Bidiagonal`](#LinearAlgebra.Bidiagonal)                   | BD     |                                 |                                     |                                     | A                           | A                                   |
| [`Diagonal`](#LinearAlgebra.Diagonal)                       | DI     |                                 | A                                   |                                     |                             |                                     |


### [Matrix factorizations](#Matrix-factorizations)
Legend:
| Key          | Description                                                                                | Example              |
|:-------------|:--------------------------------------------------------------------------------------------------------------------------------|:---------------------|
| A (all)      | An optimized method to find all the characteristic values and/or vectors is available                                           | e.g. `eigvals(M)`    |
| R (range)    | An optimized method to find the `il`th through the `ih`th characteristic values are available                                   | `eigvals(M, il, ih)` |
| I (interval) | An optimized method to find the characteristic values in the interval \[`vl`, `vh`\] is available                               | `eigvals(M, vl, vh)` |
| V (vectors)  | An optimized method to find the characteristic vectors corresponding to the characteristic values `x=[x1, x2,...]` is available | `eigvecs(M, x)`      |


### [The uniform scaling operator](#The-uniform-scaling-operator)
A [`UniformScaling`](#LinearAlgebra.UniformScaling) operator represents a scalar times the identity operator, `λ*I`. The identity operator `I` is defined as a constant and is an instance of `UniformScaling`. The size of these operators are generic and match the other matrix in the binary operations [`+`](../../base/math/#Base.:+), [`-`](../../base/math/#Base.:--Tuple%7BAny%7D), [`*`](../../base/math/#Base.:*-Tuple%7BAny,%20Vararg%7BAny%7D%7D) and [`\`](../../base/math/#Base.:\\-Tuple%7BAny,%20Any%7D). For `A+I` and `A-I` this means that `A` must be square. Multiplication with the identity operator `I` is a noop (except for checking that the scaling factor is one) and therefore almost without overhead.
To see the `UniformScaling` operator in action:
```julia-repl
julia> U = UniformScaling(2);

julia> a = [1 2; 3 4]
2×2 Matrix{Int64}:
 1  2
 3  4

julia> a + U
2×2 Matrix{Int64}:
 3  2
 3  6

julia> a * U
2×2 Matrix{Int64}:
 2  4
 6  8

julia> [a U]
2×4 Matrix{Int64}:
 1  2  2  0
 3  4  0  2

julia> b = [1 2 3; 4 5 6]
2×3 Matrix{Int64}:
 1  2  3
 4  5  6

julia> b - U
ERROR: DimensionMismatch: matrix is not square: dimensions are (2, 3)
Stacktrace:
[...]
```


### [The uniform scaling operator](#The-uniform-scaling-operator)
If you need to solve many systems of the form `(A+μI)x = b` for the same `A` and different `μ`, it might be beneficial to first compute the Hessenberg factorization `F` of `A` via the [`hessenberg`](#LinearAlgebra.hessenberg) function. Given `F`, Julia employs an efficient algorithm for `(F+μ*I) \ b` (equivalent to `(A+μ*I)x \ b`) and related operations like determinants.


## [Matrix factorizations](#man-linalg-factorizations)
[Matrix factorizations (a.k.a. matrix decompositions)](https://en.wikipedia.org/wiki/Matrix_decomposition) compute the factorization of a matrix into a product of matrices, and are one of the central concepts in (numerical) linear algebra.
The following table summarizes the types of matrix factorizations that have been implemented in Julia. Details of their associated methods can be found in the [Standard functions](#Standard-functions) section of the Linear Algebra documentation.
| Type               | Description                                                                                |
|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------|
| `BunchKaufman`     | Bunch-Kaufman factorization                                                                                |
| `Cholesky`         | [Cholesky factorization](https://en.wikipedia.org/wiki/Cholesky_decomposition)                                                    |
| `CholeskyPivoted`  | [Pivoted](https://en.wikipedia.org/wiki/Pivot_element) Cholesky factorization                                                     |
| `LDLt`             | [LDL(T) factorization](https://en.wikipedia.org/wiki/Cholesky_decomposition#LDL_decomposition)                                    |
| `LU`               | [LU factorization](https://en.wikipedia.org/wiki/LU_decomposition)                                                                |
| `QR`               | [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition)                                                                |
| `QRCompactWY`      | Compact WY form of the QR factorization                                                                                |
| `QRPivoted`        | Pivoted [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition)                                                        |
| `LQ`               | [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition) of `transpose(A)`                                              |
| `Hessenberg`       | [Hessenberg decomposition](https://mathworld.wolfram.com/HessenbergDecomposition.html)                                            |
| `Eigen`            | [Spectral decomposition](https://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix)                                            |
| `GeneralizedEigen` | [Generalized spectral decomposition](https://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix#Generalized_eigenvalue_problem) |
| `SVD`              | [Singular value decomposition](https://en.wikipedia.org/wiki/Singular_value_decomposition)                                        |
| `GeneralizedSVD`   | [Generalized SVD](https://en.wikipedia.org/wiki/Generalized_singular_value_decomposition#Higher_order_version)                    |
| `Schur`            | [Schur decomposition](https://en.wikipedia.org/wiki/Schur_decomposition)                                                          |
| `GeneralizedSchur` | [Generalized Schur decomposition](https://en.wikipedia.org/wiki/Schur_decomposition#Generalized_Schur_decomposition)              |


## [Matrix factorizations](#man-linalg-factorizations)
Adjoints and transposes of [`Factorization`](#LinearAlgebra.Factorization) objects are lazily wrapped in `AdjointFactorization` and `TransposeFactorization` objects, respectively. Generically, transpose of real `Factorization`s are wrapped as `AdjointFactorization`.


## [Orthogonal matrices (AbstractQ)](#man-linalg-abstractq)
Some matrix factorizations generate orthogonal/unitary "matrix" factors. These factorizations include QR-related factorizations obtained from calls to [`qr`](#LinearAlgebra.qr), i.e., `QR`, `QRCompactWY` and `QRPivoted`, the Hessenberg factorization obtained from calls to [`hessenberg`](#LinearAlgebra.hessenberg), and the LQ factorization obtained from [`lq`](#LinearAlgebra.lq). While these orthogonal/unitary factors admit a matrix representation, their internal representation is, for performance and memory reasons, different. Hence, they should be rather viewed as matrix-backed, function-based linear operators. In particular, reading, for instance, a column of its matrix representation requires running "matrix"-vector multiplication code, rather than simply reading out data from memory (possibly filling parts of the vector with structural zeros). Another clear distinction from other, non-triangular matrix types is that the underlying multiplication code allows for in-place modification during multiplication. Furthermore, objects of specific `AbstractQ` subtypes as those created via [`qr`](#LinearAlgebra.qr), [`hessenberg`](#LinearAlgebra.hessenberg) and [`lq`](#LinearAlgebra.lq) can behave like a square or a rectangular matrix depending on context:


## [Orthogonal matrices (AbstractQ)](#man-linalg-abstractq)
```julia
julia> using LinearAlgebra

julia> Q = qr(rand(3,2)).Q
3×3 LinearAlgebra.QRCompactWYQ{Float64, Matrix{Float64}, Matrix{Float64}}

julia> Matrix(Q)
3×2 Matrix{Float64}:
 -0.320597   0.865734
 -0.765834  -0.475694
 -0.557419   0.155628

julia> Q*I
3×3 Matrix{Float64}:
 -0.320597   0.865734  -0.384346
 -0.765834  -0.475694  -0.432683
 -0.557419   0.155628   0.815514

julia> Q*ones(2)
3-element Vector{Float64}:
  0.5451367118802273
 -1.241527373086654
 -0.40179067589600226

julia> Q*ones(3)
3-element Vector{Float64}:
  0.16079054743832022
 -1.674209978965636
  0.41372375588835797

julia> ones(1,2) * Q'
1×3 Matrix{Float64}:
 0.545137  -1.24153  -0.401791

julia> ones(1,3) * Q'
1×3 Matrix{Float64}:
 0.160791  -1.67421  0.413724
```
Due to this distinction from dense or structured matrices, the abstract `AbstractQ` type does not subtype `AbstractMatrix`, but instead has its own type hierarchy. Custom types that subtype `AbstractQ` can rely on generic fallbacks if the following interface is satisfied. For example, for
```julia
struct MyQ{T} <: LinearAlgebra.AbstractQ{T}
    # required fields
end
```
provide overloads for
```julia
Base.size(Q::MyQ) # size of corresponding square matrix representation
Base.convert(::Type{AbstractQ{T}}, Q::MyQ) # eltype promotion [optional]
LinearAlgebra.lmul!(Q::MyQ, x::AbstractVecOrMat) # left-multiplication
LinearAlgebra.rmul!(A::AbstractMatrix, Q::MyQ) # right-multiplication
```


## [Orthogonal matrices (AbstractQ)](#man-linalg-abstractq)
If `eltype` promotion is not of interest, the `convert` method is unnecessary, since by default `convert(::Type{AbstractQ{T}}, Q::AbstractQ{T})` returns `Q` itself. Adjoints of `AbstractQ`-typed objects are lazily wrapped in an `AdjointQ` wrapper type, which requires its own `LinearAlgebra.lmul!` and `LinearAlgebra.rmul!` methods. Given this set of methods, any `Q::MyQ` can be used like a matrix, preferably in a multiplicative context: multiplication via `*` with scalars, vectors and matrices from left and right, obtaining a matrix representation of `Q` via `Matrix(Q)` (or `Q*I`) and indexing into the matrix representation all work. In contrast, addition and subtraction as well as more generally broadcasting over elements in the matrix representation fail because that would be highly inefficient. For such use cases, consider computing the matrix representation up front and cache it for future reuse.


## [Pivoting Strategies](#man-linalg-pivoting-strategies)
Several of Julia's [matrix factorizations](#man-linalg-factorizations) support [pivoting](https://en.wikipedia.org/wiki/Pivot_element), which can be used to improve their numerical stability. In fact, some matrix factorizations, such as the LU factorization, may fail without pivoting.
In pivoting, first, a [pivot element](https://en.wikipedia.org/wiki/Pivot_element) with good numerical properties is chosen based on a pivoting strategy. Next, the rows and columns of the original matrix are permuted to bring the chosen element in place for subsequent computation. Furthermore, the process is repeated for each stage of the factorization.
Consequently, besides the conventional matrix factors, the outputs of pivoted factorization schemes also include permutation matrices.
In the following, the pivoting strategies implemented in Julia are briefly described. Note that not all matrix factorizations may support them. Consult the documentation of the respective [matrix factorization](#man-linalg-factorizations) for details on the supported pivoting strategies.
See also [`LinearAlgebra.ZeroPivotException`](#LinearAlgebra.ZeroPivotException).
```julia
NoPivot
```
Pivoting is not performed. Matrix factorizations such as the LU factorization may fail without pivoting, and may also be numerically unstable for floating-point matrices in the face of roundoff error. This pivot strategy is mainly useful for pedagogical purposes.
```julia
RowNonZero
```
First non-zero element in the remaining rows is chosen as the pivot element.


## [Pivoting Strategies](#man-linalg-pivoting-strategies)
Beware that for floating-point matrices, the resulting LU algorithm is numerically unstable — this strategy is mainly useful for comparison to hand calculations (which typically use this strategy) or for other algebraic types (e.g. rational numbers) not susceptible to roundoff errors. Otherwise, the default `RowMaximum` pivoting strategy should be generally preferred in Gaussian elimination.
Note that the [element type](../../base/collections/#Base.eltype) of the matrix must admit an [`iszero`](../../base/numbers/#Base.iszero) method.
```julia
RowMaximum
```
The maximum-magnitude element in the remaining rows is chosen as the pivot element. This is the default strategy for LU factorization of floating-point matrices, and is sometimes referred to as the "partial pivoting" algorithm.
Note that the [element type](../../base/collections/#Base.eltype) of the matrix must admit an [`abs`](../../base/math/#Base.abs) method, whose result type must admit a [`<`](../../base/math/#Base.:%3C) method.
```julia
ColumnNorm
```
The column with the maximum norm is used for subsequent computation. This is used for pivoted QR factorization.
Note that the [element type](../../base/collections/#Base.eltype) of the matrix must admit [`norm`](#LinearAlgebra.norm) and [`abs`](../../base/math/#Base.abs) methods, whose respective result types must admit a [`<`](../../base/math/#Base.:%3C) method.


## [Standard functions](#Standard-functions)
Linear algebra functions in Julia are largely implemented by calling functions from [LAPACK](https://www.netlib.org/lapack/). Sparse matrix factorizations call functions from [SuiteSparse](http://suitesparse.com). Other sparse solvers are available as Julia packages.
```julia
*(A::AbstractMatrix, B::AbstractMatrix)
```
Matrix multiplication.
**Examples**
```julia-repl
julia> [1 1; 0 1] * [1 0; 1 1]
2×2 Matrix{Int64}:
 2  1
 1  1
```
```julia
*(A, B::AbstractMatrix, C)
A * B * C * D
```
Chained multiplication of 3 or 4 matrices is done in the most efficient sequence, based on the sizes of the arrays. That is, the number of scalar multiplications needed for `(A * B) * C` (with 3 dense matrices) is compared to that for `A * (B * C)` to choose which of these to execute.
If the last factor is a vector, or the first a transposed vector, then it is efficient to deal with these first. In particular `x' * B * y` means `(x' * B) * y` for an ordinary column-major `B::Matrix`. Unlike `dot(x, B, y)`, this allocates an intermediate array.
If the first or last factor is a number, this will be fused with the matrix multiplication, using 5-arg [`mul!`](#LinearAlgebra.mul!).
See also [`muladd`](../../base/math/#Base.muladd), [`dot`](#LinearAlgebra.dot).
These optimisations require at least Julia 1.7.
```julia
\(A, B)
```


## [Standard functions](#Standard-functions)
Matrix division using a polyalgorithm. For input matrices `A` and `B`, the result `X` is such that `A*X == B` when `A` is square. The solver that is used depends upon the structure of `A`. If `A` is upper or lower triangular (or diagonal), no factorization of `A` is required and the system is solved with either forward or backward substitution. For non-triangular square matrices, an LU factorization is used.
For rectangular `A` the result is the minimum-norm least squares solution computed by a pivoted QR factorization of `A` and a rank estimate of `A` based on the R factor.
When `A` is sparse, a similar polyalgorithm is used. For indefinite matrices, the `LDLt` factorization does not use pivoting during the numerical factorization and therefore the procedure can fail even for invertible matrices.
See also: [`factorize`](#LinearAlgebra.factorize), [`pinv`](#LinearAlgebra.pinv).
**Examples**
```julia-repl
julia> A = [1 0; 1 -2]; B = [32; -4];

julia> X = A \ B
2-element Vector{Float64}:
 32.0
 18.0

julia> A * X == B
true
```
```julia
A / B
```
Matrix right-division: `A / B` is equivalent to `(B' \ A')'` where [`\`](../../base/math/#Base.:\\-Tuple%7BAny,%20Any%7D) is the left-division operator. For square matrices, the result `X` is such that `A == X*B`.
See also: [`rdiv!`](#LinearAlgebra.rdiv!).
**Examples**