LibGit2

LibGit2.Buffer

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

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

buf_ref = Ref(Buffer())
@check ccall(..., (Ptr{Buffer},), buf_ref)
# operation on 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: diff 中项目的 GitHash。如果项目在 diff 的这一侧为空（例如，如果 diff 是删除文件），则将为 GitHash(0)。
• path: 指向相对于存储库工作目录的项目的以 NULL 结尾的路径。
• size: 项目的大小（以字节为单位）。
• flags: git_diff_flag_t 标志的组合。此整数的第 i 位设置第 i 个标志。
• mode: 项目的 stat 模式。
• id_abbrev: 仅在 LibGit2 版本 0.25.0 或更高版本中存在。使用 string 转换时 id 字段的长度。通常等于 OID_HEXSZ (40)。

LibGit2.DiffOptionsStruct

与 git_diff_options 结构匹配。

字段表示

• version：使用的结构体版本，以防将来发生更改。目前，始终为 1。
• flags: 控制哪些文件将出现在 diff 中的标志。默认为 DIFF_NORMAL。
• ignore_submodules: 是否查看子模块中的文件。默认为 SUBMODULE_IGNORE_UNSPECIFIED，这意味着子模块的配置将控制它是否出现在 diff 中。
• pathspec: 要包含在 diff 中的文件的路径。默认为使用存储库中的所有文件。
• notify_cb: 可选回调，它将在文件增量添加到 diff 时通知用户 diff 的更改。
• progress_cb: 可选回调，它将显示 diff 进度。仅在 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: 在 diff 的一侧放置旧文件的虚拟文件目录。默认为 "a"。
• new_prefix: 在 diff 的一侧放置新文件的虚拟文件目录。默认为 "b"。

LibGit2.FetchHead

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

字段表示

• name: fetch head 在本地引用数据库中的名称，例如 "refs/heads/master"。
• url: fetch head 的 URL。
• oid: fetch head 顶部的 GitHash。
• ismerge: 布尔标志，指示远程的更改是否已合并到本地副本中。如果为 true，则本地副本与远程 fetch head 保持同步。

LibGit2.FetchOptions

与 git_fetch_options 结构匹配。

字段表示

• version：使用的结构体版本，以防将来发生更改。目前，始终为 1。
• callbacks: fetch 期间使用的远程回调。
• prune: 是否在 fetch 后执行 prune。默认为使用 GitConfig 中的设置。
• update_fetchhead: 是否在 fetch 后更新 FetchHead。默认为执行更新，这是正常的 git 行为。
• download_tags: 是否下载远程存在的标签。默认为请求任何情况下从服务器下载的对象的标签。
• proxy_opts: 通过代理连接到远程的选项。请参阅 ProxyOptions。仅在 libgit2 版本 0.25.0 或更高版本中存在。
• custom_headers: fetch所需的任何额外标头。仅在 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 提交随附有关其查找方式和原因的信息，以便重新定基或合并操作可以获得更多有关提交上下文的信息。例如，冲突文件包含有关合并中发生冲突的源/目标分支的信息。例如，当传递 FetchHead 或使用 GitReference 描述分支头时，带注释的提交可以引用远程分支的顶端。

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

使用从 repo 的历史记录中收集的更改信息，为 path 处的文件构造一个 GitBlame 对象。GitBlame 对象记录了谁在何时更改了文件的哪些块以及如何更改。options 控制如何分离文件的内容以及要探测哪些提交 - 有关更多信息，请参阅 BlameOptions。

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

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

• hash 是完整的 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是文本规范：有关完整列表，请参阅 git 文档。

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

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

• hash 是完整的 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是文本规范：有关完整列表，请参阅 git 文档。

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 是文本规范：有关完整列表，请参阅 git 文档。

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

使用其名称和 URL 查找远程 git 存储库。使用默认的 fetch 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)

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

• hash 是完整的 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是文本规范：有关完整列表，请参阅 git 文档。

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

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

