Cm find の例

どのようなバージョン管理システムでも、使用状況に関する情報や変更されているファイルについての情報を取得したり、特定の変更や特定のブランチを単純に検索したりする必要が頻繁に生じます。

そのための最良の方法は、クエリを使用することです。そこで、Plastic SCM を作成するときに cm find と呼ばれる非常に強力なクエリシステムを追加しました。このコマンドを使用して、変更セット、ブランチ、ラベル、マージ、およびコードレビューに関する詳細な情報を取得できます。

find コマンドは GUI 内のビューのカスタマイズにも使用できます。

この記事では、cm find コマンドで対処できるいくつかのシナリオについて例を交えて説明します。それらは Plastic SCM でできることのごく一部です。それぞれの例には質問、解決の手順と予期される出力が含まれており、どのような種類の情報が返されるかを理解するのに役立ちます。

特定の期間にユーザーによって作成されたブランチを取得してから、特定の属性でフィルタリングします。

使用可能なすべてのブランチの取得を開始します。

必要なのは自分のブランチだけなので、ユーザーでフィルタリングします。

ユーザー別にフィルタリングした後は、このスプリントに関連するブランチのみが必要であるため、次のように特定の日付以降に作成されたブランチを探します。

次のように、形式化された出力を使用できます。

いよいよ、特定の属性を探します。内部の機能ライフサイクルに応じて、各ブランチがメインブランチに統合されるには事前にテストに合格する必要があります。

ブランチがテストに合格すると、"test" 属性が "passed" に設定されます。このため、属性名と属性値を使用してフィルタリングします。

次の表に、現在 cm find branch コマンドで使用できるさまざまなフィルタリングオプションを示します。

* 条件 date は、ブランチビューの「作成日」列に対応しています。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find branch コマンドで使用できるさまざまな出力オプションを示します。

変更セットについてたくさんの情報を見つけることができます。コメントはその中の 1 つにすぎません。すぐに情報を得るには、cm log を使用して独自のフィルタリング（シェルコマンドの使用）を実行するか、cm find を使用して操作を行うことができます。

このサンプルでは、あるブランチに属しているすべての変更セットについて日付とコメントを取得します。

ここにすべての変更セットが表示されており、「solution」という単語を探します。ここでは簡単に見つかりますが、数百の変更セットがある場合には時間がかかる面倒な作業です。特定の単語によるフィルタリングには、SQL 構文 LIKE および % を使用して近似値検索を行います。コメント全文を探しているわけではないためです。

次のコマンドを使用して、変更セットをレプリケーション日ごとに照会することもできます（最終レプリケーション日を取得する方法については、後ほど紹介します）。

returnparent を使用すると、特定の変更セットやリビジョンの親を取得することができます。これで、その変更セットより前に何が起こったかを知りたい場合は、次のように照会することができます。

次の表に、現在 cm find changeset コマンドで使用できるさまざまなフィルタリングオプションを示します。

* 条件 changesetid、date、owner はそれぞれ、変更セットビューの「名前」、「作成日」、「作成者」列に対応しています。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find changeset コマンドで使用できるさまざまな出力オプションを示します。

ブランチを指定すると、期間の開始点以降のすべてのレプリケーション操作を時系列で取得できます。

最後の日付のみが必要な場合は、Powershell または Bash を使用して検索結果を日付でフィルタリングし、最後の行を選択します。

Powershell：

Bash：

結果：

次の表に、現在 cm find replicationlog コマンドで使用できるさまざまなフィルタリングオプションを示します。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find replicationlog コマンドで使用できるさまざまな出力オプションを示します。

すべてのラベルを取得するには、次のコマンドを使用できます。

また、特定のブランチで作成されたすべてのラベルを取得するには、次のコマンドを使用できます。

codice で開発用のメインブランチを保持し、「Fix」ブランチで現在のバージョンと旧バージョンをサポートしている場合、特定のリリースを含んだブランチを検索するには、次のようにします。

ご覧のように、ラベル BL237 は main ブランチから取得されました。

