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 相符的標籤。支援 glob 展開。
• 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：delta 和兩側物件的旗標。決定檔案是否視為二進制/文字，是否存在於 diff 的兩側，以及物件 ID 是否已知為正確。
• similarity：用於表示檔案是否已重新命名或複製。
• nfiles：delta 中的檔案數目（例如，如果 delta 是在子模組提交 ID 上執行，可能包含多個檔案）。
• old_file：包含變更前檔案資訊的 DiffFile。
• new_file：包含變更後檔案資訊的 DiffFile。

LibGit2.DiffFile

delta 一側的描述。符合 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：當檔案 delta 新增到 diff 中時，會通知使用者 diff 變更的選用回呼。
• progress_cb：顯示 diff 進度的選用回呼。僅與至少為 0.24.0 的 libgit2 版本相關。
• payload：傳遞給 notify_cb 和 progress_cb 的 payload。
• context_lines：用於定義 hunk 邊緣的未變更行數。這也是在 hunk 前後顯示的行數，以提供內容。預設為 3。
• interhunk_lines：在兩個獨立 hunk 之間允許的未變更行數上限，超過此上限後 hunk 將會合併。預設為 0。
• id_abbrev：設定要列印的縮寫 GitHash 長度。預設為 7。
• max_size：blob 的最大檔案大小。超過此大小，將會視為二進位 blob。預設為 512 MB。
• old_prefix：放置 diff 一側舊檔案的虛擬檔案目錄。預設為 "a"。
• new_prefix：放置 diff 一側新檔案的虛擬檔案目錄。預設為 "b"。

LibGit2.FetchHead

包含取回期間 HEAD 的資訊，包括取回分支的名稱和 URL、HEAD 的 oid，以及已取回的 HEAD 是否已在本地合併。

欄位表示

• name：取回 HEAD 在本地參考資料庫中的名稱，例如 "refs/heads/master"。
• url：取回 HEAD 的 URL。
• oid：取回 HEAD 尖端的 GitHash。
• ismerge：布林旗標，表示遠端的變更是否已合併到本地副本中。如果為 true，則本地副本已更新至遠端取回 HEAD。

LibGit2.FetchOptions

符合 git_fetch_options 結構。

欄位表示

• version：使用的結構版本，如果稍後變更，則為 1。
• callbacks：取回期間要使用的遠端回呼。
• prune：是否在取回後執行精簡。預設為使用 GitConfig 的設定。
• update_fetchhead：是否在取回後更新 FetchHead。預設為執行更新，這是正常的 git 行為。
• download_tags：是否下載遠端存在的標籤。預設為請求伺服器中無論如何都會下載的物件的標籤。
• proxy_opts：透過代理伺服器連線到遠端的選項。請參閱 ProxyOptions。僅存在於 0.25.0 或更新版本的 libgit2 中。
• custom_headers：擷取所需的任何額外標頭。僅存在於 0.24.0 或更新版本的 libgit2 中。

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 傳回 GitCommit 物件，由 hash/spec 指定。

• hash 是完整 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是一個文字規格：請參閱 git 文件 以取得完整清單。

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

透過從 path 中的檔案載入組態資訊來建立新的 GitConfig。請參閱 addfile 以取得關於 level、repo 和 force 選項的更多資訊。

GitConfig(repo::GitRepo)

取得 git 儲存庫 repo 的儲存組態。如果 repo 沒有設定特定的組態檔案，將會使用預設的 git 組態。

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

透過將全域和系統組態檔案載入優先順序組態，來取得預設的 git 組態。這可以用於在特定的 git 儲存庫外部存取預設的組態選項。

GitHash

一個 git 物件識別碼，根據 sha-1 hash。它是一個 20 位元組字串（40 個十六進位數字），用於識別儲存庫中的 GitObject。

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

從 repo 傳回指定的物件（GitCommit、GitBlob、GitTree 或 GitTag），由 hash/spec 指定。

• hash 是完整 (GitHash) 或部分 (GitShortHash) 哈希。
• spec 是一個文字規格：請參閱 git 文件 以取得完整清單。

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)

