LibGit2

LibGit2.Buffer

用于从 libgit2 导出数据的数据缓冲区。与 git_buf 结构匹配。

从 LibGit2 获取数据时，典型的用法如下：

buf_ref = Ref(Buffer())
@check ccall(..., (Ptr{Buffer},), buf_ref)
# 对 buf_ref 的操作
free(buf_ref)

特别注意，之后应该在 Ref 对象上调用 LibGit2.free。

LibGit2.CheckoutOptions

匹配 git_checkout_options 结构体。

字段表示：

• version: 正在使用的结构体版本，以防将来更改。目前始终为 1。
• checkout_strategy: 确定如何处理冲突以及是否强制检出/重新创建缺失的文件。
• disable_filters: 如果非零，则不应用像 CLRF 这样的过滤器（用于在 UNIX 和 DOS 之间转换文件换行符）。
• dir_mode: 参与检出的任何目录的读/写/访问模式。默认值为 0755。
• file_mode: 参与检出的任何文件的读/写/访问模式。默认值为 0755 或 0644，具体取决于 blob。
• file_open_flags: 在检出期间用于打开任何文件的位标志。
• notify_flags: 用户应被通知的冲突类型的标志。
• notify_cb: 可选的回调函数，用于在发生检出冲突时通知用户。如果此函数返回非零值，则检出将被取消。
• notify_payload: 通知回调函数的有效负载。
• progress_cb: 可选的回调函数，用于显示检出进度。
• progress_payload: 进度回调的有效负载。
• paths: 如果不为空，描述在检出期间要搜索的路径。如果为空，检出将发生在存储库中的所有文件上。
• baseline: workdir 的预期内容，捕获在（指向）GitTree 中。默认为 HEAD 时树的状态。
• baseline_index: workdir 的预期内容，捕获在（指向）GitIndex 中。默认为 HEAD 时索引的状态。
• target_directory: 如果不为空，则检出到此目录而不是 workdir。
• ancestor_label: 在发生冲突时，公共祖先方的名称。
• our_label: 在发生冲突时，“我们”一方的名称。
• their_label: 在发生冲突时，“他们”一方的名称。
• perfdata_cb: 可选的回调函数，用于显示性能数据。
• perfdata_payload: 性能回调的有效负载。

LibGit2.CloneOptions

匹配 git_clone_options 结构体。

字段表示：

• version：正在使用的结构体版本，以防将来更改。目前始终为 1。
• checkout_opts：作为克隆的一部分执行远程检出的选项。
• fetch_opts：作为克隆的一部分执行远程预检索的选项。
• bare：如果为 0，则克隆完整的远程仓库。如果非零，则执行裸克隆，其中在仓库中没有源文件的本地副本，且 gitdir 和 workdir 是相同的。
• localclone：标志是否克隆本地对象数据库或进行检索。默认情况下让 git 决定。它不会为本地克隆使用 git 感知的传输，但会为以 file:// 开头的 URL 使用。
• checkout_branch：要检出的分支名称。如果为空字符串，则将检出远程的默认分支。
• repository_cb：一个可选的回调，用于创建克隆所做的新仓库。
• repository_cb_payload：仓库回调的有效负载。
• remote_cb：一个可选的回调，用于在从中进行克隆之前创建 GitRemote。
• remote_cb_payload：远程回调的有效负载。

LibGit2.DescribeOptions

匹配 git_describe_options 结构体。

字段表示：

• version: 正在使用的结构体版本，以防将来更改。目前始终为 1。
• max_candidates_tags: 考虑在 refs/tags 中最近的这个数量的标签来描述一个提交。默认为 10（因此将检查最近的 10 个标签以查看它们是否描述了一个提交）。
• describe_strategy: 是否考虑 refs/tags 中的所有条目（相当于 git-describe --tags）或 refs/ 中的所有条目（相当于 git-describe --all）。默认情况下仅显示注释标签。如果传递 Consts.DESCRIBE_TAGS，将考虑所有标签，无论是否注释。如果传递 Consts.DESCRIBE_ALL，将考虑 refs/ 中的任何引用。
• pattern: 仅考虑与 pattern 匹配的标签。支持通配符扩展。
• only_follow_first_parent: 在查找匹配引用与描述对象之间的距离时，仅考虑第一个父级的距离。
• show_commit_oid_as_fallback: 如果找不到描述提交的匹配引用，则显示提交的 GitHash 而不是抛出错误（默认行为）。

LibGit2.DescribeFormatOptions

匹配 git_describe_format_options 结构体。

字段表示：

• version: 正在使用的结构体版本，以防将来更改。目前始终为 1。
• abbreviated_size: 要使用的简化 GitHash 的下限大小，默认为 7。
• always_use_long_format: 设置为 1 以在可以使用短格式的情况下仍然使用长格式字符串。
• dirty_suffix: 如果设置，将在描述字符串的末尾附加此内容，如果 workdir 是脏的。

LibGit2.DiffDelta

对一个条目的更改描述。与 git_diff_delta 结构匹配。

字段表示：

• status: Consts.DELTA_STATUS 中的一个，指示文件是否已被添加/修改/删除。
• flags: 表示增量和每一侧对象的标志。决定是否将文件视为二进制/文本，是否在增量的每一侧存在，以及对象 ID 是否已知为正确。
• similarity: 用于指示文件是否已被重命名或复制。
• nfiles: 增量中的文件数量（例如，如果增量是在子模块提交 ID 上运行的，它可能包含多个文件）。
• old_file: 一个 DiffFile，包含更改前文件的信息。
• new_file: 一个 DiffFile，包含更改后文件的信息。

LibGit2.DiffFile

描述增量的一侧。与 git_diff_file 结构匹配。

字段表示：

• id：增量中项目的 GitHash。如果该项目在增量的这一侧为空（例如，如果增量是文件的删除），则该值为 GitHash(0)。
• path：相对于存储库工作目录的以 NULL 结尾的项目路径。
• size：项目的字节大小。
• flags：git_diff_flag_t 标志的组合。该整数的第 i 位设置第 i 个标志。
• mode：项目的 stat 模式。
• id_abbrev：仅在版本大于或等于 0.25.0 的 LibGit2 中存在。使用 string 转换时 id 字段的长度。通常等于 OID_HEXSZ（40）。

LibGit2.DiffOptionsStruct

匹配 git_diff_options 结构体。

字段表示：

• version: 正在使用的结构体版本，以防将来更改。目前始终为 1。
• flags: 控制哪些文件将出现在差异中的标志。默认为 DIFF_NORMAL。
• ignore_submodules: 是否查看子模块中的文件。默认为 SUBMODULE_IGNORE_UNSPECIFIED，这意味着子模块的配置将控制它是否出现在差异中。
• pathspec: 要包含在差异中的文件路径。默认是使用存储库中的所有文件。
• notify_cb: 可选回调，当文件增量被添加到差异时，将通知用户差异的变化。
• progress_cb: 可选回调，将显示差异进度。仅在 libgit2 版本至少为 0.24.0 时相关。
• payload: 传递给 notify_cb 和 progress_cb 的有效负载。
• context_lines: 用于定义一个块边缘的 未更改 行数。这也是在块之前/之后显示的行数，以提供上下文。默认是 3。
• interhunk_lines: 允许在两个独立块之间的 未更改 行的最大数量，超过此数量将合并块。默认是 0。
• id_abbrev: 设置要打印的缩写 GitHash 的长度。默认是 7。
• max_size: blob 的最大文件大小。超过此大小，将被视为二进制 blob。默认是 512 MB。
• old_prefix: 在差异一侧放置旧文件的虚拟文件目录。默认是 "a"。
• new_prefix: 在差异一侧放置新文件的虚拟文件目录。默认是 "b"。

