Plastic SCM CLI ガイド

Plastic SCM は視覚的なバージョン管理システムです。しかし、コマンドラインから使用することもできます。

このガイドでは、Plastic の操作に慣れていただくために、一般的なコマンドラインインターフェース（CLI）のシナリオを順を追ってご説明します。

新規ワークスペースの作成に必要なのは、cm workspace create コマンドを使用することだけです。

そして次のコマンドを実行し、新規に作成されたディレクトリへ移動します。

これは、依然として変更セット 0 にいることを意味します。更新をまだ実行していなかったためです。デフォルトでは、ワークスペースはブランチ main を使用するよう設定されています。

次のように cm status --head を実行することで、対象ブランチの最新の変更セットを確認することができます。

最新の変更セットに更新するには、次のように入力するだけです。

その後、コピーされる対象のファイルに関する全情報のダンプがコマンドによって開始され、これは最新の変更セットへ更新がされるまで続けられます。

これで最新の変更セット（このケースでは 573）になりました。

新規ブランチを作成するには、次のように cm branch（または cm branch create）コマンドを実行するだけで済みます。

ここでは新規ブランチを作成したのみで、cm status に示されているように、まだそのブランチには切り替えていません。

開始点を指定しなかったため、新規ブランチは単に親ブランチの最新の変更セット（このケースでは main の cset 573）から始まります。--changeset 修飾子と --label 修飾子を使用して、ブランチを開始する変更セットまたはラベルを指定できます。

次は、switch コマンドを使用してワークスペースをそのブランチに切り替えます。

新規ブランチはまだ空であるため、Plastic は実際には切り替えを実行するためにワークスペース上で何も更新しませんでした。この時点では、fix-1342 は同じ cset 573 をポイントしているためです。

ワークスペース内のファイルを編集し、その後変更を検索することでそのファイルを特定します。

status は、（以前に示した）ワークスペースの設定のみでなく、変更、チェックアウト、移動、削除などが行われたファイルも表示します。

次は、FileSystem-renamed.cs を新しい場所に移動します。

それから status を実行して移動されたファイルを探します。

ここで Moved locally とは、ファイルを Plastic のコントロール外に移動したが、その移動されたファイルは引き続き以前のバージョンと 99% 同じであるため、検出は可能であることを意味します。

その後、変更を簡単にチェックインできます。

デフォルトの ci コマンドは、追加されたすべてのファイルをチェックインします。ci --all は基本的に、変更されたファイルをすべて検出してチェックインを実行するよう Plastic に指示します。そして、all は変更、削除、または移動されたファイルを指します。ci --all --private を使用してプライベートファイルを含めることもできます。

cm log このコマンドで、指定した変更セット、あるいは特定の変更セットの範囲に対して行われた変更が表示されます。

ここで、チェックインを行い、最終変更セット内で、ファイル FileSystem.cs を変更して移動したことが表示されます。

コマンド cm diff でも同様の処理が行われますが、常に対象は指定の変更セットに限定されます。

実験的な変更をしばらく試してみた後で、保留中の変更をすべて捨てて、最初からやり直すことに決めました。どうすればよいでしょうか？

まず現在のステータスを確認します。

必要なのは、すべての変更を元に戻すことだけです。このために、undo コマンドをただ繰り返して実行します。

ステータスは次のようになります。

つまり、クリーンになりました。

備考：

デフォルトでは、undo は、本当の「チェックアウト」か単なる変更済みファイルかにかかわらず、すべての変更に適用されますが、undo を特定の変更の種類に限定することができます。Plastic では「変更済みファイル」と「チェックアウト済みファイル」は少し異なり、一部のコマンドにはそれが反映されています。

上述のように、特定の変更の種類に undo を限定できます。これはフィルターオプションを使用して行います。

上述と同じ変更があるが、今回は 2 つのファイルを追加して削除したとします。

今回は、追加と削除を元に戻しますが、変更はそのままにします。これはフィルターを使用して行います。

ステータスは次のようになります。

望んだとおりになっています。

1 つの変更済みファイルを元に戻すにはどうすればよいでしょうか？

次のように、いくつかのファイルを変更したとします。

cg_main.c への変更のみを元に戻したい場合は、次のコマンドを実行します。

特定のパスの下にあるいくつかの変更を元に戻す必要がある場合は、次のようにコマンドを実行できます。

code の下にある変更を元に戻したいが、merge の下にあるものはそのままにしたいという場合は、次のようにできます。