ラベルの日付を取得して、後から、そのブランチでその期間に作成された変更セットを確認します。2 つ（以上）のラベルの情報を取得するのは簡単です。

次の表に、現在 cm find label コマンドで使用できるさまざまなフィルタリングオプションを示します。

* 条件 date は、ラベルビューの「作成日」列に対応しています。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find label コマンドで使用できるさまざまな出力オプションを示します。

属性は、区別なく、ブランチ、変更セット、ラベルに対して適用できます。まず必要になるのはオブジェクト ID です。これは、ブランチに対してクエリを実行するときに ID を指定して取得できます。

取得したら、次のコマンドを使用して属性リストを取得できます。

このケースでは、属性名は "status"、属性値は "Passed" です。

これら 2 つのコマンドを Powershell スクリプトを使用して結合できます。

または、bash スクリプトを使用します。

出力は前と同じです。

次のクエリを実行しても、同じ出力が得られます。

いくつかのオブジェクトに特定の属性を設定したと仮定してみましょう（このケースではテストの "status"）。含んでいるオブジェクトに関係なく、それらの属性に対してクエリを実行できます。

次の表に、現在 cm find attributes コマンドで使用できるさまざまなフィルタリングオプションを示します。

* 条件 date と type はそれぞれ、属性ビューの「作成日」列と「名前」列に対応しています。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find attributes コマンドで使用できるさまざまな出力オプションを示します。

前の例では特定の変更セットを取得しました。次は、その中で変更が加えられたファイルについて詳細を確認する必要がある場合があります。find revision はその目的で使用できます。

必要なのはファイルとフォルダーのパスのみであるため、カスタム形式を指定します。

また、一部のコマンドラインヘルプ（Linux の場合は grep、Windows Powershell の場合は where）を使用して、フォルダー別にフィルター処理することもできます。

Powershell：

Bash：

すると、出力は次のようになります。

ブランチのリビジョン情報は、そのブランチの変更セットすべてを検索することでも取得できます。まず、次のようにあるブランチの特定の期間に変更が加えられたすべての項目を取得します。

後でお気に入りのシェルツール（ここでは PowerShell）を使用して、その情報をフィルタリングできます。

bash を使用する場合、行はこのようになります。

予期される出力はこのようになります。

次の表に、現在 cm find revisions コマンドで使用できるさまざまなフィルタリングオプションを示します。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find revisions コマンドで使用できるさまざまな出力オプションを示します。

マージの場合はどうでしょう？特定のブランチや変更セットとの間で実行されたマージを追跡することは可能です。

ブランチがどこで統合されたかを知りたい場合は、次のコマンドを入力することができます。

特定のブランチに統合されるブランチを確認するためのコマンドを次に示します。

上記のコマンドでは、format フラグを使用してブランチ名だけを返すことで、出力をカスタマイズすることもできます。たとえば、2 つ目のコマンドは次のようになります。

または：

find merge はすべての種類のマージ（通常のマージ、チェリーピックマージ、減法マージ）を返すことを忘れないでください。

そのため、特定のブランチへの間隔マージを取得できます。

この質問には、2 つのクエリ（ブランチの検索、マージの検索）といくつかの Powershell ハッキングを使用して答えることができます。次のコードを PS1 ファイルに配置して、Powershell コンソールから実行します。

サンプル出力は次のようになります。

このコードは次のアクションを実行します。

1. このスプリントからのすべてのブランチを検索します。
2. このスプリントからのすべてのマージを検索し、ソースブランチのみを返します。
3. $allbranches の出力の形式を変更して、両方のリストが同じ形式になるようにします。
4. 「マージ」のリストに allBranches リストのブランチが含まれているかどうかを調べます。含まれていないブランチは、統合されていません。

これと同等の Bash のコードは次のようになります。

このコードは、次のことを実行します。

1. このスプリントに属するすべてのブランチを検索します。
2. このスプリントに属するすべてのマージを検索し、そのソースブランチのみを返します。
3. このスプリントからの、マージ済みブランチのリストに存在しないすべてのブランチを出力します。

次はこのシナリオについて確認します。

