Plastic SCM CLI 指南

Plastic SCM 是一个可视化的版本控制系统。但是，也可以从命令行使用它。

本指南将逐步引导您了解常见的命令行界面 (CLI) 场景，以帮助您熟悉 Plastic。

要创建新的工作区，只需使用 cm workspace create 命令。

然后，我转到新创建的目录：

这意味着我仍在变更集 0 上，因为我还没有运行更新。默认情况下，工作区配置为使用 main 分支。

我可以通过运行 cm status --head 来检查分支上的最新变更集是什么：

我只需输入以下命令即可更新到最新变更集：

该命令随后将开始转储有关正在复制的文件的所有信息，直到我获得最新变更集。

现在，我位于最新变更集上：在我的示例中是 573。

创建新分支只需运行 cm branch（或 cm branch create）命令：

请注意，我刚刚创建了新分支，但我还没有切换到这个分支，如 cm status 所示：

由于我没有指定起点，因此新分支直接从父分支上的最新变更集开始，在我的示例中是 main 分支的变更集 573。我可以使用 --changeset 和 --label 修饰符来指定给定的变更集或标签作为我的分支起点。

现在我将通过简单地使用 switch 命令将工作区切换到分支：

新分支仍然是空的，所以 Plastic 在进行切换时实际上没有更新工作区上的任何内容，因为此时 fix-1342 指向相同的变更集 573。

我将在我的工作区中编辑一个文件，然后我将搜索更改以找到该文件：

status 不仅显示工作区配置（如我之前所示），还显示已更改、已签出、已移动、已删除的文件等。

现在我要将 FileSystem-renamed.cs 移动到一个新位置：

然后，我运行 status 以查找已移动的文件：

其中，已在本地移动表示我将文件移到了 Plastic 控制范围之外，但还是能够找到已移动的文件，因为该文件仍然与先前的版本有 99% 的相似度。

然后我可以轻松签入我的更改：

默认的 ci 命令会签入所有已添加的文件。使用 ci --all 本质上就是在告诉 Plastic：检测所有更改并执行签入。而 all 表示已更改、已删除或已移动的文件。我们还可以使用 ci --all --private 来包含私有文件。

cm log 命令显示针对给定变更集或在特定变更集范围内所做的更改：

在这里可以看到在我签入的最后一个变更集内，我修改并移动了文件 FileSystem.cs。

命令 cm diff 具有类似的功能，但它始终仅限于给定的变更集：

在尝试了一些实验性更改之后，我决定丢弃所有待定更改并从头开始。我怎么操作？

现在检查我的当前状态：

我的需求仅仅是撤销所有更改。为此，我只需以递归方式运行 undo 命令：

现在我的状态是：

这意味着我是全新的了。

备注：

• 默认情况下，undo 适用于所有更改，无论这些更改是真正的“签出”还是仅仅是已更改的文件，但您也可以将 undo 限制到特定的更改类型。在 Plastic 中，“已更改的文件”和“已签出的文件”略有不同，一些命令可以反映这一点。

我刚才提到，我可以将撤销 (undo) 限制到特定的更改类型。我通过筛选条件选项来做到这一点：

假设我有一些与上面相同的更改，但这次我添加和删除了几个文件：

这次我想撤销添加和删除操作，但让更改保持不变。我通过筛选条件来做到这一点：

现在我的状态是：

结果正如我所愿。

如果您只想撤销单个已更改的文件，该怎么办？

我修改了几个文件：

但我只想撤销对 cg_main.c 的更改。我将运行以下命令：

现在假设我只需要在某些路径下撤销一些更改：

我只想撤销 code 下的更改，但保留 merge 下的更改：

现在的状态符合预期：

我可以使用通配符更精确地定向执行撤销：

这次我只想撤销 code 下的头文件但保留源文件：

现在的状态符合预期：

现在假设我只想签入给定路径上的某些文件。我有一些修改过的文件如下：

但我只想签入 q3radiant\alpha 中的文件，所以我按以下方式运行 checkin 命令：

在 Plastic SCM 中，可以简单地更改文件，也可以签出文件。因此，您可以遵循两个工作流程：编辑-签入或签出-编辑-签入。

签出某个文件相当于告诉 Plastic“嘿，我要修改文件了”，所以 Plastic 就会将文件添加到一个内部签出文件列表中。

使用签出操作通常有 3 个主要原因：

1. 您习惯于使用这种操作方式，因为您是 Perforce（p4 编辑）或 ClearCase（签出）用户。如果您采用这种操作方式，有可能您还喜欢将工作区中的所有文件设置为只读以作为某种“保护”措施，这样文件系统就会在您在签出文件之前修改文件时发出警告。
   
2. 如果需要使用独占签出（锁定），则需要在编辑文件之前签出文件。在此处阅读有关锁定的更多信息。
3. 如果所处理的代码库很庞大（超过 500k 文件），那么您可能希望使用签出功能来加速所有操作。cm status 可遍历工作区以寻找更改。如果使用签出，则 status 命令只列出签出列表中的文件，不需要访问磁盘。

“签出-编辑-签入”工作流程非常简单：只需在编辑任何文件之前运行 cm co 命令。

现在可以看到 Bmp.cpp 被标记为已签出而不只是已更改。

使用 cm mv 命令移动的文件被视为另一种形式的签出，如以下示例所示：

您会看到 aselib.c 不是“locally moved”而只是“moved”。

我可以按如下方式签入两个已签出的文件：

由于我没有在 checkin 中指定 --all 修饰符，因此只签入了已签出的文件，而 Socket.cs 文件仍然是待定更改：

从 CLI 进行合并非常容易，只需运行 cm merge 命令即可。

到目前为止，我都是在 main/fix-1342 分支中进行的所有更改，现在我将切换到 main 以合并我的更改。此时我的情况如下：

我将切换到 main：

好吧，我还不能切换，因为我遗留了 Socket.cs...我会先撤销更改，然后再尝试切换：

switch 命令会更新我的工作区，将我在分支上更改的所有文件替换为 main 中的版本。

现在我的状态如下：

这也反映在分支资源管理器中：

我现在将运行 merge 命令：

不带任何修饰符的合并只会打印将要合并的内容的预览，因此了解将要发生的情况非常有用。

为了使合并更有趣，我将修改 FileSystem-renamed.cs（请注意该文件在分支上已移动和重命名）：

现在我要重新运行合并，并添加注释：

如最后一行所示，FileSystem-renamed.cs 现在需要三向合并，因为该文件已被两个参与者修改。

现在我将运行合并，将 --merge（实际执行合并）和 --commentsfile（根据文件内容设置新变更集的注释）修饰符添加到 merge 命令：

可以看到，这会将所有合并应用到工作区，并启动您配置的三向合并工具（默认情况下是 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 的行为可能不符合您的预期，因此您会希望与我们出色的支持团队联系。为了帮助支持团队诊断您的问题，您可以向他们发送一个包含有用诊断信息的 zip 文件，为此，您可以使用 cm support 命令生成该文件，如下所示。

我刚刚运行了一个脚本，该脚本对我的源文件进行了大量更改，包括本地移动和删除。我的 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 mkbr 命令替换为 cm branch。

2019 年 3 月 21 日

• 我们更新了关于使用 cm shelveset 命令搁置更改的章节。

2019 年 3 月 13 日

• 我们将 cm mklabel 的引用更改为 cm label，使其与 CLI 中的新标签相关命令相一致。

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 命令的格式字符串。