LibGit2.FetchHead

包含有关获取期间 HEAD 的信息，包括从中获取的分支的名称和 URL、HEAD 的 oid，以及获取的 HEAD 是否已在本地合并。

字段表示：

• name: 获取头在本地引用数据库中的名称，例如 "refs/heads/master"。
• url: 获取头的 URL。
• oid: 获取头尖端的 GitHash。
• ismerge: 布尔标志，指示远程的更改是否已合并到本地副本中。如果为 true，则本地副本与远程获取头是最新的。

LibGit2.FetchOptions

匹配 git_fetch_options 结构体。

字段表示：

• version: 正在使用的结构体版本，以防将来更改。目前始终为 1。
• callbacks: 在获取过程中使用的远程回调。
• prune: 是否在获取后执行修剪。默认使用 GitConfig 中的设置。
• update_fetchhead: 是否在获取后更新 FetchHead。默认执行更新，这是正常的 git 行为。
• download_tags: 是否下载远程存在的标签。默认请求从服务器下载的对象的标签。
• proxy_opts: 通过代理连接到远程的选项。请参见 ProxyOptions。仅在 libgit2 版本大于或等于 0.25.0 时存在。
• custom_headers: 获取所需的任何额外头部。仅在 libgit2 版本大于或等于 0.24.0 时存在。

GitAnnotated(repo::GitRepo, commit_id::GitHash)
GitAnnotated(repo::GitRepo, ref::GitReference)
GitAnnotated(repo::GitRepo, fh::FetchHead)
GitAnnotated(repo::GitRepo, committish::AbstractString)

一个注释的 git 提交携带了关于如何查找它以及原因的信息，以便 rebase 或合并操作可以获得有关提交上下文的更多信息。例如，冲突文件包含有关合并中冲突的源/目标分支的信息。注释提交可以引用远程分支的顶端，例如当传递一个 FetchHead 时，或者引用使用 GitReference 描述的分支头。

GitBlame(repo::GitRepo, path::AbstractString; options::BlameOptions=BlameOptions())

构造一个 GitBlame 对象，用于 path 处的文件，使用从 repo 的历史中获取的变更信息。GitBlame 对象记录了谁在何时以何种方式更改了文件的哪些部分。options 控制如何分隔文件的内容以及要探测哪些提交 - 有关更多信息，请参见 BlameOptions。

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

从由 hash/spec 指定的 repo 返回一个 GitBlob 对象。

• hash 是一个完整的 (GitHash) 或部分的 (GitShortHash) 哈希。
• spec 是一个文本规范：请参见 the git docs 获取完整列表。

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

从由 hash/spec 指定的 repo 返回一个 GitCommit 对象。

• hash 是一个完整的 (GitHash) 或部分的 (GitShortHash) 哈希。
• spec 是一个文本规范：请参见 the git docs 获取完整列表。

GitConfig(path::AbstractString, level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_APP, force::Bool=false)

通过从path处的文件加载配置信息来创建一个新的GitConfig。有关level、repo和force选项的更多信息，请参见addfile。

GitConfig(repo::GitRepo)

获取 git 仓库 repo 的存储配置。如果 repo 没有设置特定的配置文件，将使用默认的 git 配置。

GitConfig(level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_DEFAULT)

通过将全局和系统配置文件加载到优先配置中来获取默认的 git 配置。这可以用于访问特定 git 仓库之外的默认配置选项。

GitHash

一个基于 sha-1 哈希的 git 对象标识符。它是一个 20 字节的字符串（40 个十六进制数字），用于在仓库中标识 GitObject。

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

从 repo 中返回由 hash/spec 指定的对象（GitCommit, GitBlob, GitTree 或 GitTag）。

• hash 是完整的 (GitHash) 或部分的 (GitShortHash) 哈希。
• spec 是文本规范：请参见 the git docs 获取完整列表。

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

通过名称和 URL 查找远程 git 仓库。使用默认的获取 refspec。

示例

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

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

使用仓库的名称和 URL 以及从远程获取的规范（例如，从哪个远程分支获取）来查找远程 git 仓库。

示例

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

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

仅使用其 URL 而不是名称查找远程 git 存储库。

示例

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

LibGit2.GitRepo(path::AbstractString)

在 path 处打开一个 git 仓库。

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

在 path 处打开一个 git 仓库，并提供扩展控制（例如，如果当前用户必须是特殊访问组的成员才能读取 path）。

GitRevWalker(repo::GitRepo)

GitRevWalker 遍历 git 仓库 repo 的 修订（即提交）。它是仓库中提交的集合，支持迭代和对 LibGit2.map 和 LibGit2.count 的调用（例如，LibGit2.count 可用于确定某个作者在仓库中提交的百分比）。

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

在这里，LibGit2.count 找到沿着遍历与某个 GitHash 相关的提交数量。由于 GitHash 是提交的唯一标识，cnt 将为 1。

GitShortHash(hash::GitHash, len::Integer)

一个缩短的 git 对象标识符，当它是唯一时可以用来识别一个 git 对象，由 hash 的前 len 个十六进制数字组成（其余数字被忽略）。

LibGit2.GitSignature

这是一个指向git_signature对象的指针的Julia包装器。

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

收集关于 git 仓库 repo 中每个文件状态的信息（例如，文件是否被修改、已暂存等）。status_opts 可用于设置各种选项，例如是否查看未跟踪的文件或是否包含子模块等。有关更多信息，请参见 StatusOptions。

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

从由 hash/spec 指定的 repo 返回一个 GitTag 对象。

• hash 是一个完整的 (GitHash) 或部分的 (GitShortHash) 哈希。
• spec 是一个文本规范：请参见 the git docs 以获取完整列表。

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

从由 hash/spec 指定的 repo 返回一个 GitTree 对象。

• hash 是一个完整的 (GitHash) 或部分的 (GitShortHash) 哈希。
• spec 是一个文本规范：请参见 the git docs 获取完整列表。

LibGit2.IndexEntry

索引中文件条目的内存表示。与 git_index_entry 结构匹配。

LibGit2.IndexTime

匹配 git_index_time 结构。

LibGit2.BlameOptions

匹配 git_blame_options 结构体。

字段表示：

• version：正在使用的结构体版本，以防将来更改。目前始终为 1。
• flags：Consts.BLAME_NORMAL 或 Consts.BLAME_FIRST_PARENT 之一（libgit2 尚未实现其他 blame 标志）。
• min_match_characters：在提交中必须更改的最小 字母数字 字符数，以便将更改与该提交关联。默认值为 20。仅在使用 Consts.BLAME_*_COPIES 标志之一时生效，而 libgit2 尚未实现这些标志。
• newest_commit：要查看更改的最新提交的 GitHash。
• oldest_commit：要查看更改的最旧提交的 GitHash。
• min_line：开始 blame 的文件的第一行。默认值为 1。
• max_line：要 blame 的文件的最后一行。默认值为 0，表示文件的最后一行。

LibGit2.MergeOptions

匹配 git_merge_options 结构体。

字段表示：

• version：正在使用的结构体版本，以防将来更改。目前始终为 1。

• flags：描述合并行为的 enum 标志。定义在 git_merge_flag_t。对应的 Julia 枚举是 GIT_MERGE，其值为：

  • MERGE_FIND_RENAMES：检测文件在共同祖先与“我们的”或“他们的”合并一侧之间是否被重命名。允许文件被重命名的合并。
  • MERGE_FAIL_ON_CONFLICT：如果发现冲突则立即退出，而不是尝试解决它。
  • MERGE_SKIP_REUC：在合并结果的索引上不写入 REUC 扩展。
  • MERGE_NO_RECURSIVE：如果要合并的提交有多个合并基础，则使用第一个，而不是尝试递归合并基础。

