Plastic SCM - GitSync 指南

您現在可能已經知道，Plastic SCM 是擁有完整功能的 DVCS (分散式版本控制軟體)。Plastic SCM 也採用 Git 網路通訊協定。

Plastic SCM 能夠直接將變更至推送和提取至任何遠端 Git 伺服器。這是因為 Plastic 可在推送和提取變更集時支援 https:// 和 git:// 通訊協定。

此功能會立即將 Plastic SCM 轉換為與 Git 完全相容的 DVCS。此功能的優點在於您可以在工作站上使用 Plastic 或 Git，而且仍可參與 Git 專案 (GitHub、CodePlex 及其他更多項目)。

這可以是第一個方法：GitSync 是連線至 GitHub 的原生 Windows DVCS。因此，它實際上是會讓 Plastic SCM 變成適用於 Git 的全面性 Windows 用戶端。

想像一下您是使用 GitHub (或是 Bitbucket 或 CodePlex) 的開發者。在任何情況下會有您喜歡的：針對程式碼使用雲端式儲存庫，並使用 Windows 進行開發。也有您不喜歡的：被迫使用 CLI，而且缺乏絕佳 GUI 工具。

因此，您希望享有所有的優點：雲端儲存庫、DVCS 強大功能，以及絕佳的 Windows 工具。

這就是您採用 GitSync 的優勢。

GitSync 的功能如下所示：

• 直接推送/提取 - 包括所有認可、註解、分支、合併追蹤和標籤。
• 新增/刪除或移動檔案 - 兩端的任一端均無限制。
• 完整合併追蹤 - 您可以在 Git 端進行合併，而 Plastic 將會辨識合併追蹤。在 Plastic 至 Git 方向，也是同樣的情況。這就是 Plastic SCM 和 Git 成為完整 DVCS 的優勢！
• 衝突管理 - 您可以在 Git 端和 Plastic 端的相同分支上同時做變更，而 Plastic 會處理資料交換、提取變更、要求使用者執行合併，然後推送已解決的衝突 (就像您在只使用完整 Git 設定時的做法一樣)。

一張圖勝過千言萬語，因此，讓我們開始逐步瞭解整個推送和提取程序吧。

您有一個 Git 儲存庫，然後您在 Plastic 上提取該儲存庫。因此，您獲得了精確的分支複製，而您之前在 Git 中擁有的認可，現已轉換至 Plastic，其中最棒的是能夠在分支瀏覽器中轉譯：

下圖顯示在 Git 端建立新認可時所發生的情況，以及來自 Plastic SCM 的提取動作如何擷取。

此圖顯示如何從 big_feature 分支合併至 master 分支，而不是只執行簡單的變更。Plastic SCM 中的結果會模仿 Git 端所發生的情況，在 Plastic 分支瀏覽器上新增合併連結 (這會轉譯為綠色線條)：

下一個步驟是在 Plastic SCM 中執行變更，並將變更推送至 Git。為了建立更完整的範例 (而不是只建立新變更集)，我們也會執行合併。

已在 Plastic 端建立變更集 6 和 7，然後會將它們推送至 Git。如下圖所示，合併資訊 (Git 儲存庫上的多個上層) 也會從 Plastic 傳送至 Git。

目前為止，已在其中一端做出變更，但沒有在兩端同時做出變更。

下圖顯示多位開發者同時處理同一個分支時所發生的情況。在 Git 中建立一個新認可 (綠色)，並且也在 Plastic 中建立一個新認可 (橘色)：

如果 Plastic 開發者嘗試推送至 Git，將會出現錯誤，因為有衝突變更 (此錯誤同樣會出現在單純 Plastic 或單純 Git 設定上的類似案例)。以下是遵循步驟：

1. 先從 Git 提取變更
2. 將建立的新「子分支」正確地放置 88ffa 變更集。
   
3. 後續步驟將會解決 Plastic SCM 端的合併衝突，然後完成推送作業：
   