別のブランチへ統合されてしまっているもの（そのため、そのブランチへのマージは破棄する必要がある）の中で、統合保留中の変更セット（図中オレンジで示された変更セット）を保持しているブランチについて検索します。実はこれは、1 つのクエリと、後処理をちょっと Powershell コードを使うことで、できてしまいます。

サンプル出力は次のようになります。

このコードは次のアクションを実行します。

1. 特定の日付より後に実行されたすべてのマージとソース変更セットを取得します。
2. 同じマージ元とマージ先を持つマージをフィルタリングします。
3. すでにマージされているものを破棄するために、そのマージのみを含むリストを取得します。
4. find branches の出力の形式を変更して、find merge と同じ形式にします。
5. 比較して、その期間にマージされているものの、マージが保留中の変更セットを含んでいるブランチをフィルタリングします。

Bash を使用している場合は、次のコードを代わりに使用します。

ここで行っていることを整理してみましょう。

1. 特定の日付より後に実行された全マージを、ソース変更セットを示した上でファイルに書き込みます。同時に、すべてのマージ元ブランチを別のファイルに書き込みます。
2. 既存のすべてのブランチをブランチ名と変更セットで反復処理して、1 番目のファイル（マージ元のブランチと変更セット）に含まれていないが 2 番目のファイルには含まれているブランチ（つまり、マージ保留中の変更セットがあるブランチ）のみを出力します。
3. 最後に、一時ファイルを削除します。

次はこのシナリオについて確認します。

バージョン 1.0 に（直接または間接的に）統合されたブランチを調べる必要があります。前述のとおり、必要なのはサーバーに対する 1 つのクエリと、データをフィルター処理するための PowerShell のみです。この例では、/main に統合されたすべてのブランチを取得します。

サンプル出力は次のようになります。ブランチ 12299 がリリース 4.3.39.406 に間接的に統合されたことがわかります。

このスクリプトの簡単な説明を次に示します。

1. 前述の手順と同様に、リストを取得して重複を削除します。
2. ターゲットブランチ（空の visited リスト）と深度を表示するためのマーカーを指定して ListAll 関数を呼び出します。この関数の出力は null に送られます（この値をコードで使用しないため）。それ以外の場合は、出力が表示されます。
3. ListAll 関数の内部で、ターゲットの期間に一致するマージの検索を試行します。
4. 一致する場合、その項目を visited リストに追加し、日時とマージ元を指定して ListAll を再帰的に呼び出します。
5. 再帰関数が戻ったら、関数の戻り値に基づいて visited リストを更新します。

次のスクリプトを使用すると、これと同等の処理を Bash で行うことができます。

このスクリプトの簡単な説明を次に示します。

1. マージのリストを取得し、重複エントリを削除して、ファイルに保存します。
2. 次に示す 2 つの補助ファイルを準備します。
   1. old_targets：検索するターゲットブランチをすべて保存します。
   2. targets：ソースを検索するターゲットブランチが格納されます。
3. 次に、ターゲットブランチがリストファイルに同期先として存在するかどうかを確認します。存在する場合は、次回の処理用にマージ元のブランチを格納します（以前に影響がなかった場合）。また、結果を画面に出力します。
4. 深度レベルを増やし、ターゲットリストを切り替えます。新しいターゲットリストが現在のターゲットリストになり、現在のリストが「使用済み」リストに追加されます。
5. 最後に、クリーンアップ操作を実行します。環境は元の状態のまま維持されます。

次の表に、現在 cm find merge コマンドで使用できるさまざまなフィルタリングオプションを示します。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find merge コマンドで使用できるさまざまな出力オプションを示します。

統合されたコードレビュー機能を使用すると、レビューのステータスに関する情報を取得できます。このサンプルではまず、自分のレビュー（文字どおり 'me' に割り当てられたレビュー。'me' は現在のユーザー）を取得します。前に行ったようにユーザーの名前を入力することもできます。

その後、特定のステータス（1 = 承認済み）を持つレビューに結果を絞り込むことができます。