• rename_threshold：考虑一个文件是另一个文件重命名的相似度阈值。这是一个设置相似度百分比的整数。默认值为 50。

• target_limit：查找重命名时要比较的最大文件数。默认值为 200。

• metric：可选的自定义函数，用于确定两个文件之间的相似度以进行重命名检测。

• recursion_limit：执行合并共同祖先的合并次数的上限，以尝试为合并构建一个新的虚拟合并基础。默认值为无限制。此字段仅在 libgit2 版本高于 0.24.0 时存在。

• default_driver：如果两个侧面都有更改，则使用的合并驱动程序。此字段仅在 libgit2 版本高于 0.25.0 时存在。

• file_favor：如何处理 text 驱动程序的冲突文件内容。

  • MERGE_FILE_FAVOR_NORMAL：如果合并的两个侧面对某个部分都有更改，则在索引中记录冲突，git checkout 将使用该索引创建合并文件，用户可以参考该文件以解决冲突。这是默认值。
  • MERGE_FILE_FAVOR_OURS：如果合并的两个侧面对某个部分都有更改，则在索引中使用合并的“我们的”侧面的版本。
  • MERGE_FILE_FAVOR_THEIRS：如果合并的两个侧面对某个部分都有更改，则在索引中使用合并的“他们的”侧面的版本。
  • MERGE_FILE_FAVOR_UNION：如果合并的两个侧面对某个部分都有更改，则在放入索引的文件中包含来自两个侧面的每个唯一行。

• file_flags：合并文件的指导方针。

LibGit2.ProxyOptions

通过代理连接的选项。

与 git_proxy_options 结构匹配。

字段表示：

• version: 正在使用的结构版本，以防将来更改。目前始终为 1。

• proxytype: 用于指定代理类型的 enum。在 git_proxy_t 中定义。相应的 Julia 枚举是 GIT_PROXY，其值为：

  • PROXY_NONE: 不尝试通过代理进行连接。
  • PROXY_AUTO: 尝试从 git 配置中找出代理配置。
  • PROXY_SPECIFIED: 使用此结构的 url 字段中给定的 URL 进行连接。

  默认是自动检测代理类型。

• url: 代理的 URL。

• credential_cb: 指向回调函数的指针，如果远程需要身份验证以进行连接，则会调用该函数。

• certificate_cb: 指向回调函数的指针，如果证书验证失败，则会调用该函数。这让用户决定是否继续连接。如果函数返回 1，则允许连接。如果返回 0，则不允许连接。可以使用负值返回错误。

• payload: 提供给两个回调函数的有效负载。

示例

julia> fo = LibGit2.FetchOptions(
           proxy_opts = LibGit2.ProxyOptions(url = Cstring("https://my_proxy_url.com")))

julia> fetch(remote, "master", options=fo)

LibGit2.PushOptions

匹配 git_push_options 结构体。

字段表示：

• version：正在使用的结构体版本，以防将来更改。目前始终为 1。
• parallelism：如果必须创建一个包文件，则此变量设置将由包构建器生成的工作线程数量。如果为 0，包构建器将自动设置要使用的线程数量。默认值为 1。
• callbacks：用于推送的回调（例如，用于与远程进行身份验证）。
• proxy_opts：仅在 LibGit2 版本大于或等于 0.25.0 时相关。设置使用代理与远程通信的选项。有关更多信息，请参见 ProxyOptions。
• custom_headers：仅在 LibGit2 版本大于或等于 0.24.0 时相关。推送操作所需的额外头部。

LibGit2.RebaseOperation

描述在变基过程中要执行的单个指令/操作。与 git_rebase_operation 结构匹配。

字段表示：

• optype：当前正在执行的变基操作的类型。选项包括：

  • REBASE_OPERATION_PICK：挑选相关的提交。
  • REBASE_OPERATION_REWORD：挑选相关的提交，但使用提示重写其消息。
  • REBASE_OPERATION_EDIT：挑选相关的提交，但允许用户编辑提交的内容及其消息。
  • REBASE_OPERATION_SQUASH：将相关的提交压缩到前一个提交中。这两个提交的提交消息将被合并。
  • REBASE_OPERATION_FIXUP：将相关的提交压缩到前一个提交中。仅使用前一个提交的提交消息。
  • REBASE_OPERATION_EXEC：不挑选提交。运行一个命令，如果命令成功退出则继续。

• id：在此变基步骤中正在处理的提交的 GitHash。

• exec：如果使用 REBASE_OPERATION_EXEC，则在此步骤中要运行的命令（例如，在每个提交后运行测试套件）。

LibGit2.RebaseOptions

匹配 git_rebase_options 结构体。

字段表示：

• version：正在使用的结构体版本，以防将来更改。目前始终为 1。
• quiet：通知其他 git 客户端在进行 rebase 时应“安静”地完成 rebase。用于互操作性。默认值为 1。
• inmemory：开始一个内存中的 rebase。处理 rebase 的调用者可以逐步进行并提交任何更改，但不能回退 HEAD 或更新仓库。workdir 将不会被修改。仅在 libgit2 版本大于或等于 0.24.0 时存在。
• rewrite_notes_ref：用于在 rebase 完成时重写提交注释的注释引用名称。
• merge_opts：控制在每个 rebase 步骤中如何合并树的合并选项。仅在 libgit2 版本大于或等于 0.24.0 时存在。
• checkout_opts：在初始化 rebase、逐步进行和中止时写入文件的检出选项。有关更多信息，请参见 CheckoutOptions。

LibGit2.RemoteCallbacks

回调设置。与 git_remote_callbacks 结构匹配。

LibGit2.SignatureStruct

一个操作签名（例如，提交者、标签者等）。与 git_signature 结构匹配。

字段表示：

• name: 提交者或提交的作者的全名。
• email: 可以联系到提交者/作者的电子邮件。
• when: 一个 TimeStruct，指示提交何时被创作/提交到仓库。

LibGit2.StatusEntry

提供文件在 HEAD 和索引中的差异，以及索引和工作目录之间的差异。与 git_status_entry 结构体相匹配。

字段表示：

• status：包含文件的状态标志，指示它是否是当前的，或者在索引或工作树中以某种方式发生了变化。
• head_to_index：指向一个 DiffDelta 的指针，该指针封装了文件在 HEAD 和索引中存在的差异。
• index_to_workdir：指向一个 DiffDelta 的指针，该指针封装了文件在索引和 workdir 中存在的差异。

LibGit2.StatusOptions

用于控制 git_status_foreach_ext() 如何发出回调的选项。与 git_status_opt_t 结构匹配。

字段表示：

• version：正在使用的结构版本，以防将来更改。目前始终为 1。
• show：用于检查哪些文件及其顺序的标志。默认值为 Consts.STATUS_SHOW_INDEX_AND_WORKDIR。
• flags：用于控制状态调用中使用的任何回调的标志。
• pathspec：用于路径匹配的路径数组。路径匹配的行为将根据 show 和 flags 的值而有所不同。
• baseline 是用于与工作目录和索引进行比较的树；默认为 HEAD。

LibGit2.StrArrayStruct

LibGit2 的字符串数组表示。与 git_strarray 结构匹配。

从 LibGit2 获取数据时，典型的用法如下：

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

特别注意，之后应该在 Ref 对象上调用 LibGit2.free。

相反，当将字符串向量传递给 LibGit2 时，通常最简单的方法是依赖隐式转换：

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