互動結束時，兩個儲存庫看起來會一模一樣，並且可讓開發者在兩端一起運作。

GitSync 設定檔案 (gitsync.conf) 可讓您包含將在 GitSync 作業期間自動使用的資訊。

此資訊與兩個 Plastic SCM 與 Git 物件之間的對應有關：

• 使用者帳戶
• Xlink/子模組資訊

在 gitsync.conf 檔案中，我們可以在 Plastic 與 Git (電子郵件) 之間定義對應。此資訊將在認可 Git 時做為作者和提交者來使用。

此資訊會以下列格式新增至 email-mapping 區段：

plastic_user = git_email_address

這是 gitsync.conf 檔案的範例：

[email-mapping]
asalim = asalim@mymailprovider.com
ubuntu = ubuntu@linuxprovider.com

Git 子模組只是不同儲存庫中認可的指標。它不會在子模組之間傳播作業，或在儲存庫之間處理分支，因此這項基本資訊對於子模組的運作來說非常足夠。

Plastic Xlink 物件比 Git 子模組更複雜：Xlink 可讓使用者設定相對伺服器、設定分支擴充的規則，以及定義 Xlink 是否可寫。

一般而言，我們可以說 Git 子模組和 Plastic Xlink 具有相同的使命：指向不同儲存庫中的認可。因此，可在下列兩者之間建立直接對應：

• Git 認可 ↔ Plastic 變更集
• Git 儲存庫 URL ↔ Plastic 儲存庫規格

GitSync 可讓使用者從 Git 子模組建立 Plastic Xlink，反之亦然。Git 子模組和 Plastic Xlink 可使用 GitSync 進行同步：

• 在提取作業期間，Git 子模組會轉換為 Plastic Xlink。
• 在推送作業期間，Plastic Xlink 會轉換為 Git 子模組。

請注意，在使用 Xlink/子模組同步處理儲存庫前，必須先同步處理目標儲存庫。

若要將儲存庫與 Xlink/子模組同步，必須在 gitsync.conf 檔案上新增對應資訊。此資訊會以下列格式新增至子模組區段上：

git_repository_url -> plastic_repository_spec [writable:true|false] [relativeserver:true|false]

• 如果 Git 子模組必須在可寫入的 Plastic Xlink 上進行轉換，則必須以 writable:true 形式包含 writable 欄位。如果 writable 欄位已遭忽略或設為 false，則會以唯讀形式建立 Xlink。
• 如果 Git 子模組必須在具有相對伺服器的 Plastic Xlink 上進行轉換，則必須以 relativeserver:true 形式包含欄位 relativeserver。如果 relativeserver 欄位已遭忽略或設為 false，則會針對 Plastic 儲存庫伺服器建立 Xlink (以非相對 Xlink 形式)。

這會是有效的設定範例：

[submodules]
git://localhost/code -> code@localhost:8084 writable:true relativeserver:true
git://localhost/doc -> doc@localhost:8084 writable:false relativeserver:true

使用 GitSync 時，會有兩個受到限制的 Git 作業：

• rebase 命令
• merge (快轉) 命令

這些 Git 命令不會考量您的變更歷史記錄。雖然使用者可以採用並行方式工作，Git 會以類似線性的概念談論歷史記錄。但 Plastic 會優先保留變更歷史記錄。

Plastic SCM 會將您進行的整個變更歷史記錄納入考量。這表示 Plastic 不會重寫歷史記錄。不是我們排斥它，而是一種設計決策和理念。

處理分支和合併時，會反映變更歷史記錄。因為 Plastic SCM 能夠解決和顯示歷史紀錄的情況，建議您在使用 GitSync 時最好避免使用這些 Git 命令。

• 重定基底是 Git 中的微妙主題 - 您只能在推送前執行此動作 (事實上，很多人建議永遠不要使用此功能)，而在大多數情況下，此功能有助於瞭解歷史記錄，而不被所有合併搞混：
  
  我們不會以 Git 形式處理重定基底。
