Plastic SCM CLI 指南

Plastic SCM 是一個視覺化版本控制系統。但該系統也應能透過命令列使用。

本指南會逐步引導您瞭解常見的命令列介面 (CLI) 案例，協助您熟悉如何使用 Plastic。

若要建立新的工作區，您唯一要做的就是使用 cm workspace create 命令。

然後，我會移至新建立的目錄：

這表示我仍在變更集 0 上，因為我尚未執行更新。根據預設，此工作區會設定為使用分支 [主要]。

我可以藉由執行 cm status --head 來查看分支上的最新變更集：

只需輸入下列命令，即可更新至最新狀態：

然後，此命令將開始傾印複製的檔案的所有相關資訊，直到我更新到最新狀態為止。

現在我已在最新的變更集上：我的案例為 573。

建立新分支只需執行 cm branch (或 cm branch create) 命令：

請注意，我剛建立了新分支，但我尚未切換至該分支，如 cm status 所示：

因此，我並未指定起點，新分支會直接從上層分支上的最新變更集開始，在我的案例中就是 main 分支的 cset 573。我可以使用 --changeset 和 --label 修飾詞，指定要從哪個特定變更集或標籤開始我的分支。

現在，我要使用切換命令來將工作區切換至分支：

新分支仍為空白狀態，因此，Plastic 實際上並未在工作區上更新任何內容以進行切換，因為此時 fix-1342 指向同一個 cset 573。

我要在我的工作區編輯檔案，然後搜尋變更來找出該檔案：

status 不僅會顯示 wk 設定 (如同之前所示)，也會顯示已變更、簽出、移動、刪除的檔案。

現在，我要將 FileSystem-renamed.cs 移至新位置：

我會執行 status 尋找己移動的檔案：

其中 [在本機移動] 是指我已將檔案移至 Plastic 控制範圍之外，但它能夠找出已移動的檔案，因為它與先前版本之間仍具有 99% 的相似性。

然後，我可以輕鬆簽入我的變更：

預設的 ci 命令會簽入所有新增的檔案。透過 ci --all，我基本上是在告訴 Plastic：偵測已變更的所有內容，並執行簽入。all 表示：已變更、刪除或移動的檔案。我們也可以使用 ci --all --private 來包含私人檔案。

cm log 命令會顯示在指定 cset 上或特定 cset 範圍內所做的變更：

在這裡可以看到其顯示我在簽入的最後一個變更集中修改和移動檔案 FileSystem.cs 的過程。

cm diff 命令會執行類似的動作，但始終限定於指定的 cset：

工作一段時間後，在嘗試一些實驗性質變更的同時，我決定捨棄所有暫止的變更，並從頭開始。該如何進行？

現在檢查我的目前狀態：

我只想要復原所有變更。為了這樣做，我只是以遞迴方式執行 undo 命令：

現在我的狀態是：

這表示我處於全新狀態。

一個備註：

• 根據預設，無論變更是否真的「簽出」或只是已變更的檔案，undo 都會套用至所有變更，但您可以將 undo 限制到特定變更類型。在 Plastic 中，「已變更的檔案」和「已簽出的檔案」略為不同，而某些命令會反映其差異。

如先前所述，我可以將復原限制到特定變更類型。我可使用篩選選項來執行此操作：

假設我有與上述相同的變更，但這次我已新增和刪除幾個檔案：

這次我要復原 [新增] 和 [移除]，但會將變更保留原狀：我使用篩選來執行此操作：

現在我的狀態是：

正符合我的需要。

如果您只想要復原單一已變更的檔案，該怎麼做？

我修改了幾個檔案：

但我只想要復原對 cg_main.c 所做的變更。我將執行下列命令：

現在，假設我只需要復原某些路徑底下的一些變更：

我只要復原 code 底下的變更，但保留 merge 底下的變更：

現在狀態如同預期：

我可以將目標鎖定在復原，甚至可以使用萬用字元提高精確度：

這次我只要復原 code 底下的標題檔案，但保留原始檔案：

現在狀態如同預期：

現在，假設我只要在指定路徑簽入某些檔案。我有許多已修改的檔案，如下所示：

但我只想要簽入 q3radiant\alpha 內的檔案，因此我執行 checkin 命令，如下所示：

在 Plastic SCM 中，可以只變更檔案，也可以將其簽出。因此，您可以遵循按照兩個工作流程：編輯-簽入或簽出-編輯-簽入。

簽出檔案表示告訴 Plastic：「嘿，我要修改檔案了」，因此，它會將檔案新增至已簽出檔案的內部清單。

使用簽出有 3 個主要原因：