最後に、特定の期間内に行われたレビューを取得します。

それを、この特定の期間とこの特定の条件を指定した結果と比較してみましょう。

これらの 2 つのクエリにより、このスプリント上のすべてのレビューに対する承認済みレビューの割合を調べることができます。

次の表に、現在 cm find review コマンドで使用できるさまざまなフィルタリングオプションを示します。

* 条件 date と targetid はそれぞれ、「コードレビュー」ビューの「作成日」列と「レビュー済みオブジェクト」列に対応しています。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find review コマンドで使用できるさまざまな出力オプションを示します。

昨年中に自分のチームメンバーによって作成されたシェルブを取得するには、次のコマンドを使用できます。

次の表に、現在 cm find shelve コマンドで使用できるさまざまなフィルタリングオプションを示します。

定数を使用して日付でフィルタリングする方法を確認してください。

また、次の表に、現在 cm find shelve コマンドで使用できるさまざまな出力オプションを示します。

この記事では出力をカスタマイズする方法を見てきましたが、出力を XML として設定し、後で分析するためにファイルに保存することもできます。そのためには、次のコマンドを実行します。

これにより、次の XML コンテンツが生成されます。

<?xml version="1.0" encoding="utf-8" ?>
<PLASTICQUERY>
  <REVISION>
    <ID>426098</ID>
    <COMMENT></COMMENT>
    <DATE>07/06/2013 16:00:09</DATE>
    <OWNER>roberto</OWNER>
    <TYPE>dir</TYPE>
    <SIZE>0</SIZE>
    <CHANGESET>16716</CHANGESET>
    <PARENT>426069</PARENT>
    <ITEM>d:\linked_replicated\</ITEM>
    <ITEMID>2</ITEMID>
    <BRANCH>br:/main/Fix-4.1/scm12863</BRANCH>
    <PATH>d:\linked_replicated\</PATH>
    <REPOSITORY>codice</REPOSITORY>
    <REPNAME>codice</REPNAME>
    <REPSERVER>localhost:8087</REPSERVER>
    <HASH>kWJO1fm+7RCiZZcgSjM4/Q==</HASH>
  </REVISION>
  <REVISION>
    <ID>426092</ID>
    <COMMENT></COMMENT>
    <DATE>07/06/2013 16:00:09</DATE>
    <OWNER>roberto</OWNER>
    <TYPE>txt</TYPE>
    <SIZE>78238</SIZE>
    <CHANGESET>16716</CHANGESET>
    <PARENT>426056</PARENT>
    <ITEM>d:\linked_replicated\01nerva\src\client\plastic\ActionMenuManager.cs</ITEM>
    <ITEMID>37736</ITEMID>
    <BRANCH>br:/main/Fix-4.1/scm12863</BRANCH>
    <PATH>d:\linked_replicated\01nerva\src\client\plastic\ActionMenuManager.cs</PATH>
    <REPOSITORY>codice</REPOSITORY>
    <REPNAME>codice</REPNAME>
    <REPSERVER>localhost:8087</REPSERVER>
    <HASH>FXmLNV7B9Et1wTGqULWpgQ==</HASH>
  </REVISION>
</PLASTICQUERY>
  

このコンテンツを後で Excel などのツールにインポートして、そこから美しい方法で統計を表示できます。

リポジトリ内のすべての変更セットに関する情報を取得する必要があるとします。その場合は次のコマンドを実行します。

その後、出力を Excel にロードします。結果は次のようになります。

Excel にはピボットテーブルと呼ばれる非常に便利なユーティリティが含まれており、これを使用してより詳細な統計情報を取得できます。

Excel で提供されているフィルタリング機能と並べ替え機能を使用して変更セットをユーザーでグループ化し、それらの統計情報をグラフに変換することができます。

ブランチでグループ化することも可能です。ブランチでグループ化して、共同作成を行ったユーザーの数と、各ユーザーによって作成された変更セットの数をブランチごとに表示することができます。

