コマンド一覧と共通の引数

操作からコマンドを探す

cdg dag のコマンドはワークフローを、cdg task のコマンドはワークフロー内のタスクを操作の対象にします。そのほかのルートコマンドは、プロジェクトの初期化、キューの確認、ブランチ名の解放、プラグインとアカウントの管理に使います。

一時停止、強制停止、復旧をそれぞれどんな場面で使うかは介入と制御、レビューアクションの選び方は判断に応じてアクションを選ぶを参照してください。

cdg と codedag は、同じコマンドラインツールの 2 つの名前です。ドキュメントでは、すべて cdg と書きます。どのコマンドでも、後ろに --help を付けると、そのコマンドの引数とオプションをすべて確認できます。たとえば cdg task pause --help です。

cdg help <コマンド...> も使えます。コマンド名を上の階層から順に書けば、どの階層のサブコマンドのヘルプも表示できます。たとえば cdg help dag review clear です。dag、task、dag review、task review、plugin、branch、auth の各コマンドグループにも、それぞれ help があります。そのため、cdg dag help review clear でも同じヘルプが出力されます。cdg help dag foo のように、書いた名前がその階層に存在しない場合、コマンドは、そこまでにたどり着いた階層のヘルプを stderr に出力し、終了コードは 1 になります。

ワークフローを指定する

コマンドでは、ワークフローを名前でもパスでも指定できます。ただし、どの書き方でも、最終的には、プライマリリポジトリの .codedag/dags/ ディレクトリ（サブディレクトリを含む）にある .yaml、.yml、.json のいずれかのファイルを指していなければなりません。それ以外の場所にあるファイルや、それ以外の拡張子のファイルを指している場合、コマンドは実行を拒否します。普段は、名前をそのまま書くのが最も手軽です。たとえば .codedag/dags/feature.yaml は feature と書きます。

名前と、.codedag/dags/ で始まるパスは、常にプライマリリポジトリを基準に解決されます。そのため、プライマリリポジトリ、登録済みのいずれかのレプリカのワークスペース、それらの任意のサブディレクトリのどこで実行しても、結果は同じです。それ以外の / を含む相対的な書き方は、./ や ../ で始まるものも含めて、すべて現在のディレクトリを基準に解決されます。したがって、プライマリリポジトリのルートで team/feature と書くと拒否されます。サブディレクトリにあるワークフローは、.codedag/dags/team/feature と書く必要があります。レプリカのワークスペースでは、./.codedag/dags/feature.yaml のような相対パスはレプリカ自身のディレクトリを指すため、これも拒否されます。この場合は、名前で書くか、.codedag/dags/ で始まる書き方に変えてください。

どの書き方でも、コマンドそのものはプロジェクトの中、つまりプライマリリポジトリか登録済みのいずれかのワークスペースの中で実行する必要があります。プロジェクトの外では、正しい絶対パスを書いても、コマンドはそのワークフローが属するプロジェクトを見つけられません。

feature.yaml と feature.yml のように、同じディレクトリにあって拡張子だけが異なる 2 つのファイルは、同じログファイルと同じブランチ名を共有します。そのため、2 つの異なるワークフローを置くのには向きません。ファイルの置き場所と形式を参照してください。

位置引数と -w

cdg dag のコマンドでは、ワークフローを位置引数として書きます。cdg task のコマンドでは、位置引数はタスク ID に使うため、ワークフローは -w で指定します。-w、--workflow-file、--dag は同じオプションの 3 つの書き方で、値のルールは上の表と同じです。

cdg dag status feature
cdg task status 2 -w feature

どちらの方法も受け付けるコマンドが 3 つあります。cdg dag status と cdg dag logs では、位置引数でも -w でもワークフローを指定できます。cdg task ls は位置引数そのものがワークフローで、同じように -w も受け付けます。これらのコマンドが一度に操作するワークフローは 1 つだけで、位置引数、-w、--dag のうち指定できるのは 1 つだけです。2 つ以上を同時に指定すると、コマンドはエラーになり、ステータスもログも出力しません。それらが同じワークフローを指していても同じです。

cdg dag の検証、投入、制御、レビューのコマンドには、スペースで区切って複数のワークフローを一度に指定できます。たとえば cdg dag validate feature docs です。一方、1 つの cdg task コマンドが操作するのは、1 つのワークフローのタスクだけです。

ワークフローを省略すると、ほとんどのコマンドはキューの先頭のワークフロー、つまりキューのいちばん前に並んでいるワークフローを対象にします。どの時点でも、実行されているのはこのワークフローだけです。一方、cdg dag validate、cdg dag submit、cdg dag review clear では、ワークフローを必ず明記しなければなりません。各コマンドでワークフローを省略できるかどうか、省略したときにどのワークフローが対象になるかは、各コマンドのページで確認してください。キューに複数のワークフローがある場合、キューの先頭は、最後に投入したワークフローとは限りません。そのため、スクリプトの中や、エージェントにコマンドを実行させる場合は、ワークフローを明記するほうが確実です。