1. 您已習慣以這種方式工作，因為您是來自 Perforce (p4 編輯) 或 ClearCase (簽出)。如果您以這種方式工作，您很可能也會喜歡將工作區中的所有檔案設定為唯讀，做為某種「保護」措施，這樣如果您在簽出前修改檔案，檔案系統就會向您發出警告。
   
2. 如果您需要使用獨佔簽出 (鎖定)，則必須先編輯檔案，才能簽出檔案。在這裡閱讀更多有關鎖定的資訊。
3. 如果您使用大型程式碼庫 (>50 萬個檔案)，則您可能會喜歡使用簽出來加速所有作業。cm status 會逐步引導您在工作區中尋找變更。如果您使用簽出，則狀態命令只會列出簽出清單中的檔案，不需要進行磁碟存取。

以簽出-編輯-簽入的方式工作非常簡單：只需要在編輯任何檔案前執行 cm co 命令即可。

現在您可以看到，Bmp.cpp 已標示為已簽出，而不只是已變更。

使用 cm mv 命令移動的檔案會視為另一種形式的已簽出，如下列範例所示：

您會看到 aselib.c 並非「在本機移動」，而只是已移動。

我可以簽入兩個已簽出的檔案，如下所示：

因為我並未在 checkin 中指定 --all 修飾詞，因此只簽入了已簽出的檔案，且 Socket.cs 檔案仍為暫止的變更：

從 CLI 進行合併的方法相當簡單，只要執行 cm merge 命令即可。

到目前為止，我在 main/fix-1342 分支中進行所有變更，因此我將切換至 main 分支以合併我的變更。我目前的情況如下：

我將切換至 main：

抱歉，目前還無法切換，因為我忘了我的 Socket.cs...我將先復原變更，再嘗試重新切換：

切換命令會更新我的工作區，使用 main 分支中的版本取代我已在分支上變更的所有檔案。

現在，我的狀態如下所示：

這也會反映在分支瀏覽器中：

我現在要執行 merge 命令：

不含任何修飾詞的合併只會列印即將合併內容的預覽，這樣有助於瞭解即將發生的情況。

為了讓合併更加有趣，我將修改 FileSystem-renamed.cs (別忘了，它已在分支上移動和重新命名)：

現在，我將重新執行合併，並新增註解：

如最後一行所示，FileSystem-renamed.cs 現在需要 3 向合併，因為兩位貢獻者已做過修改。

現在，我將執行合併，將 --merge (實際執行合併) 和 --commentsfile (從檔案內容設定新變更集的註解) 修飾詞新增至 merge 命令：

如您所見，它會將所有合併套用至工作區，並啟動您已設定的 3 向合併工具 (預設為 Plastic 的 Xmerge)，以解決 FileSystem.cs 中的衝突。請注意 FileSystem.cs 如何正確移動和重新命名，且檔案內容已正確合併。

現在，如果執行 status 命令，所有已合併的檔案都會處於已簽出狀態：

您現在會看到使用中的新狀態：已取代，這表示，為提高效率會儲存指向分支上原始位置的指標 (而不是複製版本控制中的檔案)，然後 FileSystem.cs 檔案在合併後標示為真正的已簽出。

此時，我的分支瀏覽器如下所示：

虛線表示合併仍在進行中，尚未簽入。

現在，我只需直接使用 cm ci 命令簽入：

為新合併的程式碼加上標籤需要執行 cm label 命令，如下所示：

分支瀏覽器現在顯示如下：

列出指定伺服器上的儲存庫輕而易舉，只要使用 repository [list] 命令即可：

根據預設，repository 會顯示預設伺服器中的儲存庫，該伺服器是您在設定精靈中設定的伺服器，並且已寫入 client.conf 中：

repository list 命令非常實用，可診斷與伺服器的連線問題，因為您也可以輸入不同伺服器，如下所示：

Plastic SCM 會保留您機器上擁有的工作區清單 (至少會有它知道的工作區，因為您可以隨時從某個位置複製工作區，而 Plastic 的清單上不會有該工作區)。

本指南僅簡介您可以透過 CLI 進行的所有操作。如需瞭解其他可用命令，您可以執行 cm showcommands。

此外，所有命令均隨附於其選項 cm <command> --usage 的內建文件，以及更完整且包含範例的說明 cm <command> --help

偶爾可能會發生 CLI 運作不如預期的情況，這時候您便需要與我們的專業支援團隊聯絡。為了協助他們診斷您的問題，您可以使用如下所示的 cm support 命令來產生一個 zip 檔案，然後再將這個滿載實用診斷資訊的檔案傳送給他們。

我剛執行了對原始檔案做出大量變更的指令碼，包括本地移動和刪除。我的 status 現在如下所示：

既然這些檔案都已經移動或刪除，如何讓這些變更受到原始檔控制？這不是問題。我們可以直接執行 move 或 remove 命令，並建立受控變更：