注意不需要调用 free，因为数据是由 Julia 分配的。

LibGit2.TimeStruct

签名中的时间。与 git_time 结构匹配。

addfile(cfg::GitConfig, path::AbstractString,
        level::Consts.GIT_CONFIG=Consts.CONFIG_LEVEL_APP,
        repo::Union{GitRepo, Nothing} = nothing,
        force::Bool=false)

将位于 path 的现有 git 配置文件添加到当前的 GitConfig cfg。如果文件不存在，将会创建它。

• level 设置 git 配置的优先级，并由

Consts.GIT_CONFIG 决定。

• repo 是一个可选的仓库，用于允许解析条件包含。
• 如果 force 为 false 且给定优先级的配置已存在，

addfile 将会报错。如果 force 为 true，则现有配置将被 path 中的文件替换。

add!(repo::GitRepo, files::AbstractString...; flags::Cuint = Consts.INDEX_ADD_DEFAULT)
add!(idx::GitIndex, files::AbstractString...; flags::Cuint = Consts.INDEX_ADD_DEFAULT)

将所有由 files 指定路径的文件添加到索引 idx（或 repo 的索引）。如果文件已经存在，索引条目将被更新。如果文件尚不存在，它将被新添加到索引中。files 可能包含将被扩展的通配符模式，任何匹配的文件将被添加（除非设置了 INDEX_ADD_DISABLE_PATHSPEC_MATCH，见下文）。如果文件被忽略（在 .gitignore 或配置中），它 将不会 被添加，除非 它已经在索引中被跟踪，在这种情况下它 将 被更新。关键字参数 flags 是一组位标志，用于控制与被忽略文件相关的行为：

• Consts.INDEX_ADD_DEFAULT - 默认，如上所述。
• Consts.INDEX_ADD_FORCE - 忽略现有的忽略规则，强制将文件添加到索引，即使它已经被忽略。
• Consts.INDEX_ADD_CHECK_PATHSPEC - 不能与 INDEX_ADD_FORCE 同时使用。检查 files 中每个存在于磁盘上的文件是否不在忽略列表中。如果其中一个文件 被 忽略，函数将返回 EINVALIDSPEC。
• Consts.INDEX_ADD_DISABLE_PATHSPEC_MATCH - 关闭通配符匹配，仅添加与 files 中指定路径完全匹配的文件到索引。

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

为指定的 rmt 添加一个 fetch refspec。此 refspec 将包含有关要从中获取的分支的信息。

示例

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

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

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

为指定的 rmt 添加一个 push refspec。此 refspec 将包含有关要推送到哪些分支的信息。

示例

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

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

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

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

读取 path 处的文件，并将其作为松散的 blob 添加到 repo 的对象数据库中。返回结果 blob 的 GitHash。

示例

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)

author(c::GitCommit)

返回提交 c 的作者的 Signature。作者是对相关文件进行了更改的人。另见 committer。

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

返回 repo 仓库中所有提交的作者。

示例

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)

# 将会是一个 [sig, sig] 的向量
auths = LibGit2.authors(repo)

branch(repo::GitRepo)

等同于 git branch。从当前的 HEAD 创建一个新分支。

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

在 repo 仓库中检出一个新的 git 分支。commit 是 GitHash，以字符串形式表示，将作为新分支的起点。如果 commit 是空字符串，将使用当前的 HEAD。

关键字参数包括：

• track::AbstractString=""：此新分支应跟踪的远程分支的名称（如果有）。如果为空（默认值），则不会跟踪任何远程分支。
• force::Bool=false：如果为 true，则强制创建分支。
• set_head::Bool=true：如果为 true，则在分支创建完成后，将分支头设置为 repo 的 HEAD。

等效于 git checkout [-b|-B] <branch_name> [<commit>] [--track <track>]。

示例

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

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

相当于 git checkout [-f] --detach <commit>。在 repo 中检出 git 提交 commit（以字符串形式表示的 GitHash）。如果 force 为 true，则强制检出并丢弃任何当前更改。请注意，这会分离当前的 HEAD。

示例

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
# 如果没有 force=true，这将失败
# 因为文件有修改
LibGit2.checkout!(repo, string(commit_oid), force=true)

clone(repo_url::AbstractString, repo_path::AbstractString, clone_opts::CloneOptions)

将远程仓库 repo_url（可以是远程 URL 或本地文件系统上的路径）克隆到 repo_path（必须是本地文件系统上的路径）。克隆的选项，例如是否执行裸克隆，由 CloneOptions 设置。

示例

repo_url = "https://github.com/JuliaLang/Example.jl"
repo = LibGit2.clone(repo_url, "/home/me/projects/Example")

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

将位于 repo_url 的远程仓库克隆到本地文件系统位置 repo_path。

关键字参数包括：

• branch::AbstractString=""：要克隆的远程分支，如果不是默认的仓库分支（通常是 master）。
• isbare::Bool=false：如果为 true，则将远程克隆为裸仓库，这将使 repo_path 本身成为 git 目录，而不是 repo_path/.git。这意味着无法检出工作树。相当于 git CLI 参数 --bare。
• remote_cb::Ptr{Cvoid}=C_NULL：在克隆之前用于创建远程的回调。如果为 C_NULL（默认值），则不会尝试创建远程 - 将假定其已存在。
• credentials::Creds=nothing：在对私有仓库进行身份验证时提供凭据和/或设置。
• callbacks::Callbacks=Callbacks()：用户提供的回调和有效负载。

等同于 git clone [-b <branch>] [--bare] <repo_url> <repo_path>。

示例

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

commit(repo::GitRepo, msg::AbstractString; kwargs...) -> GitHash

包装 git_commit_create。在仓库 repo 中创建一个提交。msg 是提交信息。返回新提交的 OID。

关键字参数包括：

• refname::AbstractString=Consts.HEAD_FILE：如果不为 NULL，则更新指向新提交的引用名称。例如，"HEAD" 将更新当前分支的 HEAD。如果引用尚不存在，将会被创建。
• author::Signature = Signature(repo) 是一个 Signature，包含有关提交作者的信息。
• committer::Signature = Signature(repo) 是一个 Signature，包含有关将提交提交到仓库的人的信息。不一定与 author 相同，例如，如果 author 将补丁通过电子邮件发送给 committer，然后由 committer 提交。
• tree_id::GitHash = GitHash() 是一个 git 树，用于创建提交，显示其祖先及与其他历史的关系。tree 必须属于 repo。
• parent_ids::Vector{GitHash}=GitHash[] 是一个由 GitHash 组成的提交列表，用作新提交的父提交，可以为空。如果是合并提交，提交可能有多个父提交。

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

将当前补丁提交到变基 rb，使用 sig 作为提交者。如果提交已经应用，则静默处理。

committer(c::GitCommit)

返回提交 c 的提交者的 Signature。提交者是最初由 author 创作的更改的提交人，但不必与 author 相同，例如，如果 author 将补丁通过电子邮件发送给提交者，而提交者进行了提交。

LibGit2.count(f::Function, walker::GitRevWalker; oid::GitHash=GitHash(), by::Cint=Consts.SORT_NONE, rev::Bool=false)

使用 GitRevWalker walker 在仓库历史中“遍历”每个提交，找到当 f 应用于它们时返回 true 的提交数量。关键字参数包括： * oid：要开始遍历的提交的 GitHash。默认使用 push_head!，因此从 HEAD 提交及其所有祖先开始。 * by：排序方法。默认是不排序。其他选项包括按拓扑排序 (LibGit2.Consts.SORT_TOPOLOGICAL)、按时间向前排序 (LibGit2.Consts.SORT_TIME，最古老的在前) 或按时间向后排序 (LibGit2.Consts.SORT_REVERSE，最新的在前)。 * rev：是否反转排序顺序（例如，如果使用拓扑排序）。

