Plastic SCM - GitServer 指南

現在，所有 Plastic SCM 伺服器皆可使用 Git 通訊協定 (支援 git 和 http) 為儲存庫提供服務。

這表示，每個 Git 用戶端都可以直接推送/提取至 Plastic SCM 伺服器。

Git 生態系統中的任何工具現在都可以直接使用原生 Git 功能連線至 Plastic SCM。Plastic 上的團隊現在可以從所有 DevOps、CI 和專為 Git 開發的專案管理整合中獲益。

GitServer 是 GitSync 的伺服器端對應項目 (這可允許所有 Plastic SCM 用戶端推送/提取至 git 伺服器)，並關閉 Git 互通性迴圈。

GitServer 可用於廣泛的案例，但其主要目標是做為「通用連接器」，以讓任何 Git 軟體連線至 Plastic。

任何 Git 相容的 git 用戶端均可將變更推送/提取至 GitServer ，這可支援許多不同的使用案例：

1. 將 Git 相容軟體連線至 Plastic SCM - 開發者可以使用 GitServer，利用 Git 整合將 FishEye、CodeCollaborator、ReviewBoard、TeamCity 等諸多工具連線至 Plastic SCM。
2. 使用 Plastic SCM 做為中央 Git 伺服器 - 開發者可以從 Git 推送/提取至啟用 GitServer 的 Plastic SCM 伺服器。
3. 做為異質團隊的中央儲存庫 - 數個團隊現在可以在 Git 和 Plastic SCM 上進行共同作業。這可能會在逐步移轉至 Plastic SCM 後發生，其中某些團隊仍在 Git 上，或只是做為策略的一部分，其中不同團隊將選擇 Plastic 或 Git 做為其版本控制選項，而且仍可使用 Plastic 做為中央會合點來進行共同作業。

在 Plastic SCM 伺服器上啟用 GitServer，非常簡單：

1. 在伺服器的二進位檔目錄上 (plasticd.exe 的所在位置) 建立空白的 gitserver.conf 檔案。
2. 然後，重新啟動 Plastic SCM 伺服器。它會開始在 git 通訊協定預設連接埠上進行監聽：9418。

現在，您可以從 Git 推送/提取至 Plastic SCM，如下所示：

此命令會將 Git 儲存庫推送至名為預設的 Plastic 儲存庫。

gitserver.conf 是控制 GitServer 設定的檔案，且具有下列格式，其中每一行皆為選用：

# port configuration
tcp.port=9418
http.port=80

# mapping storage - the mappings between git and plastic objects
# the default path is automatically generated by the server
storage.baseDirectory=e:\gitserver\mappings

# mapping interval - how often GitServer looks for new changes
# on the Plastic side to make them available to git
# By default, it is 5 minutes (300 seconds)
mapping.interval=300

# repositories to be exported. By default, all repositories 
# will be available on GitServer unless a list is specified here
export.repo=code
export.repo=quake
export.repo=robotcode

Windows 會在 HTTP 上施加安全性限制，因此必須採取特殊動作，才能讓 GitServer 使用指定的 HTTP 連接埠。它只會影響不在特殊權限帳戶下執行的程序。因此，若以 Windows Service 形式執行 Plastic SCM，不需執行任何特殊動作，即可啟用 http。

如果 Plastic SCM 伺服器在非管理員模式下執行 (不是以預設 Windows 服務的形式)，則您只需要將權限授與執行此程序的特定使用者。這可透過下列命令進行：

GitServer 可以使用 HTTP 基本驗證來保護 Git 用戶端。

這表示，若啟用此驗證，Git 用戶端將在連線至 GitServer 時要求您輸入使用者名稱和密碼。

若要設定 HTTP 驗證，您只需在 gitserver.conf 檔案中新增下列項目：

# http authentication
http.basicauth=true

當然，GitServer 必須設定為在 HTTP 通訊協定中監聽：

# http authentication
http.port=8080
http.basicauth=true

Plastic SCM 伺服器可以像 Git 伺服器一樣運作，讓 Git 用戶端以公開透明方式存取。

變更可以從不同的來源傳送至 GitServer：

• 從 Git 執行 git push 作業。此 Git 命令一旦完成，變更便可立即供 Plastic SCM 和 Git 用戶端使用。
• 從 Plastic 執行 check-in 或 replica 作業。這些變更無法立即供 Git 用戶端使用。如果「匯出」至 Git 的儲存庫中有新的 Plastic 變更，背景執行緒會每 mapping.interval 秒檢查一次。如果有發現變更，就會開始計算對應，計算完成後，Git 就會看到新變更。