1 つまたは複数のタスクを指定する

タスクコマンドでは、ワークフローファイルの tasks[].id の値でタスクを指定します（id を参照）。この値は正の整数で、タスクのタイトルとも、リスト内でのタスクの位置とも関係ありません。同じ ID でも、ワークフローが違えば別のタスクを指します。そのため、コマンドでは -w でワークフローも指定する必要があり、省略した場合はキューの先頭のワークフローになります。

複数の ID は、スペースで区切って書きます。たとえば cdg task status 2 3 -w feature です。有効なのは、数字だけからなり、値が 1 以上の書き方だけです。2,3、1.5、+2、2abc、0 のような書き方では、コマンドは Invalid task ID というエラーを出し、何もせずに終了コード 1 で終了します。1 つのコマンドに複数の ID がある場合、そのうち 1 つでも誤っていると、コマンド全体がエラーになり、正しく書いた ID も処理されません。

指定できるタスクの数は、タスクコマンドによって異なります。cdg task ls を除いて、どのコマンドにもデフォルトのタスクはありません。タスクを省略すると、コマンドはエラーになり、すべてのタスクが対象になることはありません。

タスクセレクター

タスクセレクターを使うと、依存関係をもとにタスクのまとまりを一度に選べるため、ID を 1 つずつ並べる必要がありません。以下では、5 つのタスクからなるワークフロー feature を例に、各セレクターがどのタスクを選ぶかを説明します。タスク 2 とタスク 3 はどちらもタスク 1 に依存し、タスク 4 はタスク 2 とタスク 3 に、タスク 5 はタスク 4 に依存します。

flowchart LR  t1["1 インターフェース<br/>契約を書く"] --> t2["2 インターフェースを<br/>実装"]  t1 --> t3["3 テストを書く"]  t2 --> t4["4 テストを<br/>実行して修正"]  t3 --> t4  t4 --> t5["5 ドキュメントを<br/>更新"]

上流と下流は dependencies を 1 段ずつたどって決まり、間接的な依存関係も含まれます。タスク 5 はタスク 4 を介してタスク 2 に間接的に依存しているため、--below 2 にはタスク 5 が含まれます。指定したタスクと並列の位置にあり、互いに依存関係のないタスクは、上流にも下流にも含まれません。そのため、--through 2 にタスク 3 は含まれません。

コマンドの後ろに書いたタスク ID は、--only の省略形です。したがって、cdg task pause 2 3 と cdg task pause --only 2 3 は同じです。直接書いた ID は、どのセレクターとも同時には使えません。--only そのものも例外ではありません。

1 つのセレクターに指定できる ID の数は、コマンドによって異なります。タスクの一時停止、一時停止の解除、強制停止、復旧のコマンドでは、どのセレクターにも複数の ID を指定でき、結果はその和集合になります。たとえば --upto 2 3 は 1、2、3 を選びます。タスクのレビューコマンド（cdg task review clear を含む）では、--only 以外のセレクターが受け付ける ID は、それぞれ 1 つだけです。

ワークフローの途中にあるひと続きのタスクを選びたいときは、2 つのセレクターを組み合わせて、その積集合を取れます。一方は --downfrom または --below から、もう一方は --upto または --above から選びます。それ以外の組み合わせ、たとえば --only と --upto の併用や、3 つのセレクターの同時使用では、コマンドはエラーになり、実行されません。

# タスク 2 から下流へ、タスク 4 まで：2、4 を選ぶ
cdg task pause --downfrom 2 --upto 4 -w feature
# タスク 1 とタスク 5 の間にあるタスク：2、3、4 を選ぶ
cdg task pause --below 1 --above 5 -w feature

セレクターは依存関係だけをもとにタスクを選び、タスクが現在どの状態にあるかは見ません。選ばれたタスクにそのアクションを実行できるかどうかは、各コマンドがそれぞれの前提条件に従って、タスクごとに判断します。たとえば cdg task pause は、レビューが終了したタスクをスキップします。各コマンドの具体的な前提条件は、制御コマンドの構文と適用できる状態とレビューを参照してください。

よく使う一括操作

以下のコマンドでは、引き続きワークフロー feature を使います。タスク 2 とタスク 3 はタスク 1 に、タスク 4 はタスク 2 とタスク 3 に、タスク 5 はタスク 4 に依存します。最後の例では、ワークフロー docs も使います。

一括制御のそのほかの書き方は範囲の指定と一括制御、一括レビューでの各アクションのオプションとデフォルト値はレビューを参照してください。