Cm find 範例

在所有版本控制系統中，我們經常需要取得使用情況、哪些檔案正在變更，以及搜尋特定變更或特定分支的相關資訊。

達成此目的的最佳方式就是使用查詢。因此，當我們建立 Plastic SCM 時，會新增非常強大的查詢系統 (名為 cm find)，它是可讓您取得包含變更集、分支、標籤、合併和程式碼檢閱之特定資訊的命令。

find 命令也能用來自訂 GUI 中的檢視。

本文涵蓋一些可使用 cm find 命令處理的範例案例。它們是一個有關您可在 Plastic SCM 安裝中進行之作業小的子集。每個範例都包含問題、逐步解決方案及預期輸出，協助您瞭解系統會回傳哪種資訊。

我們可以擷取使用者在某個時間範圍內建立的分支，然後可以依特定屬性進行篩選。

我們開始擷取所有可用的分支：

我們只要我們的分支，因此依使用者篩選：

依使用者進行篩選後，我們現在只想要與此衝刺相關的分支，因此我們要尋找在特定日期之後建立的分支：

您可以使用已設定格式的輸出：

最後，我們會尋找某個特定屬性。根據我們內部的功能生命週期，每個分支都必須先通過測試，才能在 main 分支上進行整合。

當分支通過測試時，「test」屬性將設為「passed」，因此我們會依屬性名稱和屬性值進行篩選：

下表顯示目前可與 cm find branch 命令搭配使用的不同篩選選項：

* 條件 date 對應至 [分支] 檢視中的 [建立日期] 欄。

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find branch 命令搭配使用的不同輸出選項：

我們可以找出變更集的許多資訊，而註解只是其中一項。如需快速資訊，我們可以使用 cm log 並執行自己的篩選 (使用 Shell 命令)，或讓 cm find 為您完成此工作。

在此範例中，我們要取得屬於某個分支之所有變更集的日期和註解：

這裡有所有的變更集，現在我們要尋找「解決方案」這個詞，我們可以在這裡輕鬆看到這個詞，但當有幾百個變更集時，就會變成緩慢且枯燥乏味的作業。為了依特定字詞進行篩選，我們使用 SQL 語法 LIKE 和 % 來進行概略搜尋，因為我們並不是要尋找完整註解：

我們也可以使用下列命令，依複寫日期查詢變更集 (我們稍後將瞭解如何取得最後複寫日期):

returnparent 可讓我們取得特定變更集或修訂的上層。如此一來，如果想要知道此變更集之前發生的情況，只需直接詢問：

下表顯示目前可與 cm find changeset 命令搭配使用的不同篩選選項：

* 條件 changesetid、date 和 owner 分別對應至 [變更集] 檢視中的 [名稱]、[建立日期] 和 [建立者] 欄。

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find changeset 命令搭配使用的不同輸出選項：

只要有了分支，我們就可以取得自開始計算時間以來的所有複寫作業 (依時間先後順序排列)。

如果我們只需要最後的日期，我們可以依日期篩選搜尋，並使用 PowerShell 或 Bash 選取最後一列。

PowerShell：

Bash：

結果：

下表顯示目前可與 cm find replicationlog 命令搭配使用的不同篩選選項：

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find replicationlog 命令搭配使用的不同輸出選項：

我們可以取得所有標籤：

我們可以取得在特定分支中建立的所有標籤：

在 codice，我們會為開發保留一個主要分支以及一個支援目前版本和舊版的「修正」分支，因此我們可能會想要尋找哪個分支包含某個特定發行版本：

如畫面上所示，標籤 BL237 是來自 main 分支。

我們可以取得標籤日期，之後再要求在該分支的該時間範圍內所建立的變更集。取得兩個 (或更多) 標籤資訊的方法非常簡單：

下表顯示目前可與 cm find label 命令搭配使用的不同篩選選項：

* 條件 date 對應至 [標籤] 檢視中的 [建立日期] 欄。

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find label 命令搭配使用的不同輸出選項：

屬性可以套用至分支、變更集和標籤，沒有任何區別。首先，我們需要物件 ID。我們可以在查詢分支時讓它指定 ID：