• Git 快轉合併命令會執行類似的操作，以線性方式解決合併：
  
  使用 merge --no-ff 命令保留歷史記錄。

Plastic 具有分支瀏覽器，其會以圖形方式讓您瞭解正在發生的情況。如此一來，您就不會分心，也不會錯過重定基底。

當您針對一個分支與多個合併進行差異比對時，很難看出哪些是分支上實際變更的內容，哪些是來自合併的內容... 這也已在 Plastic 中獲得解決：

如我們之前所見，Plastic 可以使用原生 Git 和 https 通訊協定 (包括 GitHub、BitKeeper、CodePlex 及其他眾多知名網站)，直接推送和提取至遠端 Git 伺服器。

當我們開始開發與 Plastic SCM 的 Git 雙向同步時，我們考慮到下列情況：

• 已使用 Plastic SCM 的開發者，想要在 GitHub、CodePlex、BitKeeper 及其他網站中對專案做出貢獻。
• 使用 Git 做為主要伺服器以進行團隊合作的開發者偏好使用 Plastic SCM，但需要將變更回饋給主要伺服器。
• 逐步採用 Plastic SCM 的團隊需要在 Git 上向其他團隊做出貢獻。

過去我們是採用土法煉鋼方式取得解決方案：當時我們並未想出某種中繼指令碼將變更從一個系統轉換至另一個系統，或進行快速匯入/匯出，施加大量限制。但我們過去確實已在 Plastic 中實作 Git 網路通訊協定，做為能直接提取和推送至 Git 的圖層。

Plastic 與遠端 Git 伺服器開始進行交涉階段，就像 Git 命令一樣採用 Git 通訊協定。這是一項核心功能，而不是附加元件指令碼。

我們之前說過，GitSync 會實作智慧通訊協定，並且：

• 可以與遠端 Git 接收封包進行交涉，上傳資料 (協商需要哪些變更集/認可，並從 Plastic 儲存庫資料產生要傳送至 Git 的正確封包檔案)。
• 也可以與遠端上傳封包進行交涉，決定需要封裝哪些認可、下載封包，然後將其匯入 Plastic 中。

一開始先連線至 GitHub 儲存庫。

1. 如果您移至 GitHub 並瀏覽儲存庫，可能會發現類似「熱門」儲存庫的清單。在範例圖中，我已選取其中一個，叫做 corefx 儲存庫：
   

   現在，為了將它提取至 Plastic，我已建立一個「託管它」的儲存庫 (也稱為 corefx)，然後移至起初空白的分支瀏覽器，然後再移至操作功能表選項以啟動 [與 Git 同步處理]：

   
2. 然後，您會啟動 [同步] 對話方塊 (這非常類似於在 Plastic 伺服器之間推送/提取變更的複寫對話方塊)，並輸入 Git 儲存庫的 URL：
   

   現在不需要認證，因為我們剛從公開儲存庫提取 (複製)。如果您需要推送，則必須指定這些項目，然後伺服器會要求您成為通過驗證的使用者。

3. 只要按下 [同步]，程序 (提取) 將隨即啟動，如下所示：
   
   注意：可透過下列方式使用命令列完成此作業： cm sync corefx git https://github.com/corefx/corefx.git

   假設本機 corefx 儲存庫為空白狀態，它會計算需要從遠端 GitHub 儲存庫提取的變更集和分支，然後提取這些項目：

   

   若要提取在 GitHub 端完成的新變更，您只需重新執行相同的命令：

   cm sync corefx git https://github.com/corefx/corefx.git

   現在它將計算並只提取在 Git 端所做的新變更 (如果有的話)。

   您目前正在將 Git 變更集和分支直接提取至本機 Plastic SCM 儲存庫：

   
   
