使用版本控制和部署

本頁假設您已為專案設定版本控管。如果看到「設定 Git」按鈕，而不是本頁面所述的選項，請先為專案設定 Git。

Looker 會使用 Git 記錄變更並管理檔案版本。每個 LookML 專案都對應一個 Git 存放區，而每個開發人員分支都與一個 Git 分支相關聯。

您可以設定 Looker 與許多 Git 供應商搭配使用，例如 GitHub、GitLab 和 Bitbucket。如要瞭解如何為 Looker 專案設定 Git，請參閱「設定及測試 Git 連線」說明文件頁面。

使用 Git 分支

Git 的主要優點之一，就是 Looker 開發人員可以在分支 (檔案存放區的獨立版本) 中工作。您可以在不影響其他使用者的情況下開發及測試。在 Looker 中，開發人員只要處於開發模式，就會使用 Git 分支。

Git 的另一項主要功能是可輕鬆與其他開發人員協作。您可以建立分支並視需要進行變更，然後其他開發人員可以切換至該分支，以審查或變更分支。如果其他開發人員已將變更內容提交至分支版本，Looker 會顯示「Pull Remote Changes」(提取遠端變更) 按鈕。您應該先將這些已提交的變更提取至分支版本，再進行其他變更。

您也可以刪除分支，但不能刪除主要分支、目前分支或開發人員的個人分支。

個人分支版本

為提升效能，首次在開發模式中開啟 LookML 專案時，Looker IDE 會顯示專案的正式模式版本，以及「建立開發人員副本」按鈕。點選專案的「建立開發人員副本」按鈕後，Looker IDE 會建立您的個人 Git 分支，並在開發模式中載入 LookML 專案。

個人分支版本會以 dev- 開頭，並包含您的名稱。

個人分支版本專屬於您，無法刪除。其他開發人員只能讀取您的個人分支版本。如果您與其他開發人員協作處理專案，可以建立新分支，讓其他人切換至該分支並提供變更。

建立新的 Git 分支

如果您要進行簡單的修正，且沒有與其他開發人員協作，通常可以在個人分支中作業。您可以使用個人分支進行快速更新，然後提交變更並推送至正式環境。

不過，除了個人分支以外，您可能也想建立新的 Git 分支。在下列情況中，建立新的 Git 分支是合理的做法：

  • 您與其他開發人員合作。由於其他開發人員只能讀取您的個人分支版本，如要與他人協作，請建立新的 Git 分支版本，讓其他開發人員可以寫入該分支版本。與他人協作時，請務必在每次繼續工作時提取變更。這樣一來，您就能在繼續工作前，取得所有開發人員的最新更新。
  • 您同時處理多組功能。有時您可能正在進行大型專案，但想解決小問題或快速修正。在這種情況下，您可以將變更提交至目前所在的分支，然後建立或切換至其他分支，處理另一組功能。您可以在新分支中修正問題，然後將該分支的變更部署至正式環境，再繼續在原始分支中工作。

建立新分支版本前，請先完成下列步驟：

  • 如果目前分支版本有合併衝突，您必須先解決衝突，才能建立新分支版本。
  • 如果目前分支版本有任何未提交的變更，請先提交變更，再建立新分支版本。
  • 如要從現有的開發分支版本 (而非正式版) 建立分支版本，請先切換至該開發分支版本，然後提取遠端變更，同步處理該分支版本的本機版本，取得最新版本。

如要建立新的 Git 分支，請按照下列步驟操作：

  1. 確認已開啟開發模式。

  2. 在「Develop」選單中前往專案檔案。

  3. 選取左側圖示選單中的「Git」圖示，開啟「Git Actions」面板。

  4. 選取「查看分支機構」下拉式選單。

  5. 選取「New Branch」。

  6. 在「New Branch」(新分支) 視窗中，輸入分支的名稱。請注意，Git 分支名稱有相關限制；如需命名規定，請參閱本頁的「Git 分支命名規則」。

  7. 選取「Create From」(從以下項目建立) 下拉式選單，然後選取要做為新分支起點的現有分支。

  8. 選取「建立」即可建立分支。

您也可以從專案設定的「Branch Management」分頁建立 Git 分支。

Git 分支命名規則

Looker 會使用 Git 指定的分支命名慣例規定。