• hash 是完整的 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是文本规范：有关完整列表，请参阅 git 文档。

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：开始归责的文件的第一行。默认值为1。
• max_line：要归责的文件的最后一行。默认值为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：为了尝试为合并构建新的虚拟合并基础，要执行的公共祖先合并次数的上限。默认情况下没有限制。此字段仅存在于 0.24.0 之后版本的 libgit2 中。
• default_driver：如果双方都进行了更改，则要使用的合并驱动程序。此字段仅存在于 0.25.0 之后版本的 libgit2 中。
• 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：如果必须创建打包文件，则此变量设置打包构建器将生成的 worker 线程数。如果为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 客户端变基应“安静地”完成。用于互操作性。默认值为1。
• inmemory：启动内存中变基。在变基上工作的调用者可以遍历其步骤并提交任何更改，但不能倒回 HEAD 或更新存储库。workdir不会被修改。仅存在于 0.24.0 或更高版本的 libgit2 中。
• rewrite_notes_ref：要用于在变基完成后重写提交注释的注释的引用的名称。
• merge_opts：控制在每个变基步骤中如何合并树的合并选项。仅存在于 0.24.0 或更高版本的 libgit2 中。
• checkout_opts：在初始化变基、逐步执行变基和中止变基时写入文件的检出选项。有关更多信息，请参阅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)

# will be a Vector of [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
# would fail without the force=true
# since there are modifications to the file
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：如果非空，则要更新以指向新提交的引用的名称。例如，"HEAD"将更新当前分支的 HEAD。如果引用尚不存在，则将创建它。
• author::Signature = Signature(repo)是一个包含有关提交作者信息的Signature。
• committer::Signature = Signature(repo)是一个包含有关将提交提交到存储库的人员的信息的Signature。不一定与author相同，例如，如果author通过电子邮件将补丁发送给committer，后者将其提交。
• tree_id::GitHash = GitHash()是要用于创建提交的git树，显示其祖先及其与任何其他历史记录的关系。tree必须属于repo。
• parent_ids::Vector{GitHash}=GitHash[]是使用GitHash作为新提交的父提交的提交列表，并且可以为空。例如，如果提交是合并提交，则它可能有多个父提交。

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

使用sig作为提交者，将当前补丁提交到rebase rb。如果提交已应用，则保持静默。

committer(c::GitCommit)

返回提交c的提交者的Signature。提交者是最初由author提交更改的人员，但不必与author相同，例如，如果author通过电子邮件将补丁发送给committer，后者将其提交。

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)

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

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关于对服务器进行身份验证的指南。

credentials_callback的C函数指针

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

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

等效于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：要插入 reflog 的消息。

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的所有获取头的列表，每个获取头都表示为一个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的获取 refspec。这些 refspec 包含有关要从中获取哪个分支的信息。

示例

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

fetchhead_foreach_callback的 C 函数指针。

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

# merge the branch in
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")

# 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

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 的语法。

关键字

• scheme::AbstractString=""：用于标识要使用的协议的 URL 方案。对于 HTTP，使用“http”，对于 SSH，使用“ssh”等。当未提供scheme时，输出格式将为“ssh”，但使用类似 scp 的语法。
• username::AbstractString=""：如果提供，则在输出中使用的用户名。
• password::AbstractString=""：如果提供，则在输出中使用的密码。
• host::AbstractString=""：在输出中使用的主机名。必须指定主机名。
• port::Union{AbstractString,Integer}=""：如果提供，则在输出中使用的端口号。在使用类似 scp 的语法时，不能指定此选项。
• 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

返回指向repo的当前 HEAD 的GitReference。

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

使用启发式方法猜测文件是否为二进制文件：搜索空字节并在前 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") # 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

等效于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) # 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

等效于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}

确定存储库repo中是否存在由branch_name指定的分支。如果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/* refspec和mirror标志。

mirror_callback的C函数指针

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的推送refspec。这些refspec包含有关要推送到哪个分支的信息。

示例

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（或由idx拥有的存储库中treehash指向的树）读入索引idx。当前索引内容将被替换。

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

尝试当前分支的自动合并变基，如果提供了upstream，则从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更新索引中的一些条目，来自目标提交树。

将当前head设置为指定的提交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，并丢弃所有工作更改。

示例

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

在这个例子中，正在获取的远程仓库的索引中确实包含一个名为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
# will discard the changes to file1
# and unstage it
new_head = LibGit2.reset!(repo, head_oid, mode)

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

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

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

列出commit1和commit2（字符串形式的提交对象ID）之间的修订次数。由于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)

为位于path处的GitRepo或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中，在提交commit处创建一个新的git标签tag（例如"v0.5"）。

关键字参数为

• 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内部发生错误，则将使用restore将repo恢复到其快照状态。发生的错误将重新抛出，但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成功返回或抛出错误后调用obj上的close。确保在不再需要分配的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的多次调用到凭据回调之间的状态。每当CredentialPayload实例将用于不同的URL时，都应将其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 - 表示可用的最高级别的配置文件（即实际加载的最具体的配置文件）