示例

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

LibGit2.count 找到沿着某个 GitHash commit_oid1 的遍历中的提交数量，从该提交开始遍历并向前移动。由于 GitHash 对于每个提交是唯一的，cnt 将为 1。

counthunks(blame::GitBlame)

返回文件中不同“hunk”的数量。一个 hunk 可能包含多行。hunk 通常是一起添加/更改/删除的文件的一部分，例如，添加到源文件的函数或后来从该函数中优化掉的内部循环。

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

在仓库 repo 中创建一个名为 bname 的新分支，该分支指向提交 commit_obj（该提交必须是 repo 的一部分）。如果 force 为 true，则如果存在名为 bname 的现有分支，将其覆盖。如果 force 为 false 且已存在名为 bname 的分支，则此函数将抛出错误。

credential_callback(...) -> Cint

一个 LibGit2 凭证回调函数，提供与连接协议相关的不同凭证获取功能。payload_ptr 需要包含一个 LibGit2.CredentialPayload 对象，该对象将跟踪状态和设置。

allowed_types 包含一个 LibGit2.Consts.GIT_CREDTYPE 值的位掩码，指定应尝试哪些身份验证方法。

凭证身份验证按以下顺序进行（如果支持）：

• SSH 代理
• SSH 私钥/公钥对
• 用户名/密码明文

如果用户被提示输入凭证，他们可以通过输入 ^D（同时按下控制键和 d 键）来中止提示。

注意：由于 libgit2 身份验证过程的特性，当身份验证失败时，此函数会再次被调用，而没有任何指示身份验证是否成功。为了避免因重复使用相同的错误凭证而导致的无限循环，我们将使用有效负载跟踪状态。

有关更多详细信息，请参阅 LibGit2 关于 对服务器进行身份验证 的指南。

C 函数指针用于 credentials_callback

返回签名对象。使用后释放它。

LibGit2.delete_branch(branch::GitReference)

删除由 branch 指向的分支。

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

显示在 git 仓库 repo 中，branch1 和 branch2 之间发生变化的文件。

关键字参数为：

• filter::Set{Consts.DELTA_STATUS}=Set([Consts.DELTA_ADDED, Consts.DELTA_MODIFIED, Consts.DELTA_DELETED]))，用于设置 diff 的选项。默认情况下显示添加、修改或删除的文件。

仅返回已更改文件的 名称，而不是其内容。

示例