從 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 實作）。
• min_match_characters：提交中必須變更的最小 字母數字 字元數，才能將變更與該提交關聯。預設值為 20。僅在使用 libgit2 尚未實作的 Consts.BLAME_*_COPIES 標記之一時才會生效。
• 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 enum 為 GIT_MERGE，其值為
  • MERGE_FIND_RENAMES：偵測檔案是否已在共同祖先和合併的「ours」或「theirs」端之間重新命名。允許合併已重新命名的檔案。
  • 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：如果雙方都已變更，則使用合併驅動程式。此欄位僅存在於 0.25.0 以上版本的 libgit2。
• file_favor：如何處理 text 驅動程式的衝突檔案內容。
  • MERGE_FILE_FAVOR_NORMAL：如果合併的雙方都對某個區段有變更，請在索引中記下衝突，git checkout 會使用該索引建立合併檔案，使用者可以參考該檔案來解決衝突。這是預設值。
  • MERGE_FILE_FAVOR_OURS：如果合併的雙方都對某個區段有變更，請在索引中使用合併的「ours」側版本。
  • MERGE_FILE_FAVOR_THEIRS：如果合併的雙方都對某個區段有變更，請在索引中使用合併的「theirs」側版本。
  • MERGE_FILE_FAVOR_UNION：如果合併的雙方都對某個區段有變更，請將雙方的每一個唯一行都包含在放入索引的檔案中。
• file_flags：合併檔案的準則。

LibGit2.ProxyOptions

透過代理伺服器連線的選項。

與 git_proxy_options 結構相符。

欄位表示

• version：使用的結構版本，如果稍後變更，則為 1。
• proxytype：要使用的代理伺服器類型的 enum。定義於 git_proxy_t。對應的 Julia enum 為 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：在此 rebase 步驟中正在處理的提交的 GitHash。
• exec：如果使用 REBASE_OPERATION_EXEC，則在此步驟中執行的命令（例如，在每次提交後執行測試套件）。

LibGit2.RebaseOptions

與 git_rebase_options 結構相符。

欄位表示

• version：使用的結構版本，如果稍後變更，則為 1。
• quiet：告知幫助/處理 rebase 的其他 git 客戶端，rebase 應「安靜地」完成。用於互操作性。預設值為 1。
• inmemory：開始記憶體中的 rebase。處理 rebase 的呼叫者可以執行其步驟並提交任何變更，但不能倒轉 HEAD 或更新儲存庫。workdir 將不會被修改。僅出現在 libgit2 版本 0.24.0 或更新版本中。
• rewrite_notes_ref：當 rebase 完成時，用於重寫提交註解的註解參考名稱。
• merge_opts：合併選項，控制在每個 rebase 步驟中樹狀結構如何合併。僅出現在 libgit2 版本 0.24.0 或更新版本中。
• checkout_opts：初始化重新設定基礎、逐步執行重新設定基礎及中止重新設定基礎時，用於寫入檔案的 checkout 選項。如需更多資訊，請參閱 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)

請注意，由於資料是由 Julia 分配的，因此不需要呼叫 free。

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 可能包含會擴充的 glob 模式，且任何符合的檔案都會加入（除非設定 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 - 關閉 glob 比對，並僅將與 files 中指定路徑完全相符的檔案加入索引。

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

為指定的 rmt 新增一個 fetch refspec。此 refspec 將包含從哪些分支進行 fetch 的資訊。

範例

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 中的檔案，並將其新增到 repo 的物件資料庫中，作為一個獨立 blob。傳回結果 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 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：如果非 NULL，要更新為指向新提交的參考名稱。例如，"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 作為提交者，將目前的修補程式提交到重新設定 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 認證程序的特殊性，當認證失敗時，此函式會再次呼叫，而不會有任何指示是否認證成功。為了避免重複使用相同有問題的認證資料而造成無限迴圈，我們將使用 payload 追蹤狀態。