find コマンドでは各オブジェクトに対してデフォルトの出力がありますが、これまで見てきたように、カスタムの出力オプションを定義し、--xml 属性を使用して結果を XML 形式で取得したうえで、--file 属性を使用して結果を後で分析するためにファイルに保存することができます。

一般的な構文を以下に示します。

ここで：

• object には、ブランチ、属性、変更セット、ラベル、マージ、レビュー、リビジョン、ユーザーなど、システム内のほぼすべてのオブジェクトを指定できます。
• conditions はオブジェクトによって異なります。コマンド cm showfindobjects を入力すると、条件（および使用可能なすべてのオブジェクト）を取得できます。
• on repositories 引数は、1 つ以上のリポジトリから、現在のワークスペースに一致するかまたは一致しない情報を取得するために使用できます。任意のフォルダー（ワークスペース内、別のワークスペース内、またはワークスペースを含まないフォルダー内）に移動して、次のように入力できます。 cm find revisions "where branch = 'main/scm12800' on repositories 'codice@localhost:8087'" --nototal 423620 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\#br:/main/scm12800#16582 423621 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\01nerva#br:/main/scm12800#16582 423622 27/05/2013 13:25:53 dirRoberto d:\linked_replicated\01nerva\src#br:/main/scm12800#16582

  これは、ユーザーにそのリポジトリをクエリするための権限があれば機能します。

  さまざまなリポジトリだけでなく、さまざまなサーバーからもまとめてクエリできます。次に例を示します。

  cm find "changesets where date >= '2017/11/17' on repositories 'documentation/plasticdocu@localhost:8087','codice@codice@cloud'" --nototal 68621 1451 /main/scm21135 11/20/2017 3:32:31 PM maria documentation/plasticdocu Added documentation about the EOL conversion mechanism. 4821759 132324 /main/SCM21120 11/20/2017 1:41:45 PM pablo codice Added missing config file 4821840 132326 /main/scm21149/scm21150 11/20/2017 1:54:35 PM vsanchezm@codicesoftware.com codice Fix HAL FAILED - Conflicts and user intervention required. Rebase from main. 4821941 132333 /main 11/20/2017 2:38:28 PM hal codice HAL: merged /main/scm21076/scm21084/scm21093 : GTK Gluon: add pending changes view
• options では、前に説明した出力オプション（--format、--xml、または --file）を指定できます。

日付でフィルタリングするときは、お使いのマシンのローカライズ設定に従った日付形式を使用できます。たとえば、お使いのコンピューターで日付が「yyyy-MM-dd」の形式で表示される場合、クエリで「2019-12-31」のような日付を使用できます。

クエリを簡単にするために、次の定数を使用することもできます。

• 'today'：今日の日付。
• yesterday'：昨日の日付。
• this week'：今週の月曜日の日付。
• this month'：今月の 1 日の日付。
• this year'：今年の 1 月 1 日の日付。
• one day ago'：現在の日付の 1 日前。
• one week ago'：現在の日付の 7 日前。
• one month ago'：現在の日付の 1 か月前。
• n days ago'：現在の日付の「n」日前。
• n months ago'：現在の日付の「n」か月前。
• n years ago'：現在の日付の「n」年前。

次の「where」句は、タイプ「date」のフィールドで有効です。

• (...) where date > 'today' (...)
• (...) where date < 'yesterday' (...)
• (...) where date > 'this week' (...)
• (...) where date > 'this month' (...)
• (...) where date < 'one day ago' and date > '3 days ago' (...)
• (...) where date < 'one week ago' and date > '3 weeks ago' (...)
• (...) where date < 'one month ago' and date > '3 months ago' (...)
• (...) where date > '1 year ago' (...)

2019 年 12 月 10 日

• cm find の一部の例を、不足している二重引用符を追加して修正しました。

2018 年 12 月 7 日

• いくつかの新しい例を追加しました。
• シェルブを検索する方法をご確認ください。
• 日付でフィルタリングするときに日付定数を使用できます。

2017 年 11 月 20 日

• on repositories 引数を使用して 1 つ以上のリポジトリからクエリする方法をご確認ください。

2014 年 7 月 1 日

• 公開日。