4. 複寫完成後，我們將回到工作區瀏覽器，並且將更新工作區以下載來源檔案。
5. 也請重新整理分支瀏覽器。您將能以一般的 Plastic SCM 方式轉譯剛匯入的 Git 變更集：
   

   現在，只要在任何變更集上按一下右鍵 (以 Git 行話來說就是認可)，您就能使用內建差異比對系統來檢查差異：

   

現在您已準備好在 Plastic 中進行更多變更，無論是分支、合併或任何項目。然後，重複相同程序以同步至 Git (如果已在相同分支上做出同時變更，這將進而推送或提取變更，並要求您先解決合併，然後再推送回 Git)。

我們要將其中一個 Plastic 儲存庫推送至 GitHub。您會發現此程序與先前的程序非常相似。

好！我們開始吧！

1. 我建立了一個新的 GitHub 儲存庫，可將我的 Plastic 儲存庫匯出至 GitHub：
   
2. 我已選擇我的 dokancode Plastic 儲存庫。在分支瀏覽器檢視中，在其中一個分支上按一下右鍵，然後像我們在上一章所做的一樣，選取 [與 Git 同步處理] 功能表選項：
   

   [同步] 對話方塊隨即啟動。

3. 然後，輸入 GitHub 儲存庫 URL，並視需要輸入認證：
   
4. 然後，按一下 [同步] 按鈕，開始進行同步。在此案例中，我們將推送 (或匯出) Plastic 儲存庫：
   

   我們目前正在將 Plastic SCM 變更集和分支直接推送至我的 GitHub 儲存庫。

   注意：可透過下列方式使用命令列完成此作業： cm sync dokancode git https://github.com/mbctesting/dokancode.git

   假設 GitHub dokancode 儲存庫為空白，GitSync 會計算它需要從 Plastic 儲存庫推送的變更集和分支，然後推送這些項目：

   

   推送作業完成後，我們可以看到持續匯出之物件的摘要：

   
   
5. 如果我們回到 GitHub 並重新整理 dokancode 儲存庫，將會看到從 Plastic 匯出的物件：
   

現在我們已準備好在兩端使用儲存庫：Plastic SCM 和 GitHub。我們將能建立分支、執行變更... 以及再次透過提取/推送來同步處理。

在本章中，我們將示範如何使用 dokancode 儲存庫 (包括 GitHub 端和 Plastic 端)，應用一些基本操作。

現在我要在 master 分支上執行一些作業：

1. 刪除 license.txt 檔案：
   
2. 編輯 dokan-net-0.6.0\readme_dokan.txt 檔案：
   
3. 並將其移至 dokan-net-0.6.0\DokanNet 資料夾：
   
4. 然後，我要建立新分支 (scm007)。
   
5. 新增兩個檔案：
   
   
6. 並編輯其中一個檔案：
   

已完成認可，現在我們可開始在 Plastic 端查看認可了。

正如我們在本指南期間所學，我們發現 GitSync 能夠計算另一端的新增項目、與遠端伺服器進行協調，以及推送變更。

1. 讓我們執行 [與 Git 同步處理] 動作，以同步處理 Plastic 儲存庫與 GitHub 儲存庫。
   
   
2. 只要按一下 [同步]，就會開始執行同步作業，並且會將我們在 GitHub 端執行的變更提取至 Plastic 儲存庫：
   

   完成同步作業後：

   
3. 我們可以看到匯入物件的摘要：
   
4. 如果我們回到分支瀏覽器並重新整理檢視，我們將會看到 GitHub 端已完成且已匯入 Plastic 的變更：
   
5. 我們可以開啟變更集檢視，以查看這些 GitHub 變更：
   
6. 此外，若要深入探究，我們可以使用 GitHub 端的 readme_dokan.txt 檔案確認完成的變更，我們可以看到該檔案的歷史記錄，檢查這些變更已隨著同步作業一起套用：
   

現在我們可以繼續在 Plastic 端執行變更了。