LibGit2.branch!(repo, "branch/a")
LibGit2.branch!(repo, "branch/b")
# 向 repo 添加一个文件
open(joinpath(LibGit2.path(repo),"file"),"w") do f
    write(f, "hello repo
")
end
LibGit2.add!(repo, "file")
LibGit2.commit(repo, "add file")
# 返回 ["file"]
filt = Set([LibGit2.Consts.DELTA_ADDED])
files = LibGit2.diff_files(repo, "branch/a", "branch/b", filter=filt)
# 返回 [] 因为现有文件没有被修改
filt = Set([LibGit2.Consts.DELTA_MODIFIED])
files = LibGit2.diff_files(repo, "branch/a", "branch/b", filter=filt)

等同于 git diff --name-only --diff-filter=<filter> <branch1> <branch2>。

entryid(te::GitTreeEntry)

返回 te 所引用对象的 GitHash。

entrytype(te::GitTreeEntry)

返回 te 所引用对象的类型。结果将是 objtype 返回的类型之一，例如 GitTree 或 GitBlob。

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

从指定的 rmt 远程 git 仓库中获取，使用 refspecs 来确定要获取的远程分支。关键字参数包括：

• options: 确定获取的选项，例如是否在之后进行修剪。有关更多信息，请参见 FetchOptions。
• msg: 插入到 reflogs 中的消息。

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

从仓库 repo 的上游获取更新。

关键字参数包括：

• remote::AbstractString="origin"：要从中获取的 repo 的远程名称。如果为空，将使用 URL 构造一个匿名远程。
• remoteurl::AbstractString=""：remote 的 URL。如果未指定，将根据给定的 remote 名称进行假设。
• refspecs=AbstractString[]：确定获取的属性。
• credentials=nothing：在对私有 remote 进行身份验证时提供凭据和/或设置。
• callbacks=Callbacks()：用户提供的回调和有效负载。

等同于 git fetch [<remoteurl>|<repo>] [<refspecs>]。

fetchheads(repo::GitRepo) -> Vector{FetchHead}

返回 repo 的所有 fetch heads 列表，每个 fetch head 作为 FetchHead 表示，包括它们的名称、URL 和合并状态。

示例

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

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

获取指定 rmt 的 fetch refspecs。这些 refspecs 包含有关要从中获取的分支的信息。

示例

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 函数指针用于 fetchhead_foreach_callback

merge_base(repo::GitRepo, one::AbstractString, two::AbstractString) -> GitHash

查找提交 one 和 two 之间的合并基（共同祖先）。one 和 two 可以都是字符串形式。返回合并基的 GitHash。

merge!(repo::GitRepo; kwargs...) -> Bool

对仓库 repo 执行 git 合并，将具有分歧历史的提交合并到当前分支。如果合并成功，则返回 true，否则返回 false。

关键字参数如下：

• committish::AbstractString=""：合并 committish 中指定的提交。
• branch::AbstractString=""：合并分支 branch 及其自与当前分支分歧以来的所有提交。
• fastforward::Bool=false：如果 fastforward 为 true，则仅在合并为快进时才合并（当前分支头是要合并的提交的祖先），否则拒绝合并并返回 false。这相当于 git CLI 选项 --ff-only。
• merge_opts::MergeOptions=MergeOptions()：merge_opts 指定合并的选项，例如在冲突情况下的合并策略。
• checkout_opts::CheckoutOptions=CheckoutOptions()：checkout_opts 指定检出步骤的选项。

等同于 git merge [--ff-only] [<committish> | <branch>]。

merge!(repo::GitRepo, anns::Vector{GitAnnotated}; kwargs...) -> Bool

将注释提交（作为 GitAnnotated 对象捕获）的更改 anns 合并到仓库 repo 的 HEAD。关键字参数包括：

• merge_opts::MergeOptions = MergeOptions(): 执行合并的选项，包括是否允许快速前进。有关更多信息，请参见 MergeOptions。
• checkout_opts::CheckoutOptions = CheckoutOptions(): 执行检出操作的选项。有关更多信息，请参见 CheckoutOptions。

anns 可以指远程或本地分支头。如果合并成功，则返回 true，否则返回 false（例如，如果由于分支没有共同祖先而无法合并）。

示例

upst_ann = LibGit2.GitAnnotated(repo, "branch/a")

# 合并该分支
LibGit2.merge!(repo, [upst_ann])

merge!(repo::GitRepo, anns::Vector{GitAnnotated}, fastforward::Bool; kwargs...) -> Bool

将注释提交（作为 GitAnnotated 对象）anns 中的更改合并到仓库 repo 的 HEAD。如果 fastforward 为 true，则只允许快速合并。在这种情况下，如果发生冲突，合并将失败。否则，如果 fastforward 为 false，合并可能会产生一个冲突文件，用户需要解决该文件。

关键字参数包括：

• merge_opts::MergeOptions = MergeOptions(): 执行合并的选项，包括是否允许快速合并。有关更多信息，请参见 MergeOptions。
• checkout_opts::CheckoutOptions = CheckoutOptions(): 执行检出的选项。有关更多信息，请参见 CheckoutOptions。

anns 可以指远程或本地分支头。如果合并成功，则返回 true，否则返回 false（例如，如果由于分支没有共同祖先而无法合并）。

示例

upst_ann_1 = LibGit2.GitAnnotated(repo, "branch/a")

# 合并分支，快速合并
LibGit2.merge!(repo, [upst_ann_1], true)

# 合并冲突！
upst_ann_2 = LibGit2.GitAnnotated(repo, "branch/b")
# 合并分支，尝试快速合并
LibGit2.merge!(repo, [upst_ann_2], true) # 将返回 false
LibGit2.merge!(repo, [upst_ann_2], false) # 将返回 true

ffmerge!(repo::GitRepo, ann::GitAnnotated)

将快速前进合并更改到当前 HEAD。这仅在 ann 所引用的提交是当前 HEAD 的后代时才可能（例如，如果从远程分支拉取更改，而该分支仅在本地分支的顶部之前）。

LibGit2.fullname(ref::GitReference)

返回由符号引用 ref 指向的引用的名称。如果 ref 不是符号引用，则返回空字符串。

features()

返回当前版本的 libgit2 支持的 git 特性列表，例如线程、使用 HTTPS 或 SSH。

filename(te::GitTreeEntry)

返回 te 所引用的磁盘上对象的文件名。

filemode(te::GitTreeEntry) -> Cint

返回 te 所引用的磁盘上对象的 UNIX 文件模式，作为一个整数。

LibGit2.gitdir(repo::GitRepo)

返回 repo 的 "git" 文件的位置：

• 对于普通仓库，这是 .git 文件夹的位置。
• 对于裸仓库，这是仓库本身的位置。

另见 workdir, path.

LibGit2.git_url(; kwargs...) -> String

根据提供的 URL 组件创建一个字符串。当未提供 scheme 关键字时，生成的 URL 将使用替代的 scp-like 语法。

关键字

• scheme::AbstractString="": 用于标识所用协议的 URL 方案。对于 HTTP 使用 "http"，SSH 使用 "ssh" 等。当未提供 scheme 时，输出格式将为 "ssh"，但使用 scp-like 语法。
• username::AbstractString="": 如果提供，则在输出中使用的用户名。
• password::AbstractString="": 如果提供，则在输出中使用的密码。
• host::AbstractString="": 在输出中使用的主机名。必须指定主机名。
• port::Union{AbstractString,Integer}="": 如果提供，则在输出中使用的端口号。使用 scp-like 语法时无法指定。
• path::AbstractString="": 如果提供，则在输出中使用的路径。

示例

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"

@githash_str -> AbstractGitHash

从给定字符串构造一个 git 哈希对象，如果字符串短于 40 个十六进制数字，则返回 GitShortHash，否则返回 GitHash。

示例

julia> LibGit2.githash"d114feb74ce633"
GitShortHash("d114feb74ce633")

julia> LibGit2.githash"d114feb74ce63307afe878a5228ad014e0289a85"
GitHash("d114feb74ce63307afe878a5228ad014e0289a85")

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

返回一个 GitReference，指向 repo 的当前 HEAD。

head(pkg::AbstractString) -> String

返回 pkg 仓库的当前 HEAD GitHash 作为字符串。

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

将 repo 的 HEAD 设置为 ref 指向的对象。

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

查找 git 仓库 repo 当前 HEAD 的对象 ID。

LibGit2.headname(repo::GitRepo)

查找 git 仓库 repo 当前 HEAD 的名称。如果 repo 当前处于分离状态，则返回它所分离的 HEAD 的名称。

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

在 path 处打开一个新的 git 仓库。如果 bare 为 false，工作树将被创建在 path/.git 中。如果 bare 为 true，则不会创建工作目录。

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

如果 a（以字符串形式表示的 GitHash）是 b（以字符串形式表示的 GitHash）的祖先，则返回 true。

示例

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

isbinary(blob::GitBlob) -> Bool

使用启发式方法来猜测文件是否为二进制：搜索 NULL 字节，并在前 8000 个字节中查找可打印字符与不可打印字符的合理比例。

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

检查提交 id（它是字符串形式的 GitHash）是否在该仓库中。

示例

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

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

检查由 treeish 指定的树与工作树中的跟踪文件（如果 cached=false）或索引（如果 cached=true）之间是否存在任何差异。pathspecs 是差异选项的规范。

示例

repo = LibGit2.GitRepo(repo_path)
LibGit2.isdiff(repo, "HEAD") # 应该是 false
open(joinpath(repo_path, new_file), "a") do f
    println(f, "这是我很酷的新文件")
end
LibGit2.isdiff(repo, "HEAD") # 现在是 true

等同于 git diff-index <treeish> [-- <pathspecs>]。

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

检查工作树中（如果 cached=false）或索引中（如果 cached=true）是否有任何已跟踪文件的更改。pathspecs 是差异选项的规范。

示例

repo = LibGit2.GitRepo(repo_path)
LibGit2.isdirty(repo) # 应该是 false
open(joinpath(repo_path, new_file), "a") do f
    println(f, "这是我很酷的新文件")
end
LibGit2.isdirty(repo) # 现在是 true
LibGit2.isdirty(repo, new_file) # 现在是 true

等同于 git diff-index HEAD [-- <pathspecs>]。

LibGit2.isorphan(repo::GitRepo)

检查当前分支是否为“孤立”分支，即没有提交。该分支的第一个提交将没有父提交。

isset(val::Integer, flag::Integer)

测试 val 中由 flag 索引的位是否被设置（1）或未设置（0）。

iszero(id::GitHash) -> Bool

确定给定的 GitHash 的所有十六进制数字是否为零。

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

确定由 branch_name 指定的分支是否存在于仓库 repo 中。如果 remote 为 true，则假定 repo 是一个远程 git 仓库。否则，它是本地文件系统的一部分。

如果请求的分支存在，则返回一个指向该分支的 GitReference，如果不存在，则返回 nothing。

LibGit2.map(f::Function, walker::GitRevWalker; oid::GitHash=GitHash(), range::AbstractString="", by::Cint=Consts.SORT_NONE, rev::Bool=false)

使用 GitRevWalker walker 在仓库历史中“遍历”每个提交，将 f 应用到遍历中的每个提交。关键字参数包括： * oid：要开始遍历的提交的 GitHash。默认使用 push_head!，因此使用 HEAD 提交及其所有祖先。 * range：格式为 oid1..oid2 的 GitHash 范围。f 将应用于两者之间的所有提交。 * by：排序方法。默认是不排序。其他选项包括按拓扑排序 (LibGit2.Consts.SORT_TOPOLOGICAL)、按时间向前排序 (LibGit2.Consts.SORT_TIME，最古老的在前) 或按时间向后排序 (LibGit2.Consts.SORT_REVERSE，最新的在前)。 * rev：是否反转排序顺序（例如，如果使用拓扑排序）。

示例

oids = LibGit2.with(LibGit2.GitRevWalker(repo)) do walker
    LibGit2.map((oid, repo)->string(oid), walker, by=LibGit2.Consts.SORT_TIME)
end

在这里，LibGit2.map 使用 GitRevWalker 访问每个提交并找到其 GitHash。

镜像回调函数

该函数为远程引用设置 +refs/*:refs/* 引用规范和 mirror 标志。

C 函数指针用于 mirror_callback

message(c::GitCommit, raw::Bool=false)

返回描述在提交 c 中所做更改的提交信息。如果 raw 为 false，则返回稍微“清理过”的信息（去除了任何前导换行符）。如果 raw 为 true，则信息不会去除任何此类换行符。

merge_analysis(repo::GitRepo, anns::Vector{GitAnnotated}) -> analysis, preference

对由注释分支提示 anns 指向的分支运行分析，并确定在什么情况下可以合并。例如，如果 anns[1] 只是 ann[2] 的一个祖先，那么 merge_analysis 将报告可以进行快速前进合并。

返回两个输出，analysis 和 preference。analysis 有几个可能的值：

• MERGE_ANALYSIS_NONE：无法合并 anns 的元素。
• MERGE_ANALYSIS_NORMAL：常规合并，当 HEAD 和用户希望合并的提交都从一个共同的祖先分歧。在这种情况下，必须解决更改，并可能会发生冲突。
• MERGE_ANALYSIS_UP_TO_DATE：用户希望合并的所有输入提交都可以从 HEAD 到达，因此不需要进行合并。
• MERGE_ANALYSIS_FASTFORWARD：输入提交是 HEAD 的后代，因此不需要进行合并 - 用户可以简单地检出输入提交。
• MERGE_ANALYSIS_UNBORN：存储库的 HEAD 指向一个不存在的提交。无法合并，但可能可以检出输入提交。

preference 也有几个可能的值：

• MERGE_PREFERENCE_NONE：用户没有偏好。
• MERGE_PREFERENCE_NO_FASTFORWARD：不允许任何快速前进合并。
• MERGE_PREFERENCE_FASTFORWARD_ONLY：仅允许快速前进合并，不允许其他类型（可能会引入冲突）。

preference 可以通过存储库或全局 git 配置进行控制。

LibGit2.name(ref::GitReference)

返回 ref 的完整名称。

name(rmt::GitRemote)

获取远程仓库的名称，例如 "origin"。如果远程是匿名的（见 GitRemoteAnon），名称将是一个空字符串 ""。

示例

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

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

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

julia> name(remote)
"origin"

LibGit2.name(tag::GitTag)

tag 的名称（例如 "v0.5"）。

need_update(repo::GitRepo)

等同于 git update-index。如果 repo 需要更新，则返回 true。

objtype(obj_type::Consts.OBJECT)

返回与枚举值对应的类型。

LibGit2.path(repo::GitRepo)

返回仓库 repo 的基本文件路径。

• 对于普通仓库，这通常是 ".git" 目录的父目录（注意：这可能与工作目录不同，详见 workdir）。
• 对于裸仓库，这是 "git" 文件的位置。

另见 gitdir, workdir。

peel([T,] ref::GitReference)

递归剥离 ref，直到获得类型为 T 的对象。如果没有提供 T，则 ref 将被剥离，直到获得一个不是 GitTag 的对象。

• GitTag 将被剥离到它所引用的对象。
• GitCommit 将被剥离到 GitTree。

peel([T,] obj::GitObject)

递归剥离 obj，直到获得类型为 T 的对象。如果没有提供 T，则 obj 将被剥离直到类型发生变化。

• GitTag 将被剥离到它所引用的对象。
• GitCommit 将被剥离到 GitTree。

LibGit2.posixpath(path)

将路径字符串 path 标准化为使用 POSIX 分隔符。

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

推送到指定的 rmt 远程 git 仓库，使用 refspecs 来确定要推送到哪个远程分支。关键字参数包括：

• force：如果为 true，将进行强制推送，忽略冲突。
• options：确定推送的选项，例如使用哪些代理头。有关更多信息，请参见 PushOptions。

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

将更新推送到 repo 的上游。

关键字参数包括：

• remote::AbstractString="origin"：要推送到的上游远程的名称。
• remoteurl::AbstractString=""：remote 的 URL。
• refspecs=AbstractString[]：确定推送的属性。
• force::Bool=false：确定推送是否为强制推送，覆盖远程分支。
• credentials=nothing：在对私有 remote 进行身份验证时提供凭据和/或设置。
• callbacks=Callbacks()：用户提供的回调和有效负载。

等同于 git push [<remoteurl>|<repo>] [<refspecs>]。

LibGit2.push!(w::GitRevWalker, cid::GitHash)

从提交 cid 开始 GitRevWalker walker。此函数可用于对自某一年以来的所有提交应用一个函数，通过将该年的第一个提交作为 cid 传递，然后将结果 w 传递给 LibGit2.map。

LibGit2.push_head!(w::GitRevWalker)

将 HEAD 提交及其祖先推送到 GitRevWalker w。这确保在遍历过程中会遇到 HEAD 及其所有祖先提交。

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

获取指定 rmt 的 push refspecs。这些 refspecs 包含有关要推送到哪些分支的信息。

示例

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"]

raw(id::GitHash) -> Vector{UInt8}

获取 GitHash 的原始字节，作为长度为 20 的向量。

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

将树 tree（或由 treehash 指向的树，在 idx 所拥有的仓库中）读取到索引 idx 中。当前的索引内容将被替换。

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

尝试对当前分支进行自动合并变基，如果提供了 upstream，则从其进行变基，否则从上游跟踪分支进行变基。newbase 是要变基到的分支。默认情况下，这是 upstream。

如果出现无法自动解决的冲突，变基将中止，保留仓库和工作树的原始状态，并且该函数将抛出 GitError。这大致相当于以下命令行语句：

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

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

获取 repo 仓库中所有引用名称的列表。

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

返回一个与 ref 类型对应的 Cint：

• 如果引用无效，则返回 0
• 如果引用是对象 ID，则返回 1
• 如果引用是符号引用，则返回 2

LibGit2.remotes(repo::GitRepo)

返回 repo 的远程名称的向量。

remove!(repo::GitRepo, files::AbstractString...)
remove!(idx::GitIndex, files::AbstractString...)

从索引 idx（或 repo 的索引）中删除由 files 指定路径的所有文件。

reset(val::Integer, flag::Integer)

将 val 中由 flag 索引的位清零，返回为 0。

reset!(payload, [config]) -> CredentialPayload

将 payload 状态重置为初始值，以便可以在凭证回调中再次使用。如果提供了 config，则配置也将被更新。

从目标提交树中，根据 pathspecs 更新索引中的一些条目。

将当前头设置为指定的提交 oid，并可选择性地重置索引和工作树以匹配。

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

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

将仓库 repo 重置为 id 的状态，使用 mode 设置的三种模式之一：

1. Consts.RESET_SOFT - 将 HEAD 移动到 id。
2. Consts.RESET_MIXED - 默认，将 HEAD 移动到 id 并将索引重置为 id。
3. Consts.RESET_HARD - 将 HEAD 移动到 id，将索引重置为 id，并丢弃所有工作更改。

示例

# 获取更改
LibGit2.fetch(repo)
isfile(joinpath(repo_path, our_file)) # 将为 false

# 快进合并更改
LibGit2.merge!(repo, fastforward=true)

# 因为本地没有任何文件，但远程有
# 一个文件，我们需要重置分支
head_oid = LibGit2.head_oid(repo)
new_head = LibGit2.reset!(repo, head_oid, LibGit2.Consts.RESET_HARD)

在这个例子中，从中获取的远程确实在其索引中有一个名为 our_file 的文件，这就是我们必须重置的原因。

等同于 git reset [--soft | --mixed | --hard] <id>。

示例

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
# 将丢弃对 file1 的更改
# 并取消暂存
new_head = LibGit2.reset!(repo, head_oid, mode)

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

将仓库 repo 恢复到之前的 State s，例如在合并尝试之前的分支的 HEAD。s 可以使用 snapshot 函数生成。

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

列出 commit1 和 commit2 之间的修订次数（以字符串形式表示的提交 OID）。由于 commit1 和 commit2 可能位于不同的分支上，revcount 执行“左-右”修订列表（和计数），返回一个 Int 的元组 - 左侧和右侧提交的数量。左（或右）提交指的是从树的对称差异的哪一侧可以到达该提交。

等同于 git rev-list --left-right --count <commit1> <commit2>。

示例

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

这将返回 (-1, 0)。

set_remote_url(repo::GitRepo, remote_name, url)
set_remote_url(repo::String, remote_name, url)

为 GitRepo 或位于 path 的 git 仓库设置 remote_name 的获取和推送 url。通常 git 仓库使用 "origin" 作为远程名称。

示例

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

LibGit2.shortname(ref::GitReference)

返回 ref 的简短名称，便于“人类阅读”。

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"

snapshot(repo::GitRepo) -> State

获取当前仓库 repo 的快照，存储当前的 HEAD、索引和任何未提交的工作。输出的 State 可以在后续调用 restore 时使用，以将仓库恢复到快照状态。

LibGit2.split_cfg_entry(ce::LibGit2.ConfigEntry) -> Tuple{String,String,String,String}

将 ConfigEntry 拆分为以下部分：部分、子部分、名称和值。

示例

给定包含以下内容的 git 配置文件：

[credential "https://example.com"]
    username = me

ConfigEntry 看起来如下：

julia> entry
ConfigEntry("credential.https://example.com.username", "me")

julia> LibGit2.split_cfg_entry(entry)
("credential", "https://example.com", "username", "me")

有关更多详细信息，请参阅 git config 语法文档。

LibGit2.status(repo::GitRepo, path::String) -> Union{Cuint, Cvoid}

查找 git 仓库 repo 中 path 处文件的状态。例如，这可以用来检查 path 处的文件是否已被修改并需要暂存和提交。

stage(ie::IndexEntry) -> Cint

获取 ie 的阶段编号。阶段编号 0 表示工作树的当前状态，但在合并冲突的情况下，可以使用其他编号。在这种情况下，IndexEntry 上的各种阶段编号描述了文件当前状态属于冲突的哪一方。阶段 0 是尝试合并之前的状态，阶段 1 是本地所做的更改，阶段 2 及更大的编号用于来自其他分支的更改（例如，在多分支“章鱼”合并的情况下，可能会使用阶段 2、3 和 4）。

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

在仓库 repo 中创建一个新的 git 标签 tag（例如 "v0.5"），位于提交 commit 处。

关键字参数包括：

• msg::AbstractString=""：标签的消息。
• force::Bool=false：如果为 true，将覆盖现有引用。
• sig::Signature=Signature(repo)：标签创建者的签名。

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

从仓库 repo 中删除 git 标签 tag。

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

获取 git 仓库 repo 中所有标签的列表。

LibGit2.target(tag::GitTag)

tag 的目标对象的 GitHash。

toggle(val::Integer, flag::Integer)

翻转 val 中由 flag 索引的位，因此如果某个位是 0，在翻转后将变为 1，反之亦然。

transact(f::Function, repo::GitRepo)

将函数 f 应用到 git 仓库 repo，在应用 f 之前先进行 snapshot。如果在 f 内部发生错误，repo 将使用 restore 返回到其快照状态。发生的错误将被重新抛出，但 repo 的状态不会被损坏。

treewalk(f, tree::GitTree, post::Bool=false)

遍历 tree 及其子树中的条目，按照后序或前序进行。前序意味着从根开始，然后遍历最左边的子树（并递归地向下遍历该子树的最左边子树），并向右移动通过子树。后序意味着从最左边子树的底部开始，向上遍历，然后遍历下一个右子树（同样从底部开始），最后访问树的根。

函数参数 f 应具有以下签名：

(String, GitTreeEntry) -> Cint

从 f 返回的负值将停止树遍历。正值意味着如果 post 为 false，则该条目将被跳过。

upstream(ref::GitReference) -> Union{GitReference, Nothing}

确定包含 ref 的分支是否具有指定的上游分支。

如果存在，则返回指向上游分支的 GitReference，如果请求的分支没有上游对应分支，则返回 nothing。

update!(repo::GitRepo, files::AbstractString...)
update!(idx::GitIndex, files::AbstractString...)

更新索引 idx（或 repo 的索引）中由 files 指定路径的所有文件。将索引中每个文件的状态与磁盘上的当前状态进行匹配，如果文件在磁盘上已被删除，则将其移除，或者更新其在对象数据库中的条目。

url(rmt::GitRemote)

获取远程 git 仓库的获取 URL。

示例

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"

version() -> VersionNumber

返回正在使用的 libgit2 的版本，作为 VersionNumber。

with(f::Function, obj)

资源管理辅助函数。将 f 应用到 obj，确保在 f 成功返回或抛出错误后调用 close 以关闭 obj。确保分配的 git 资源在不再需要时尽快被释放。

with_warn(f::Function, ::Type{T}, args...)

资源管理辅助函数。将 f 应用到 args，首先从 args 构造类型 T 的实例。确保在 f 成功返回或抛出错误后调用结果对象的 close。确保分配的 git 资源在不再需要时尽快被释放。如果 f 抛出错误，将显示包含该错误的警告。

LibGit2.workdir(repo::GitRepo)

返回 repo 的工作目录位置。这对于裸仓库会抛出错误。

另请参见 gitdir, path.

(::Type{T})(te::GitTreeEntry) where T<:GitObject

获取 te 所指的 git 对象，并将其作为实际类型返回（例如 entrytype 将显示的类型），例如 GitBlob 或 GitTag。

示例

tree = LibGit2.GitTree(repo, "HEAD^{tree}")
tree_entry = tree[1]
blob = LibGit2.GitBlob(tree_entry)

仅支持 user 和 password 参数的凭据

SSH 凭证类型

isfilled(cred::AbstractCredential) -> Bool

验证凭证是否准备好用于身份验证。

缓存凭证信息以供重用

LibGit2.CredentialPayload

在对同一 URL 的凭据回调进行多次调用之间保留状态。预计每当与不同的 URL 一起使用时，CredentialPayload 实例应被 reset!。

approve(payload::CredentialPayload; shred::Bool=true) -> Nothing

存储 payload 凭证以便在将来的身份验证中重用。仅在身份验证成功时调用。

shred 关键字控制是否应销毁凭证字段中的敏感信息。仅在测试期间设置为 false。

reject(payload::CredentialPayload; shred::Bool=true) -> Nothing

丢弃 payload 凭证，以防在未来的身份验证中被重新使用。仅在身份验证失败时调用。

shred 关键字控制是否应销毁凭证字段中的敏感信息。仅在测试期间设置为 false。

配置文件的优先级级别。

这些优先级级别对应于在 git 中搜索配置条目时的自然升级逻辑（从高到低）。

• CONFIG_LEVEL_DEFAULT - 打开全局、XDG 和系统配置文件（如果有可用的话）。
• CONFIG_LEVEL_PROGRAMDATA - 在 Windows 上的系统范围内，为了与便携式 git 兼容
• CONFIG_LEVEL_SYSTEM - 系统范围的配置文件；在 Linux 系统上为 /etc/gitconfig
• CONFIG_LEVEL_XDG - XDG 兼容的配置文件；通常为 ~/.config/git/config
• CONFIG_LEVEL_GLOBAL - 用户特定的配置文件（也称为全局配置文件）；通常为 ~/.gitconfig
• CONFIG_LEVEL_LOCAL - 仓库特定的配置文件；在非裸仓库中为 $WORK_DIR/.git/config
• CONFIG_LEVEL_APP - 应用程序特定的配置文件；由应用程序自由定义
• CONFIG_HIGHEST_LEVEL - 代表可用的最高级别配置文件（即实际加载的最具体的配置文件）