意図したとおりのステータスになりました。

ワイルドカードを使用して、元に戻す対象をさらに厳密に指定することもできます。

今度は、code の下のヘッダーファイルを元に戻しながらも、ソースファイルはそのままにしたいと思います。

意図したとおりのステータスになりました。

ここでは、指定したパスにある特定のファイルのみをチェックインします。次のように変更済みのファイルがいくつかあります。

しかし、チェックインしようとしているのは q3radiant\alpha 内のもののみです。したがって、次のように checkin コマンドを実行します。

Plastic SCM では、ファイルを単に変更することも、チェックアウトすることもできます。つまり、edit-checkin または checkout-edit-checkin という 2 つのワークフローを行うことができます。

ファイルのチェックアウトとは、これからファイルを変更すると Plastic に対して通知することです。これで、ファイルがチェックアウト済みファイルの内部リストに追加されます。

チェックアウトを使用する理由は主に 3 つあります。

1. Perforce（p4 編集）または ClearCase（チェックアウト）を使用していたために、この方法に慣れています。この方法で操作する場合は、ワークスペースで保護のためにファイルを読み取り専用に設定することをお勧めします。こうしておくと、ファイルをチェックアウトする前に変更するとファイルシステムによって警告されます。
   
2. 排他的チェックアウト（ロック）を使用する必要がある場合は、ファイルを編集する前にチェックアウトする必要があります。ロックの詳細については、こちらをご覧ください。
3. 大規模なコードベース（ファイル数 > 500,000）の作業を行っている場合は、すべての操作の速度を上げるためにチェックアウトの使用をお勧めします。cm status によって、ワークスペース全体での変更箇所を確認します。チェックアウトを使用する場合、status コマンドでは、チェックアウトリスト内のファイルのみがリスト表示されます。ディスクへのアクセスは必要ありません。

チェックアウト - 編集 - チェックインの形式での作業は、非常にシンプルです。すべきことは、ファイルを編集する前に cm co コマンドを実行するだけです。

ここで、Bmp.cpp が変更済みではなくチェックアウトとしてマークされていることを確認できます。

次の例に示すように、cm mv コマンドを使用して移動されたファイルは、チェックアウトのもう 1 つの形式とみなされます。

aselib.c が、「ローカルで移動」されたのではなく、ただ移動されたことが表示されます。

チェックアウト済みの 2 つのファイルを次のようにチェックインできます。

--all 修飾子を checkin に指定しなかったため、チェックアウト済みファイルのみがチェックインされ、Socket.cs ファイルは保留中の変更のままになります。

CLI からのマージは非常に簡単で、cm merge コマンドを実行するだけです。

これまでのすべての変更は main/fix-1342 ブランチで行っていたので、変更をマージするために main に切り替えます。この時点での状況は次のようになります。

main に切り替えます。

Socket.cs をそのままにしていたので、まだ切り替えができません。変更を取り消してから、もう一度切り替えを試みます。

switch コマンドによってワークスペースが更新され、ブランチ上で変更したすべてのファイルが main 内のバージョンに置き換えられます。

ステータスは次のようになります。

これはブランチエクスプローラーにも反映されます。

ここで merge コマンドを実行します。

修飾子なしでマージを実行すると、何がマージされるかのプレビューのみが出力されるので、これから起こることを理解するのに非常に役立ちます。

マージをもう少し面白くするために、FileSystem-renamed.cs を変更します（このファイルをブランチ上で移動して、名前変更したことを思い出してください）。

マージを再実行し、コメントを追加します。

最後の行を見るとわかるように、FileSystem-renamed.cs は 2 人の共同作成者によって変更されたので、3 方向マージが必要です。

そこで、修飾子 --merge（マージを実際に実行するため）と --commentsfile（ファイルのコンテンツから新しい変更セットのコメントを設定するため）を merge コマンドに追加して、マージを実行します。

ご覧のように、これによってすべてのマージがワークスペースに適用され、設定済みの 3 方向マージツール（デフォルトでは Plastic の Xmerge）が FileSystem.cs 内の競合を解決するために起動されます。どのように FileSystem.cs の移動と名前変更が正しく行われ、ファイルのコンテンツが正しくマージされているかに注目してください。

status コマンドを実行すると、マージされたすべてのファイルがチェックアウト済みステータスになっています。