擁有該 ID 後，我們就可以使用下列命令取得屬性清單：

在此案例中，屬性名稱為 "status"，而屬性值為 "Passed"。

我們可以使用一些 PowerShell 指令碼合併這兩個命令：

或使用 Bash 指令碼：

輸出會和之前一樣：

您將會透過執行下列查詢來取得相同輸出：

假設我們為某些物件設定特定屬性 (在我們的案例中便是測試「狀態」)。無論將其包含在內的是什麼物件，我們都可以查詢這些屬性。

下表顯示目前可與 cm find attributes 命令搭配使用的不同篩選選項：

* 條件 date 和 type 分別對應至 [屬性] 檢視中的 [建立日期] 和 [名稱] 欄。

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find attributes 命令搭配使用的不同輸出選項：

在先前的範例中擷取特定變更集後，我們現在可能會想要深入瞭解有哪些檔案有包含變更，為此可使用 find revision。

我們可指定自訂格式，因為我們只需要檔案和資料夾路徑：

透過一些命令列說明 (Linux 上的 grep 以及 Windows Powershell 上的 where)，我們也可以依資料夾進行篩選：

PowerShell：

Bash：

然後，輸出內容如下所示：

我們也可以在其所有變更集中進行搜尋，以取得分支的修訂資訊。首先，我們可以從分支和時間範圍取得所有已變更的項目：

之後，我們可以使用最愛的 Shell 工具 (在我們的案例為 PowerShell) 篩選該資訊。

如果您偏好使用 Bash，請使用下列命令列：

預期的輸出如下所示：

下表顯示目前可與 cm find revisions 命令搭配使用的不同篩選選項：

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find revisions 命令搭配使用的不同輸出選項：

可以合併資訊嗎？您可以追蹤來自特定來源/目的地分支或變更集的已完成合併。

若要知道分支已在哪個位置整合，您可以輸入下列命令：

若要瞭解已在特定分支中整合哪些分支，請使用下列命令：

先前命令也能使用格式標誌來自訂輸出 (方法是只傳回分支名稱)，如此一來，第二個命令就會變成：

或者：

切記，find merge 會傳回所有類型的合併：一般合併、精挑細選合併與減性合併。

因此，您可以間隔合併至指定的分支：

我們可以透過兩個查詢 (find branches、find merge) 和一些 PowerShell 駭客攻擊來取得此問題的解答。將此程式碼放置在 PS1 檔案上，並從 PowerShell 主控台執行：

以下是範例輸出：

此程式碼會執行下列動作：

1. 尋找來自此衝刺的所有分支。
2. 尋找來自此衝刺的所有分支，並且只傳回來源分支。
3. 變更 $allbranches 輸出的格式，讓兩份清單都具有相同的格式。
4. 檢查「合併」清單是否包含來自 allBranches 清單的分支。如果沒有，表示分支未整合。

Bash Shell 中的等同程式碼如下所示：

此程式碼會在它那一端執行下列動作：

1. 尋找屬於此衝刺的每個分支。
2. 尋找屬於此衝刺的每個合併，只傳回其來源分支。
3. 列印來自此衝刺的所有分支，這些分支之前不在已合併的分支清單上。

我們正在尋找此案例：

我們想要那些已整合至另一個分支的分支 (因此我們必須捨棄與同一分支的合併)，但有待整合的變更集 (圖片上的橘色 cset)，可以透過單一查詢來操作，然後透過一些 PowerShell 程式碼進行一些後製處理：

以下是範例輸出：

此程式碼會執行下列動作：

1. 取得所有合併，以及在特定日期後完成的來源變更集。
2. 篩選這些具有相同來源和目的地的合併。
3. 取得只包含合併的清單，以捨棄已合併的項目。
4. 變更 find branches 輸出的格式，使其符合 find merge 格式。
5. 比較並篩選已在該間隔合併的分支，但有要合併的暫止變更集。

如果您在使用 Bash，以下是替代方案：

我們正在做的是：