我將要在 scm005 分支上執行一些變更。目前，Git 和 Plastic 兩端皆具有相同的內容。我們可以在兩端進行檢查：

在此分支中，我將要：

1. 新增檔案：
   
2. 編輯 DokanOperation.cs 檔案：
   

   這些是新變更：

   
3. 完成變更後，我將要執行 [與 Git 同步] 作業以同步處理 GitHub 儲存庫：
   
4. 同步處理完成後，我們就可以查看摘要：
   

   此摘要指出同步作業已傳送一個分支中所涉及的兩個變更集：

   
5. 如果移至 GitHub 端，就可以查看 Plastic 端中已完成的這些新變更：
   

您可能已經注意到，Plastic main 分支會對應至 Git master 分支。此對應也可視為 Plastic 上的 main 分支的下層分支。這表示已透過移除階層並以 - 取代 /，將 Plastic 分支轉換為 Git 分支。此規則對於將 Git 分支轉換為 Plastic 分支的情況也有效：可使用 - 字元以在 Plastic 中重新建立階層。

在先前的範例中，Plastic 分支 /main/scm005 會轉換為 master-scm005。而master 分支底下的 Git 分支 scm007 則會轉換為 /main/scm007：

也允許使用 - 字元做為分支名稱的一部分，如以下範例所示：

因為 Plastic SCM 會處理與 Git 相同的概念 (DAG、認可、合併連結等)，所以可以非常輕鬆地共用合併追蹤。您可在 Git 中執行合併，也可以回到 Plastic 中執行。如果是在 Plastic 中執行合併，您甚至可以將合併連結推送回 Git。

對我們來說最難以處理的功能與「精確項目追蹤」有關；不過，我們可以處理 (但 Git 無法處理)。Plastic 具有與每個檔案和目錄相關聯的內部 ID。這表示，我們可以輕鬆處理難以追蹤 Git 的大量合併衝突 (例如分歧的移動，這對 Plastic 來說微不足道)。

在下列範例中，我們將瞭解使用 GitSync 時的合併追蹤運作方式。

我們將建立兩個分支：

1. 分支 scm008 - 我將在 DokanNet.cs 檔案中編輯 DokanResetTimeout 方法，將其移至檔案內，然後新增欄位：
   
2. 分支 scm009 - 我會將 DokanNet.cs 檔案移至另一個資料夾，然後將方法 DokanResetTimeout 移至另一個類別，並進行編輯：
   
3. 在不同的分支上完成變更後，我會將它們合併至 main 分支，並取得此結果：
   
   
4. 現在我要同步處理兩端的儲存庫，您也知道其需要使用 [與 Git 同步處理] 作業。如此一來，我會在 Git 端上推送這些合併。

新分支已推送，Git 端的合併追蹤如下所示：

現在，我們將會看到 Git 端的合併在 Plastic 端進行追蹤。

1. 我將會建立新分支，且將建立新檔案和編輯另一個檔案：
   
   
2. 完成認可後，我將要執行從 scm010 分支至主要分支的合併：
   
   請注意，此合併是使用我們在 GitSync 限制一節中看過的 --no-ff 選項所完成。
   

   此合併已完成，現在我們要將這些變更提取至遠端 Git 儲存庫：

   
3. 本機 Git 變更已提取至遠端 Git 儲存庫後，就可以去同步處理儲存庫。這表示最新變更將提取至 Plastic 儲存庫。如果我們執行 [與 Git 同步處理] 作業：
   
4. ...並且在完成同步後重新整理分支瀏覽器，此時我們將瞭解 Git 端完成的變更和合併已如何提取至 Plastic 端：
   

如我們在運作方式一章所見，我們可以在 Plastic 和 Git 端同時進行變更。這表示您可在兩個系統上使用相同分支和協調變更 (就像您在使用純 Plastic 環境或純 Git 環境時所做的一樣)。

我們將瞭解如何使用 GitSync 和 Plastic 管理該情況。