Git 分支名稱不得包含：

  • 包含空格字元
  • 含有雙句點：..
  • 包含反斜線：\
  • 包含序列：@{
  • 含有問號：?
  • 包含左方括號：[
  • 包含 ASCII 控制字元：~、\^ 或 :
  • 以半形句號開頭：.
  • 從前置字元 dev- 開始 (保留給 Looker 開發人員的個人分支)
  • 以正斜線結尾：/
  • 結束通話並傳送擴充功能：.lock

此外，只有當星號代表整個路徑元件 (例如 foo/* 或 bar/*/baz) 時，分支名稱才能包含星號 (*)，此時星號會解讀為萬用字元，而非實際分支名稱的一部分。

切換至其他 Git 分支

如果目前的分支有合併衝突，你必須先解決衝突，才能切換至其他分支。

此外，如果目前分支版本有未提交的變更，您必須先提交變更，才能切換至現有分支版本。

如要切換至其他 Git 分支，請按照下列步驟操作：

  1. 在專案中，選取左側圖示選單中的「Git」圖示，前往「Git Actions」面板。
  2. 在「Git Actions」面板中，選取目前 Git 分支版本名稱右側的 Git 分支版本下拉式選單。
  3. 在選單中選取要切換的分支版本，或在搜尋框中輸入分支版本名稱，分支版本名稱搜尋不區分大小寫。舉例來說，您可以搜尋「DEV」，查看名稱包含「dev」、「DEV」、「Dev」等的所有分支。

管理 Git 分支

專案設定的「Branch Management」分頁會顯示 Looker 專案的所有 Git 分支表格。如要開啟「Branch Management」分頁，請先選取左側圖示選單中的「Settings」圖示，前往專案設定。接著選取「分店管理」分頁標籤。

在「分店管理」分頁中，你可以：

  1. 選取「New Branch」按鈕，建立新分支。詳情請參閱本頁的「建立新的 Git 分支」一節。
  2. 在搜尋列中搜尋分支名稱。
  3. 選取「重新整理」按鈕，即可重新整理表格。
  4. 選取資料欄名稱，即可排序表格。

表格中包含下列資訊：

  • 名稱：Git 分支名稱。Looker 開發人員的個人分支會以 dev- 開頭，並包含開發人員的名字和姓氏。
  • 狀態：分支的本機版本與遠端版本之間的差異。舉例來說，3 commits behind 狀態表示本機分支版本比遠端分支版本落後三個提交。由於 Looker 一律使用遠端版本的 master，因此「Branch Management」(分支管理) 分頁不會顯示本機版本 master 分支的狀態。主分支一律視為最新版本。
  • 上次更新：Looker 開發人員上次對分支版本進行提交後經過的時間。
  • 動作：刪除分支的按鈕，或分支不符合刪除資格的原因。

刪除 Git 分支

在「分店管理」分頁中，你可以刪除表格中顯示「刪除」按鈕的分店。您無法刪除下列分支：

在表格中，這些分支機構沒有「刪除」按鈕。表格的「動作」欄會顯示無法刪除分支的原因。

分支刪除後即無法復原。刪除分支時，Looker 會一併移除分支的本機和遠端版本。

不過，如果分支是由其他 Looker 開發人員建立，或是其他開發人員已簽出分支，這些開發人員仍會有分支的本機版本。如果 Looker 開發人員將變更提交至分支的本機版本，並推送至正式版，您會再次看到分支的遠端版本。如果您想還原分支版本，這項功能就非常實用。否則，當您刪除分支時，所有其他 Looker 開發人員都應刪除相同分支，確保有人將其推送至遠端時，不會意外重新顯示。

如要從專案中刪除一或多個 Git 分支，請先從左側圖示選單中選取「設定」圖示，前往專案設定。然後選取「分店管理」分頁標籤。在「分店管理」分頁中，你可以透過兩種方式刪除分店：

  1. 如要刪除多個分支版本，請先選取分支版本的核取方塊，然後選取「刪除所選分支版本」。
  2. 如要刪除單一分支版本，請選取分支版本名稱旁的「刪除」。

在 Looker 中執行 Git 指令

Looker 內建的介面可與 Git 服務整合。Looker 會在 LookML IDE 的右上角顯示 Git 按鈕。

視您在變更及部署至正式版程序的階段而定，「Git」按鈕會顯示不同選項。一般來說，按鈕上顯示的選項是您下一步行動的最佳指引。

如果開發人員分支與正式版分支同步，Git 按鈕會顯示「最新版本」訊息，且無法選取。

為專案設定 Git 後，即可選取「Git Actions」按鈕，開啟「Git Actions」面板。

Git Actions 面板上可用的指令，取決於您在變更和部署至正式環境的過程中處於哪個階段。

將變更推行至實際工作環境

使用預設的 Looker Git 整合功能時，Looker 會透過下列 Git 工作流程提示開發人員：

也就是說，使用預設的 Git 整合功能時，所有開發人員都會將變更合併至名為 master 的分支版本，而 master 分支版本上的最新提交內容，就是 Looker 生產環境所用的內容。

如要進階實作 Git，可以自訂這個工作流程：

  • 您可以要求開發人員為 Git 生產分支版本提交提取要求，而不是允許開發人員透過 Looker IDE 合併變更。詳情請參閱「設定專案版本控管設定」說明文件頁面。
  • 您可以使用「Git Production Branch Name」(Git 生產分支名稱) 欄位，指定 Looker 應將 Looker 開發人員的分支合併至哪個 Git 存放區分支。詳情請參閱「設定專案版本控管設定」說明文件頁面。
  • 您可以透過進階部署模式指定其他要部署至 Looker 生產環境的提交 SHA 或標記名稱，而非使用生產分支的最新提交。(如要從其他分支部署提交內容，可以使用進階部署模式 webhook 或 API 端點)。詳情請參閱「進階部署模式」說明文件頁面。

如果看到「設定 Git」按鈕，而不是本節所述的選項，請先為專案設定 Git。

查看未提交的變更

如 Looker IDE 總覽說明文件頁面的「標記新增、變更和刪除項目」一節所述，當您處於開發模式且有未提交的變更時，LookML IDE 會顯示多個指標。

如要取得所有檔案的差異摘要，請從「Git Actions」面板選取「View Uncommitted Changes」選項。

在「Uncommitted Changes to Project」視窗中，Looker 會顯示專案所有檔案中，所有未提交的已儲存變更摘要。Looker 會針對每項變更顯示下列資訊：

  • 取代檔案的名稱和新增檔案的名稱。
    • 取代檔案的名稱 (以 --- 表示) 和新增檔案的名稱 (以 +++ 表示)。在許多情況下，這可能會顯示相同檔案的不同版本，修訂版本則以 --- a/ 和 +++ b/ 表示。
    • 系統會將已刪除的檔案視為取代空值檔案 (+++ /dev/null)。
    • 新增的檔案會顯示為取代空值檔案 (--- /dev/null)。
  • 變更開始的行號。

    舉例來說，-101,4 +101,4 表示檔案的第 101 行移除了 4 行，並新增了 4 行。如果刪除 20 行的檔案，系統會顯示 -1,20 +0,0，表示檔案的第一行有 20 行遭到移除，並以零行取代。
  • 更新的文字：
    • 已刪除的行會以紅色顯示。
    • 新增的行會以綠色顯示。

如要顯示單一檔案的差異摘要，請從檔案選單中選取「查看變更」選項。

提交變更

對 LookML 專案進行變更並儲存後，IDE 可能會要求您驗證 LookML。在這種情況下，Git 按鈕會顯示「驗證 LookML」文字。

這項設定是否為必要欄位，取決於專案的程式碼品質設定。如要進一步瞭解內容驗證工具，請參閱「驗證 LookML」說明文件頁面。

如果自上次更新本機分支以來，有其他開發人員變更了正式版分支，Looker 會要求您從正式版分支提取這些更新。在此情境中，Git 按鈕會顯示「從正式環境提取」文字。

如果專案已啟用進階部署模式，Git 按鈕會顯示「從主要分支版本提取」文字。

儲存變更 (並修正所有 LookML 警告或錯誤，視需要) 並從正式環境提取 (視需要) 後，「Git」按鈕會顯示「提交變更並推送」文字。

如要先查看未提交的變更，再提交變更，請按照下列步驟操作。

準備好要提交變更時，請使用 Git 按鈕將這些變更提交至目前的分支。Looker 會顯示「Commit」對話方塊，列出已新增、變更或刪除的檔案。

輸入簡要說明變更的訊息，然後取消勾選不想納入同步處理的檔案旁邊的核取方塊。然後選取「Commit」，即可提交變更。

檢查未建構的 PDT

如果您已變更專案中的任何 PDT，建議您在部署至正式環境時建立所有 PDT，以便立即將這些資料表做為正式環境版本使用。如要查看專案中 PDT 的狀態，請選取「專案健康狀態」圖示開啟「專案健康狀態」面板，然後選取「驗證 PDT 狀態」按鈕。

如要進一步瞭解如何在 LookML 專案中檢查未建構的 PDT，以及如何在開發模式中使用衍生資料表，請參閱「Looker 中的衍生資料表」說明文件頁面。

執行資料測試

專案可能包含一或多個 test 參數，用於定義資料測試，以驗證 LookML 模型的邏輯。如要瞭解如何在專案中設定資料測試，請參閱 test 參數說明文件頁面。

如果專案包含資料測試，且您處於開發模式，可以透過下列幾種方式啟動專案的資料測試：

  1. 如果專案設定為「必須先通過資料測試，才能將檔案部署至正式環境」，當您提交專案變更時，IDE 會顯示「執行測試」按鈕，讓您執行專案的所有測試，無論測試是由哪個檔案定義。您必須先通過資料測試，才能將變更部署至正式環境。
  2. 在「專案健康狀態」面板中，選取「執行資料測試」按鈕。無論哪個檔案定義測試，Looker 都會執行專案中的所有資料測試。
  3. 從檔案選單中選取「Run LookML Tests」選項。Looker 只會執行目前檔案中定義的測試。

執行資料測試後，「專案健康狀態」面板會顯示進度和結果。

  • 如果測試查詢中的每個資料列都符合測試的判斷條件，資料測試就會通過。如要進一步瞭解如何設定測試斷言和查詢，請參閱 test 參數說明文件頁面。
  • 如果資料測試失敗，「專案健康狀態」面板會提供測試失敗原因的相關資訊，包括測試是否在模型邏輯中發現錯誤，或是測試本身無效。
  • 在資料測試結果中，您可以選取資料測試的名稱，直接前往資料測試的 LookML，也可以選取「探索查詢」按鈕，開啟探索並使用資料測試中定義的查詢。

部署至正式環境

將變更提交至分支版本後，Looker IDE 會提示您將變更合併至主要分支版本。IDE 中顯示的提示類型取決於專案設定：

  • 如果專案已設定為進階部署模式，IDE 會提示您將變更合併至主要分支。合併提交後，具有 deploy 權限的 Looker 開發人員可以使用 Looker IDE 部署管理工具，或使用 Webhook 或 API 端點，將提交內容部署至正式環境。
  • 如果專案已設定使用提取要求進行 Git 整合，系統會提示您使用 Git 供應商的介面開啟提取要求。
  • 否則，使用預設的 Looker Git 整合時，如果您有 deploy 權限，Looker IDE 會提示您將變更合併至正式版分支，並將變更部署至 Looker 執行個體的正式版。

進階部署模式

使用預設的 Looker Git 整合功能時，Looker 開發人員會將變更提交至開發分支版本，然後將開發分支版本合併至正式分支版本。然後，當您部署至 Looker 環境時，Looker 會使用正式版分支的最新提交內容。(如需預設 Git 工作流程，以及進階 Git 實作的其他選項，請參閱本頁的「將變更內容發布至正式環境」一節)。

如果您不希望 Looker 環境一律使用正式版分支的最新提交內容，具備 deploy 權限的開發人員可以使用進階部署模式，為 Looker 環境指定要使用的確切提交內容。這在多環境開發人員工作流程中非常實用，因為每個環境都會指向不同版本的程式碼基底。此外，一或多位開發人員或管理員也能更有效控管部署至正式版的變更。

啟用進階部署模式後，Looker IDE 不會提示開發人員將變更部署至正式環境。IDE 會提示開發人員將變更合併至正式環境分支版本。完成後，您只能透過下列方式部署變更：

  • 在 Looker IDE 中使用部署管理員
  • 觸發 Webhook

  • 使用 API 端點

詳情請參閱「進階部署模式」說明文件頁面。

查看變更的影響

向機構提供變更內容後，您可以使用內容驗證，確保沒有任何資訊主頁或已儲存的 Look 失效。如有違規情形，您將有機會修正。

處理常見問題

處理模型時，您可能需要：

  • 捨棄變更

    有時您可能想放棄資料模型變更。如果尚未儲存，只要重新整理或離開頁面，然後接受警告提示即可。如果已儲存變更，可以按照「還原未提交的變更」一節所述，還原未提交的變更。

  • 處理與其他開發人員工作內容的合併衝突

    如果有多位開發人員處理資料模型，通常會由 Git 處理這種情況。不過，有時 Git 需要人工解決合併衝突。

部分變更 (例如變更欄位名稱) 可能會影響現有資訊主頁和 Look。如先前所述，向機構提供變更後，您可以使用內容驗證檢查內容並修正問題。

還原未提交的變更

在個人開發分支中作業時，如果不想部署已儲存但未提交的變更，可以還原這些變更。您可以還原專案中所有檔案的未提交變更，也可以只還原單一檔案的變更。

如要還原所有檔案的未提交變更，請按照下列步驟操作：

  1. 在「Git Actions」面板中選取「Revert to...」選項。
  2. 選取還原選項：
    • 如要只還原未提交的變更，請選取「還原未提交的變更」。您也可以選取「查看變更」連結，查看將還原的變更。
    • 如要還原所有變更 (包括未提交和已提交的變更)，請選取「還原至正式版」
  3. 選取「確認」即可完成還原程序。

如要還原單一檔案內容中的任何新增或刪除項目，請從該檔案的選單中選取「還原變更」選項：

重新命名檔案時，系統會刪除原始檔案，並建立新檔案，由於這項作業涉及多個檔案，因此無法使用「還原檔案」選項，復原檔案重新命名作業。如要還原檔案重新命名作業，請使用「Git Actions」面板中的「Revert to...」選項。

此外，如果您刪除檔案，IDE 檔案瀏覽器就不會再顯示該檔案。如要還原已刪除的檔案，請使用「Git Actions」(Git 動作) 面板中的「Revert to...」(還原至...) 選項。

解決合併衝突

一般來說，Git 會自動將新變更與 LookML 檔案的正式版合併。當 Git 遇到衝突的變更，且無法判斷應保留哪些變更時，就會發生合併衝突。通常是當您上次提取後，其他開發人員已進行變更，而您在同一區域也進行了變更時，就會發生這種情況。如果程式碼發生合併衝突，Looker 會在您提交變更並從正式版提取後，顯示「合併衝突」警告。

如果 Looker 顯示合併衝突警告，建議您先解決合併衝突，再進行任何變更。如果將合併衝突推送到正式環境，就會導致剖析錯誤，可能無法探索資料。如果您是進階 Git 使用者，且想繼續推送變更，請選取「Don't Resolve」按鈕。

在 LookML 檔案中，有衝突的行會標示如下：

<<<<<<< HEAD
Your code
&#61;&#61;&#61;&#61;&#61;&#61;&#61;
Production code
>>>>>>> branch 'master'

Looker 會顯示下列合併標記，指出合併衝突：

  • <<<<<<< HEAD 標示衝突行的開頭。
  • >>>>>>> branch 'master' 標示衝突行的結尾。
  • ======= 會分隔每個版本的程式碼，方便您比較。

在上述範例中，your code 代表您已提交的變更，production code 則代表 Git 無法自動合併變更的程式碼。

如要解決合併衝突，請按照下列步驟操作：

  1. 找出有合併衝突的檔案。Looker 會以紅色標示這些檔案，您也可以搜尋專案中的合併標記 (例如 <<<< 或 HEAD)，找出專案中的所有衝突。您也可以在「Git Actions」面板中，選取合併警告訊息中的「files」連結，找出受影響的檔案。
  2. 在檔案中，前往有合併衝突的行，刪除你不想保留的文字版本，並刪除所有合併衝突標記。

  3. 儲存檔案，並針對標示為合併衝突的任何其他檔案，重複上述步驟。

  4. 解決所有合併衝突並刪除專案中的所有合併標記後，請提交變更並部署至正式環境。

現在您已解決合併衝突，並將解決方案推送至正式環境，其他開發人員可以從正式環境提取解決方案，並照常繼續工作。

Git 垃圾收集

Git 垃圾收集會清除不必要的檔案，並壓縮檔案修訂版本，以最佳化 Git 存放區。更新或重新啟動 Looker 執行個體時，系統會自動執行 Git 垃圾收集 (git gc)。為避免過於頻繁地執行 git gc，Looker 會等待 30 天 (自上次執行 git gc 算起)，然後在下次重新啟動時執行 git gc。

在極少數情況下，您可能會在 git gc 執行時嘗試「將變更推送至遠端」或「將分支推送至遠端」。如果 Looker 顯示錯誤，請稍候一兩分鐘，然後再試一次推送變更。