1. 寫入檔案上的所有合併，指出已在特定日期後執行的來源變更集；與此同時，在不同檔案上寫入所有來源合併分支。
2. 依分支名稱和變更集在所有現有分支上進行反覆運算，只列印那些未顯示在第一個檔案 (合併來源分支和變更集)，但確實會顯示在第二個檔案上 (表示有要合併的暫止變更) 的部分。
3. 最後，刪除暫時檔案。

我們正在尋找此案例：

我們要知道哪些分支已整合至 1.0 版 (直接或間接)。和之前一樣，我們只需要對伺服器執行單一查詢，以及執行一些其他 PowerShell 命令來篩選資料。在此特定範例中，我們要取得已在 /main 中整合的所有分支。

以下為範例輸出，我們可以看到分支 12299 已在版本 4.3.39.406 中間接整合

指令碼簡述如下：

1. 我們取得清單，並像之前一樣移除重複項目。
2. 我們使用目標分支呼叫 ListAll 函數，這是空白的已造訪清單，以及可協助我們顯示深入資訊的標記。此函數的輸出會透過管線傳送至 null，因為我們不會在程式碼中使用此值，否則它就會顯示。
3. 在 ListAll 函數內，我們嘗試尋找其目標符合目標視窗的合併。
4. 如果符合，我們會將項目加入至 visited 清單，然後遞迴呼叫 ListAll，包含我們合併來源的時間。
5. 遞迴函數傳回後，我們會根據此函數的傳回值更新已造訪的清單。

您可使用下列指令碼，完成 Bash 底下的同等項目：

此指令碼簡述如下：

1. 我們取得合併清單，移除重複項目，並將其儲存至檔案中。
2. 我們準備兩個輔助檔案：
   1. old_targets，這會儲存我們找到的每個目標分支
   2. targets，這會包含我們正在尋找之來源的目標分支
3. 我們現在要繼續尋找目標分支是否以目的地形式存在於清單檔案上。若是如此，如果其之前未曾受到影響，我們將儲存下一輪的合併來源分支。此外，我們會將它列印在螢幕上。
4. 我們會增加深度並切換目標清單：新的目標清單變成目前的目標清單，而目前清單已新增至「已使用」清單。
5. 最後，只會剩下一個清理作業，讓環境保留原狀。

下表顯示目前可與 cm find merge 命令搭配使用的不同篩選選項：

瞭解如何使用常數依日期篩選。

此另一表格顯示目前可與 cm find merge 命令搭配使用的不同輸出選項：

整合式程式碼檢閱功能可讓我們取得有關檢閱狀態的資訊。在此範例中，我們開始取得我的檢閱 (亦即指派給「我」的檢閱，其中 'me' 是目前使用者)。我們也可以像之前一樣輸入使用者名稱。

之後，我們可以將結果的範圍設定為具有特定狀態 (1 = 已核准) 的檢閱：

最後，我們會取得在特定時間範圍內完成的檢閱：

因此，我們要將它與具有此特定範圍和此特定條件的檢閱進行比較：

透過這兩個查詢，我們可以取得此衝刺上已核准/所有檢閱的比率。

下表顯示目前可與 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 引數可用來從可能符合或不符合目前工作區的一或多個儲存庫取得資訊。我們可以移至任何資料夾 (在我們的工作區內、其他工作區中或不含工作區的資料夾中) 並輸入： 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)。

依日期篩選時，您可以使用遵循您機器當地語系化設定的日期格式。例如，若您的電腦顯示「MM-dd-yyyy」格式的日期，則您可以在查詢中使用如「12-31-2019」之類的日期。

您也可以使用下列常數簡化查詢：

• 'today'：今天的日期。
• yesterday'：昨天的日期。
• this week'：本週星期一的日期。
• this month'：本月第 1 天的日期。
• this year'：今年 1 月 1 日的日期。
• one day ago'：目前日期的前一天。
• one week ago'：目前日期的前七天。
• one month ago'：目前日期的前一個月。
• 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 引數從一或多個儲存庫進行查詢。

2014 年 7 月 1 日

• 發佈日期。