Plastic SCM 支援部分複本，這是無法對應至 Git 的功能。雖然此議題在純 Plastic 環境上相當實用，但在混合式 Git/Plastic 案例中可能會有問題。

請思考下列案例，其中 John 先將 main 分支推送至主要儲存庫 (已使用 GitServer 同步至 Git 的儲存庫)，但並未推送已合併至 main 分支的分支 main/task001：

當 GitServer 程式碼開始為新變更集 (此範例中的編號 10)「編製索引」以將它們提供給 Git 時，其只會查看變更集 10。新變更集也能以 Git 認可的形式提供，並可由 Git 用戶端提取。

假設之後 John 記得將 main/task001 推送至 central。Git 將永遠看不到新分支 task001，因為變更集 10 之前已匯出，且重新計算 task001 會變更 10 的「sha」，因此會中斷與之前已提取 10 的遠端 git 儲存庫的同步作業。

請務必瞭解此限制，確保只有在正確分支位於應該要同步至 Git 的 Plastic 儲存庫時，才會計算 git 對應。

請查看下列案例，其中的中央儲存庫使用部分複本收到 task002。無法在主要儲存庫上取得 task002 的上層，因此如果計算了與 Git 的對應，將會忽略分支：

即使稍後推送 task001，如果其對應已在 task001 推送至中央儲存庫前計算，Git 儲存庫仍將無法看到 task002。

請切記，Git 極度不建議在已遠端推送的儲存庫上進行「重定基底」和「重新寫入歷史記錄」。這同樣也適用於這裡所述的案例，其中考慮新歷史記錄意味著在 Git 端重新寫入，中斷遠端 Git 儲存庫。

假設現在前述範例中有變化，其中做為合併的未連結分支已完全複寫：

在此案例中，Git 無法看到 task002，因為它是未連結的分支。這表示，Git 也看不到新變更集 10，因為它代表可能中斷的歷史記錄。一旦複寫分支 task002 的上層，GitServer 將能連結整個歷史記錄，並向 Git 用戶端顯示變更集 10。

即使某些變更集不符合條件，仍可強制要求 GitServer 提供一個分支給 Git。

在上一個案例中，強制要求 GitServer「對應」變更集 10，即使 task002 未完全連結，且永遠不會對應至 Git。

您唯一要做的是在 gitserver.conf 上 add branch.toForceMap 項目，如下所示：

# branches which changesets are made visible
# although they have unlinked merge sources
branch.toForceMap=/main

GitServer 也會忽略含有未解析的 Xlink 的變更集，因此 Git 用戶端將無法看到它們。

請思考下列案例，其中分支 main@root 包含 main@xlink 的 Xlink。在 root 的變更集 15 中，Xlink 會指向 Xlink 的變更集 4，但此變更集尚未複寫：

這表示將會忽略變更集 15，且在複寫它 xlink 的變更集之前，Git 用戶端將無法看到它。

可以將 GitServer 設定為略過遺失的 Xlink，如此一來，即使某些內容遺失，仍可與 Git 同步。

只需要按照下列方法，新增 unresolvedxlink.skip=true 並加入至 gitserver.conf 即可：

# skip the xlink entries that cannot be resolved
unresolvedxlink.skip=true

Git 子模組可轉譯為 Plastic SCM Xlink。Xlink 可說是已進化的子模組，能為開發者減輕不少工作壓力。

將某些 git 變更/儲存庫推送至 GitServer 時，如果有指向 git 儲存庫的子模組，但 GitServer 不知該如何處理時，作業可能會失敗。

在此案例中，有一個子模組指向名為 mduem 的儲存庫，但 GitServer 不認為它是有效的 Plastic SCM 儲存庫。

為解決此問題，必須在 Plastic 中建立名為 mduem 的儲存庫，而子模組儲存庫將被推送至 GitServer：

在此案例中，Git 子模組定義如下所示：

[submodule "mduem"]
        path = mduem
        url = git://github.com/user/mduem

假設我們要在 Git 子模組與 Plastic Xlink 之間自訂對應。

我們可以採取的做法是，將下列項目加入至 gitserver.conf 檔案 (我們可以視需要針對不同的 Git 子模組新增任意數量的項目)：

repository.mapping=git://github.com/user/mduem -> mduem-xlinked@localhost:8084 writable:true relativeserver:false