有關更多詳細資料，請參閱 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 擷取的遠端，由名稱指定。如果此處為空，網址將用於建構匿名遠端。
• remoteurl::AbstractString=""：remote 的網址。如果未指定，將根據 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的擷取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/*"]

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，則僅在合併為快轉合併（目前的 branch head 為要合併的 commit 的祖先）時合併，否則拒絕合併並傳回 false。這等同於 git CLI 選項 --ff-only。
• merge_opts::MergeOptions=MergeOptions()：merge_opts 指定合併選項，例如發生衝突時的合併策略。
• checkout_opts::CheckoutOptions=CheckoutOptions()：checkout_opts 指定 checkout 步驟的選項。

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

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

將註解 commit（擷取為 GitAnnotated 物件）anns 中的變更合併至儲存庫 repo 的 HEAD。關鍵字引數為

• merge_opts::MergeOptions = MergeOptions()：如何執行合併的選項，包括是否允許快轉合併。請參閱 MergeOptions 以取得更多資訊。
• checkout_opts::CheckoutOptions = CheckoutOptions()：如何執行 checkout 的選項。請參閱 CheckoutOptions 以取得更多資訊。

anns 可能參考遠端或本機 branch head。如果合併成功，則傳回 true，否則傳回 false（例如，如果無法合併，因為 branch 沒有共同的祖先）。

範例

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()：如何執行 checkout 的選項。請參閱 CheckoutOptions 以取得更多資訊。

anns 可能參考遠端或本機 branch head。如果合併成功，則傳回 true，否則傳回 false（例如，如果無法合併，因為 branch 沒有共同的祖先）。

範例

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 hash 物件，如果字串短於 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

使用啟發法來猜測檔案是否為二進位檔案：搜尋 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 是 diff 選項的規格。

範例

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 是 diff 選項的規格。

範例

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)

檢查目前的 branch 是否為「孤立」branch，也就是沒有任何提交。此 branch 的第一個提交不會有父層提交。

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 的推播 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（或 idx 所擁有儲存庫中 treehash 指向的樹狀結構）讀取到索引 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 [<提交>] [–] <路徑規格>...

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

使用 模式 設定的三種模式之一，將儲存庫 repo 重設為其在 id 的狀態

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 還原至先前的 狀態 s，例如合併嘗試前的分支 HEAD。可以使用 snapshot 函數產生 s。

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 設定語法文件，以取得更多詳細資訊。

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)

對 git 儲存庫 repo 套用函數 f，在套用 f 之前擷取一個 快照。如果在 f 中發生錯誤，則會使用 復原 將 repo 回復到其快照狀態。發生的錯誤會重新擲回，但 repo 的狀態不會損毀。

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

以後序或前序方式遍歷 tree 及其子樹中的項目。前序表示從根節點開始，然後遍歷最左邊的子樹（並遞迴向下遍歷該子樹的最左邊子樹），並向右遍歷子樹。後序表示從最左邊子樹的底部開始，向上遍歷該子樹，然後遍歷下一個右邊的子樹（再次從底部開始），最後訪問樹根。

函數參數 f 應具有下列簽章

(String, GitTreeEntry) -> Cint

從 f 回傳的負值會停止樹狀結構遍歷。正值表示如果 post 為 false，則會略過該項目。

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

判斷包含 ref 的分支是否有指定的 upstream 分支。

如果存在 upstream 分支，則回傳對應的 GitReference，如果請求的分支沒有 upstream 對應項，則回傳 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 的憑證回呼進行多次呼叫之間的狀態。預計 CredentialPayload 執行個體在將其與不同的 URL 一起使用時會 reset!。

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

將 payload 憑證儲存在未來驗證中以供重複使用。僅應在驗證成功時呼叫。

shred 關鍵字控制是否應銷毀 payload 憑證欄位中的敏感資訊。僅應在測試期間設定為 false。

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

捨棄 payload 憑證，避免在未來的驗證中重複使用。僅應在驗證失敗時呼叫。

shred 關鍵字控制是否應銷毀 payload 憑證欄位中的敏感資訊。僅應在測試期間設定為 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 - 代表可用組態檔案的最高等級（亦即實際載入的最特定組態檔案）