首先，我們要使用其中一個先前的範例。在 Git 端的變更一節，我們在 GitHub 端做出了一些變更。以下是我的操作：

1. 在 master 分支中 - 我刪除了 license.txt 檔案、編輯 dokan-net-0.6.0\readme_dokan.txt 檔案，並將其移動至 dokan-net-0.6.0\DokanNet 資料夾。
2. 然後，我建立了新分支 (scm007)，其中我新增了兩個檔案 (ArrayIndex.cs 和 ArrayInitialization.cs) 並編輯其中一個檔案 (ArrayIndex.cs)。

現在，我要在 Plastic 端執行一些變更：

1. 在 main 分支中，我要編輯 DokanNet.cs 檔案：
   
2. 新增 3 個檔案：
   

完成變更後，我決定使用 [與 Git 同步處理] 作業來同步處理兩個儲存庫：

完成同步時，訊息將會告知需要進行合併！

這是因為我們在 Git 和 Plastic 兩端的同一個分支中做了一些變更。

在摘要中，會看到 main (或 master) 分支是需要進行合併作業的分支：

確實是這樣：我們在 Git 端的 master 分支中套用了一些變更，並在 Plastic 端的 main 分支中做了一些其他變更。請切記，該 main 和 master 是相同的分支，但使用不同的名稱 (如需其他資訊，請參閱 Git-Plastic 字典)。

如我們在運作方式一節所見，我們必須解決 Plastic 端的合併衝突。我們開始吧！

1. 如果更新分支瀏覽器，我們會發現：
   • 首先，main 分支具有多個必須合併的「標頭」。這是因為，這些衝突在 Plastic SCM 中是以子分支的形式處理。
   • 其次，scm007 分支已同步 (已從 GitHub 提取至 Plastic SCM)。
   
2. 為解決此衝突，我們將從「GitHub」標頭執行合併 (子分支的標頭)：
   

   我們會看到即將合併的變更：

   
3. 只要按一下 [處理所有合併] 按鈕，就會自動合併項目。
4. 最後一個步驟 (如您所知) 就是在 [暫止的變更] 檢視中簽入 (確認) 變更：
   
5. 按一下 [簽入] 按鈕後，您會看到兩個「標頭」已合併為只有一個標頭，也就是來自 main 分支的標頭：
   
6. 合併衝突現已解決。但我們必須在 Git 端推送 Plastic 端中完成的變更，以完成同步作業。此外，您可能已經知道，這是透過 [與 Git 同步處理] 動作所完成。

完成此作業後，兩個儲存庫皆已完全同步。這表示我們在兩端有相同的內容。

GitSync 支援使用 SSH 通訊協定與 Git 儲存庫進行同步處理。

SSH 通訊協定可讓您連線至遠端伺服器和服務並進行驗證。

使用此功能：

1. 您的 PATH 環境變數中必須具有命令列 SSH 用戶端 ssh。
2. 您必須將私人 SSH 金鑰新增至 SSH 代理。請按照這些指示將 SSH 金鑰新增至 SSH 代理。

   SSH 代理現在可管理 SSH 金鑰，並記住複雜密碼。

現在，您可以透過 Plastic GUI 或 CLI 使用 GitSync，就像平常使用 HTTP 通訊協定時一樣。

我們來看這個範例。如果您使用命令列，您必須針對 SSH 通訊協定據以指定 URL：

而不是 HTTPS 通訊協定：

2020 年 9 月 24 日

• GitSync 支援使用 SSH 通訊協定與 Git 儲存庫進行同步處理。

2020 年 5 月 26 日

• 我們已醒目提示一些有關使用 GitSync 時受限的作業的建議。

2017 年 6 月 16 日

• 閱讀有關 Plastic 與 Git 之間的分支轉換 (反之亦然) 運作方式的詳細資訊。我們也更新了相關的螢幕擷取畫面。

2016 年 4 月 12 日

• 發佈日期。