我正在處理某些實驗性質的程式碼變更，我想要將它們儲存在原始檔控制中，而且可能會與我的同事進行共用，但我不想將其簽入任何分支，因為它們只是我正在嘗試的構想。

在此情況下，我實際上使用 shelveset 命令來認可未與任何分支相關聯的變更集。

我已將本地變更擱置在儲存庫上。我將我的分支切換至另一個工作區，並繼續像平常一樣使用。之後，我要回到我之前處理的這些實驗性質變更。為此，我使用 apply 子命令來將擱置集套用至我的工作區。

Plastic CLI 的一項經常遭到忽略的功能是使用 - 選項逐一從 stdin 讀取引數，如下所示：

這為何很實用？因為這表示我們可以透過管道將輸出從其他命令傳送至 cm。

下列命令可接受管道路徑：

• add
• applylocalchanges
• checkin
• checkout
• getstatus
• partialcheckin
• remove
• shelveset create
• undocheckout
• undochange
• uncounchanged
• wktreenodestatus

我們來看一些範例！

• 我可以從 Windows dir 命令使用管道，以輕鬆從工作區中移除符合模式的所有檔案： >dir /S /B *.txt | cm rm - Item c:\Users\pablo\wkspaces\mcga\a.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\b.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\c.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\z.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\lockwkB\file.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\a.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\b.txt has been removed. Item c:\Users\pablo\wkspaces\mcga\src_dir\dest_dir\c.txt has been removed.
• checkout 命令可遞迴為管道目錄引數： Directory of c:/mcga/pipe 11/05/2020 19:48 <DIR> . 11/05/2020 19:48 <DIR> .. 11/05/2020 17:57 <DIR> dir 11/05/2020 19:46 <DIR> dir2 11/05/2020 19:47 12 dirlist 1 File(s) 12 bytes 4 Dir(s) 23,714,631,680 bytes free c:/mcga/pipe>type dirlist dir dir2 c:/mcga/pipe>type dirlist | cm partial co -r - The selected items are about to be checked out. Please wait ... Item c:/mcga/pipe/dir was correctly checked out Item c:/mcga/pipe/dir/file was correctly checked out Item c:/mcga/pipe/dir2 was correctly checked out Item c:/mcga/pipe/dir2/file2 was correctly checked out

現在，您可以盡量搭配使用管道和 cm 來建置酷炫的指令碼！

2020 年 6 月 10 日

• 在使用管線一章中，您現在可以找到有關 checkout 命令如何遞迴為管線目錄引數的範例。

2020 年 6 月 8 日

• 我們已編輯 cm status 範例，因為其輸出現在會依預設包含標頭變更集。

2020 年 1 月 21 日

• 現在已可以更新目前整個工作區，而不指定任何路徑。

2019 年 5 月 16 日

• 我們新增了一個有關透過 Plastic CLI 使用管線的章節。

2019 年 3 月 26 日

• 我們已更新有關如何復原變更以使用新 cm undo 命令的範例。

2019 年 5 月 14 日

• 我們已使用新的對應項目來取代 cm mkwk 等棄用工作區系統管理命令的參考資料。

2019 年 3 月 22 日

• 我們已使用新的對應項目來取代 cm lrep 等棄用儲存庫系統管理命令的參考資料。
• 我們已編輯建立新分支並切換至該分支一章，使用 cm branch 取代已棄用的 cm mkbr 命令。

2019 年 3 月 21 日

• 我們已更新一個有關使用 cm shelveset 命令擱置變更的章節。

2019 年 3 月 13 日

• 我們已將 cm mklabel 的參考資料變更為內嵌於 CLI 中新標籤相關命令的 cm label。

2019 年 2 月 8 日

• 我們已更新整個指南的 cm status 輸出，以反映新輸出格式和選項的變更。
• 我們已編輯建立新工作區一章，說明如何使用 cm status --head 來檢視標頭變更集。
• 我們新增了一個新的取得說明章節，說明如何使用 cm support 來產生診斷資訊。
• 我們新增了一個新的本地變更章節，說明如何使用 cm mv 和 cm rm 讓本地變更受到原始檔控制。
• 我們已縮短範例中的一些路徑，以改善可讀性。

2018 年 9 月 4 日

• 我們已編輯合併一章，說明如何在合併作業期間包含註解 (-c 和 --commentsfile 修飾詞)。

2018 年 2 月 26 日

• 執行 cm help objectspec 命令，以瞭解 Plastic 支援的不同物件規格的定義。

2015 年 8 月 24 日

• cm log 和 cm diff 範例已更新：現在這些命令會依預設列印工作區根相對路徑，而不是完整的工作區路徑。
• lrep 和 lwk 命令的改善格式字串。