這表示儲存庫 mduem 在 Plastic 端將轉譯為 mduem-xlinked。

您可以略過特定 Git 子模組，如此它們就不會對應至 Plastic SCM 儲存庫。若要這樣做，請按照下列方法編輯 gitserver.conf：

# when a submoule points to one of the following
# git urls, it will be ignored.
ignore.submoduleUrl= git://github.com/user/mduem

您可以視需要新增任意數量的 ignore.submoduleUrl 項目。

要讓 Plastic SCM 伺服器成功啟用 GitServer，需要具備有效的 Enterprise Edition 授權。

個人版和社群版不支援 GitServer。

GitServer 可在所有支援的 Plastic SCM 伺服器平台上運作：Linux、Windows 和 macOS。

避免快轉、重定基底和刪除 Git 儲存庫上將推送至 GitServer 的認可。

避免重定基底或刪除已透過 git-to-gitrestrictions 推送至一般 git 伺服器的認可。

由於 Plastic SCM 與 Git 之間存在內部差異，因此會有快轉限制。在 Git 中，多個分支前端可以「指向」單一認可，因此單一認可能夠位於多個分支。

在 Plastic SCM 中，所有變更集都會綁定至單一分支，而且無法同時位於多個分支。因此，建議的做法是避免在原來要與 Plastic SCM 同步的 Git 儲存庫上進行快轉合併。

GitServer 不會針對匯出的儲存庫執行任何安全性檢查。

Git 用戶端可以下載整個儲存庫內容，或將變更推送至儲存庫。

請記住，您可以使用 gitserver.conf 中的 export.repo 項目，限制 GitServer 可看到的儲存庫。

GitServer 不支援異動儲存的 Git 套件。這表示套件必須以非異動儲存的格式傳送。

此為效能限制，旨在加速兩個系統之間的中繼資料和資料轉換。

若要停用 Git 端的異動儲存 (deltification) 功能，請在 Git 儲存庫上執行下列命令：

如果 GitServer 在推送期間收到具有差異的套件，將顯示下列錯誤訊息：

此訊息包含有關如何「重新封裝」Git 儲存庫以停用差異的清楚指示：

GitServer 不支援陰影複製。根據 Git 用戶端版本顯示下列錯誤訊息：

自 git 用戶端版本 1.7.2 起，我們未再發現任何相容性問題。不過，仍極力建議您盡可能使用最新 git 用戶端軟體。

git push 不會在物件匯入 Plastic SCM 時顯示任何進度。視推送大小而定，此程序可能需要數秒鐘、數分鐘或數小時的時間。

標註的標籤已正確匯入 Plastic SCM，但如果它們是從 GitServer 再次複製到 Git，則會以輕量標籤的形式匯出。

具有多個層級的分支名稱在 Plastic SCM 和 Git 中可能有所不同。

例如，Plastic SCM 分支 /main/Fix-5.0/scm003 在 Git 中將轉換為 main-Fix-5.0-scm003。

目前 GitServer 可透過 git:// 和 http:// 通訊協定存取。

之後會新增 SSH 支援。

目前 GitServer 匯出的儲存庫檔案內容已重複。這表示它們以 Plastic SCM 格式儲存在資料庫和 GitServer 儲存區資料夾內。

如果您基於任何原因需要重新建立 GitServer 對應資料夾，我們無法保證新 Git SHA 會與舊 Git SHA 相符。

以下是建立與舊 Git SHA 不相符之新 Git SHA 的動作範例：

• 如果您編輯變更集的命令。
• 如果您執行會影響任何已對應的變更集的複本 (例如，新增合併連結)。

因此，在重新建立 Git 對應後，務必建立新的 Git 儲存庫，並從 Plastic 進行複製。

如果您重複使用先前的 Git 儲存庫，您最後可能會有重複的認可 (而且當最後推送回 Plastic 時，也會有重複的變更集)。

2019 年 3 月 22 日

• 我們已使用新的對應項目來取代 cm mkrep 等棄用儲存庫系統管理命令的參考資料。

2018 年 11 月 23 日

• 我們新增了一個附註，提醒您需要進行 Plastic SCM 用戶端安裝。

2018 年 11 月 8 日

• 現在，您可以使用 http 基本驗證保護 Git 用戶端。

2018 年 11 月 2 日

• 我們新增了一項有關重新建立 GitServer 對應資料夾的新限制。

2016 年 4 月 19 日

• 現在，您可以從 Git 推送/提取至 Plastic。

2016 年 3 月 30 日

• 發佈日期。