ここでは新しいステータス Replaced が使用されています。これは効率のために、バージョン管理にファイルをコピーする代わりにブランチ上の元の場所へのポインターが格納されることを意味しており、FileSystem.cs ファイルはマージされたので実際に「チェックアウト済み」としてマークされます。

この時点で、ブランチエクスプローラーは次のようになります。

点線は、マージがまだ進行中であり、まだチェックインされていないことを意味します。

あとは cm ci コマンドを使用してチェックインするだけです。

新しくマージされたコードにラベルを付けるには、次のように cm label コマンドを実行します。

ブランチエクスプローラーの表示は次のようになります。

特定のサーバー上のリポジトリをリスト表示するのは簡単で、repository [list] コマンドを使用するだけです。

デフォルトでは、repository によって default server（設定ウィザードで設定し、client.conf に書き込まれるサーバー）内のリポジトリが表示されます。

次のように別のサーバーも入力できるので、repository list コマンドはサーバーでの接続の問題を診断するのに非常に役立ちます。

Plastic SCM では、ユーザーのマシン上にあるワークスペース（少なくとも Plastic SCM によって認識されているもの。ユーザーは常にどこかからワークスペースをコピーすることができ、それは Plastic のリストには含まれないため）のリストが保持されます。

このガイドでは、CLI を使用してできるすべてのことのほんの一部を紹介します。他にどのようなコマンドを使用できるかについては、cm showcommands を実行して確認できます。

また、すべてのコマンドで cm <command> --usage を使用してそれぞれのオプションに関する組み込みのドキュメントを確認することも、cm <command> --help を使用してより包括的なヘルプを例とともに確認することもできます。

CLI が期待通りに動作しない場合は、Plastic のサポートチームにお問い合わせください。サポートチームが問題を診断するのを支援するために、有用な診断情報が入っている zip ファイルを送信してください。zip ファイルは、次のように cm support を使用して生成できます。

ローカルの移動と削除を含む、大量の変更をソースファイルに加えるスクリプトを実行しました。status は次のようになっています。

ファイルが移動または削除されているこの時点で、これらの変更をソース管理下に置くにはどうすればよいでしょうか？問題ありません。move または remove コマンドを実行し、管理対象の変更を作成するだけです。

私はいくつかの実験的なコード変更を行っているのですが、それらをソース管理内に保存して、同僚と共有できるようにしたいと考えています。ただし、まだ実験段階のアイデアなので、いずれのブランチにもチェックインはしたくありません。

このような場合、私は shelveset コマンドを使用して、いずれのブランチにも関連付けられていない変更セットをコミットします。

私はリポジトリでの自分のローカルの変更をシェルブしました。私は自分のブランチを別のワークスペースに切り替え、通常と同じように作業を続けています。後で、前に作業していた実験的変更に戻りたいと考えています。これを行う場合、私は apply サブコマンドを使用して、シェルブセットを自分のワークスペースに適用します。

Plastic CLI の機能の中でも見過ごされがちな機能なのですが、- オプションを使用して、stdin から引数を 1 つずつ読み取る機能があります。次に例を示します。

これがなぜ便利かというと、他のコマンドからの出力を 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 日

• CLI の新しいラベル関連のコマンドの導入に伴い、本文中の cm mklabel の説明を cm label に変更しました。

2019 年 2 月 8 日

• ガイド全体で、新しい出力形式とオプションの変更を反映するために cm status の出力を更新しました。
• cm status --head を使用してヘッド変更セットを表示する方法を説明するために、「新規ワークスペースを作成する」の章を編集しました。
• cm support を使用して診断情報を生成する方法を説明するために、新しい章「ヘルプを取得する」を追加しました。
• cm mv と cm rm を使用してローカルの変更をソース管理下に置く方法を説明するために、新しい章「ローカルの変更」を追加しました。
• 例に含まれるいくつかのパスを読みやすいように短くしました。

2018 年 9 月 4 日

• マージ操作中にコメントを含める方法（-c 修飾子と --commentsfile 修飾子）を説明するために、「マージ」の章を編集しました。

2018 年 2 月 26 日

• Plastic でサポートされているさまざまなオブジェクト指定の定義を確認するには、cm help objectspec コマンドを実行します。

2015 年 8 月 24 日

• cm log と cm diff の例が更新され、これらのコマンドでワークスペースのフルパスではなく、ワークスペースのルートの相対パスがデフォルトで出力されるようになりました。
• lrep および lwk コマンドの形式文字列を改善しました。