From aa61e7f1af5afdd66865e5c624fc5dce71b89ae3 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 26 Jul 2026 20:20:49 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLI=20=E3=83=AA=E3=83=95=E3=82=A1?= =?UTF-8?q?=E3=83=AC=E3=83=B3=E3=82=B9=E3=82=92=E3=82=B3=E3=83=9E=E3=83=B3?= =?UTF-8?q?=E3=83=89=E3=82=B0=E3=83=AB=E3=83=BC=E3=83=97=E5=88=A5=E3=81=AB?= =?UTF-8?q?=E5=88=86=E5=89=B2=E3=81=97=20repo=20=E9=80=A3=E6=90=BA?= =?UTF-8?q?=E3=82=AC=E3=82=A4=E3=83=89=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/user/cli-reference.md (740行) を docs/user/cli-reference/ 配下の 目次 + グループ別ファイル (toplevel/project/env/plugin/snapshot) に分割 - docs/plugin-dev/repo-backed-projects.md を新規追加 (外部リポジトリを共有 work ボリュームへ populate する pre-up パターンの解説) - 分割に伴い README 索引・各ドキュメントの参照リンクを新パスへ更新 Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 9 + docs/README.md | 16 +- docs/plugin-dev/quickstart.md | 2 + docs/plugin-dev/repo-backed-projects.md | 171 +++++++ docs/user/cli-reference/01-toplevel.md | 41 ++ .../02-project.md} | 473 +----------------- docs/user/cli-reference/03-env.md | 126 +++++ docs/user/cli-reference/04-plugin.md | 132 +++++ docs/user/cli-reference/05-snapshot.md | 77 +++ docs/user/cli-reference/README.md | 84 ++++ docs/user/container-operations.md | 6 +- docs/user/env-export-import.md | 2 +- docs/user/getting-started.md | 2 +- docs/user/plugin-registries.md | 2 +- 14 files changed, 673 insertions(+), 470 deletions(-) create mode 100644 docs/plugin-dev/repo-backed-projects.md create mode 100644 docs/user/cli-reference/01-toplevel.md rename docs/user/{cli-reference.md => cli-reference/02-project.md} (51%) create mode 100644 docs/user/cli-reference/03-env.md create mode 100644 docs/user/cli-reference/04-plugin.md create mode 100644 docs/user/cli-reference/05-snapshot.md create mode 100644 docs/user/cli-reference/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ae3f2c8..f2be7e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,8 +20,17 @@ DAYS 日（既定 7、`DEVBASE_IMAGE_MAX_AGE_DAYS` で上書き可）以上のときのみ no-cache で 再ビルドし、未満なら再ビルドしません（既存イメージを使用）。親イメージ（`FROM devbase-*`）の 作成日は独立して判定します。`devbase build` の `--no-cache` も明示フラグとして整理しました。 +- **外部リポジトリ連携プロジェクト向けドキュメント (`docs/plugin-dev/repo-backed-projects.md`)** + を追加しました。アプリ本体のリポジトリを共有 work ボリュームへ取り込み、複数コンテナで動かす + プロジェクトのための `pre-up` populate パターン（初回のみ populate し、2 回目以降はコンテナ側の + ソース・環境ファイルを上書きしない冪等スキップ）と、その設計意図・更新運用・チェックリストを + 解説しています。 ### Changed +- **CLI リファレンス (`docs/user/cli-reference.md`) をコマンドグループ別ディレクトリ + (`docs/user/cli-reference/`) に分割**しました。目次 (`README.md`) とトップレベル / project / + env / plugin / snapshot の各ファイルに再編し、1 ファイルあたりの分量を抑えて目的のコマンドへ + 辿りやすくしました。他ドキュメントからの参照リンクも新パスへ更新しています。 - **`build` / `rebuild` / `up` の再ビルド仕様を統一**しました (i07)。キャッシュの 扱いを 3 モード（既定=キャッシュビルド / `--no-cache`=無条件 no-cache / `--expires=N`= 期限切れ時のみ no-cache・期限内は再ビルドしない）に整理し、`devbase rebuild` を diff --git a/docs/README.md b/docs/README.md index 182e3ca..eae5723 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,7 +43,7 @@ graph TD | ドキュメント | 内容 | |-------------|------| | [はじめに](user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー | -| [CLI リファレンス](user/cli-reference.md) | 全コマンドの構文・オプション・使用例 | +| [CLI リファレンス](user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例 | | [プラグインレジストリ](user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 | | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 | | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 | @@ -73,6 +73,7 @@ graph LR | [プラグイン開発クイックスタート](plugin-dev/quickstart.md) | 最小構成プラグインの作成手順 | | [plugin.yml リファレンス](plugin-dev/plugin-yml-reference.md) | プラグイン定義ファイルの全フィールド | | [compose.yml ガイドライン](plugin-dev/compose-yml-guidelines.md) | Docker Compose 設定のベストプラクティス | +| [repo 連携プロジェクトと pre-up populate](plugin-dev/repo-backed-projects.md) | 外部リポジトリを共有 work ボリュームへ populate する `pre-up` パターンと冪等スキップ | ### devbase 開発者（devbase 本体を改善したい方） @@ -91,7 +92,13 @@ docs/ ├── README.md ← このファイル（ドキュメント索引） ├── user/ ← 利用者向け │ ├── getting-started.md ← はじめに -│ ├── cli-reference.md ← CLI リファレンス +│ ├── cli-reference/ ← CLI リファレンス（コマンドグループ別） +│ │ ├── README.md ← 目次・コマンド体系 +│ │ ├── 01-toplevel.md ← init / status / rc +│ │ ├── 02-project.md ← project グループ +│ │ ├── 03-env.md ← env グループ +│ │ ├── 04-plugin.md ← plugin グループ +│ │ └── 05-snapshot.md ← snapshot グループ │ ├── plugin-registries.md ← プラグインレジストリ │ ├── environment-variables.md ← 環境変数ガイド │ ├── container-operations.md ← コンテナ操作ガイド @@ -100,7 +107,8 @@ docs/ ├── plugin-dev/ ← プラグイン開発者向け │ ├── quickstart.md ← クイックスタート │ ├── plugin-yml-reference.md ← plugin.yml リファレンス -│ └── compose-yml-guidelines.md ← compose.yml ガイドライン +│ ├── compose-yml-guidelines.md ← compose.yml ガイドライン +│ └── repo-backed-projects.md ← repo 連携 / pre-up populate パターン └── developer/ ← devbase 開発者向け ├── architecture.md ← アーキテクチャ ├── contributing.md ← コントリビューション @@ -114,7 +122,7 @@ docs/ | やりたいこと | 参照先 | |-------------|--------| | devbase を初めてインストールする | [はじめに](user/getting-started.md#セットアップ手順) | -| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference.md) | +| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference/README.md) | | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) | | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) | | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) | diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index ad15db8..e607daa 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -148,6 +148,8 @@ fi > **Note:** どちらのフックも `bash` で実行されます。`chmod +x` で実行可能ビットを立てておいてください。`pre-up` が非ゼロ終了すると `devbase up` は中断します。`deploy` は各インスタンスに対して `DEVBASE_INSTANCE_INDEX` を環境変数として渡しますが、失敗してもデプロイは続行されます。 +> **応用:** 外部リポジトリを共有 work ボリュームへ取り込み、app / nginx / db など複数コンテナで動かすプロジェクトでは、`pre-up` で clone/pull と work ボリュームへの populate を行い、2 回目以降はコンテナ側を上書きしないよう冪等にスキップするのが定石です。詳細は [repo 連携プロジェクトと pre-up populate パターン](repo-backed-projects.md) を参照してください。 + --- ## 3. ローカルでの開発・テスト diff --git a/docs/plugin-dev/repo-backed-projects.md b/docs/plugin-dev/repo-backed-projects.md new file mode 100644 index 0000000..ae64df9 --- /dev/null +++ b/docs/plugin-dev/repo-backed-projects.md @@ -0,0 +1,171 @@ +# repo 連携プロジェクトと `pre-up` populate パターン + +外部リポジトリ（アプリ本体）を丸ごと取り込み、複数コンテナ（app / nginx / db 等）で共有して動かすタイプのプロジェクト向けのガイドです。`pre-up` ライフサイクルフックで **ホスト側リポジトリの clone/pull** と **共有 work ボリュームへの populate** を行い、2 回目以降の `devbase up` では populate 済みを検出して同期をスキップする冪等パターンを解説します。 + +リファレンス実装は `projects/carmo-system-console`（Laravel Sail ベース）です。 + +> **前提:** ライフサイクルフック自体の基本は [プラグイン開発クイックスタート](quickstart.md#25-ライフサイクルフック任意) を、共有ボリュームや `CONTAINER_SCALE` の一般論は [compose.yml ガイドライン](compose-yml-guidelines.md) と [コンテナ操作ガイド](../user/container-operations.md#並行開発) を参照してください。本書はそれらを組み合わせた「repo 連携」パターンに絞って説明します。 + +--- + +## 1. なぜこのパターンが必要か + +`devbase-general` / `devbase-php` のような単一 dev コンテナのプロジェクトでは、各コンテナが専用の `/work` ボリュームを持ち、ソースはコンテナ内で `git clone` すれば十分です。 + +一方で、アプリ本体のリポジトリに付属する `docker-compose.dev.yml` 相当（app / nginx / mysql / redis …）を devbase 上で再現したい場合、次の要件が生じます。 + +- **複数コンテナが同一のソースツリーを共有**する必要がある（app が書いた成果物を nginx が配信する等）。 +- app サービスは **リポジトリ内の `Dockerfile` をビルドコンテキスト**として使うため、ホスト側にソースの実体が必要。 +- コンテナ内 `git clone` に頼ると、複数コンテナの起動順で **clone レース**が起きる。 + +これを解決するのが「ホスト `repo/` を用意し、それを共有 work ボリュームへ populate してから全コンテナを起動する」パターンです。populate を `pre-up`（`docker compose up` の前）に寄せることで、app / nginx / mysql が立ち上がる前にソースを確定できます。 + +--- + +## 2. 全体構成 + +```mermaid +graph TD + S["リモート git リポジトリ
(volareinc/app 等)"] -->|"pre-up ① clone/pull"| R["ホスト ./repo
(app のビルドコンテキスト)"] + S3["S3
env/<env>.env"] -->|"pre-up ② 取得"| E["ホスト ./.env
(compose 変数展開用)"] + R -->|"pre-up ③ populate"| V["共有 work ボリューム
/work/<GIT_REPO>"] + E -->|"pre-up ④ 配置"| V + V --> A["app コンテナ /work"] + V --> N["nginx コンテナ /work:ro"] + V --> M["mysql コンテナ /work:ro"] + V --> D["dev コンテナ /work"] +``` + +| 要素 | 実体 | 役割 | +|------|------|------| +| ホスト `./repo` | `git clone` した作業コピー | app イメージのビルドコンテキスト兼、work ボリュームの populate 元 | +| ホスト `./.env` | S3 から取得 | `docker compose` の変数展開（`${DB_DATABASE}` 等）に使用 | +| 共有 work ボリューム | `external: true` の named volume | 全コンテナが `/work` にマウントする実行時ソース | + +`compose.yml` では work ボリュームを **external** として宣言し、インスタンスごとに名前を切り替えます。 + +```yaml +services: + app: + build: + context: ./repo # ← ホスト repo/ をビルドコンテキストに + dockerfile: docker/Dockerfile + volumes: + - work:/work # ← 共有 work ボリューム + nginx: + volumes: + - work:/work:ro + # ... +volumes: + work: + external: true + name: ${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}} +``` + +> **Note:** `pre-up` は子プロセスのため `export DEVBASE_WORK_VOLUME` しても後続の `docker compose up` へは伝播しません。`compose.yml` 側は `${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` のフォールバック式で解決し、加えて `pre-up` が同じ値を `.env` に書き出すことで整合を取ります。 + +--- + +## 3. `pre-up` の 4 つの責務 + +`pre-up` は毎回の `devbase up` 前に次を行います。 + +| # | 処理 | 内容 | +|---|------|------| +| ① | `repo/` の clone / pull | 無ければ `git clone`、あれば `git pull --ff-only`（app ビルドコンテキストの最新化） | +| ② | `.env` の取得 | S3 等から取得してホスト `./.env` に配置（`docker compose` の変数展開前に必要） | +| ③ | work ボリュームへ populate | `repo/` の内容を `/work/` へコピー | +| ④ | `.env` を work ボリュームへ配置 | Laravel 等のランタイムが `/work//.env` を参照するため | + +② を `deploy`（`up` 後フック）ではなく `pre-up` で行うのは、`compose.yml` の `MYSQL_DATABASE: ${DB_DATABASE:-...}` のような変数展開が `docker compose` パース時（＝ MySQL コンテナ初回起動前）に `.env` を要求するためです。`deploy` 段階では間に合わず、DB がデフォルト名で初期化されてしまいます。 + +--- + +## 4. 冪等性 — populate 済みならスキップ（重要） + +**このパターンの肝は「初回だけ populate し、2 回目以降はコンテナ側に触れない」ことです。** + +`pre-up` は work ボリューム上に `/work//.git` が存在するかどうかで populate 済みを判定し、済みの場合は ②③④ をスキップします。 + +| # | 処理 | 未populate（初回） | populate 済み（2回目以降） | +|---|------|:---:|:---:| +| ① | `repo/` の `git pull` | 実行 | **実行**（構成変更をビルドに追従） | +| ② | `.env` の S3 取得 | 実行 | スキップ | +| ③ | ソース populate | 実行 | スキップ | +| ④ | `.env` を volume へ配置 | 実行 | スキップ | + +### なぜスキップするのか + +populate 済みの work ボリュームを毎回ホスト `repo/` で上書き同期すると、次の破壊が起きます。 + +- **同期の除外リスト（`storage/` / `vendor/` / `node_modules/` / `.env` 等）に無いファイルが消える。** コンテナ内で生成した認証ファイルや作業ファイルが `devbase up` のたびに削除される。 +- **コンテナ側で編集した `.env` が上書きされる。** + +これを避けるため、実行時ソースと `.env` の供給は初回 populate 時に限定し、以降はコンテナ側を手動管理に委ねます。これはアプリ本体リポジトリが取る一般的な開発フローと同じ考え方です。多くのリポジトリでは、環境ファイルの取得やソースの用意は**ビルド時のセットアップスクリプト**が担い、日常の**起動（`docker compose up`）は環境ファイルやソースに触れません**。devbase の初回 populate がこのビルド時セットアップに相当し、2 回目以降の `up` は起動だけを行います。 + +一方で ①（`repo/` の pull）は常に実行します。これはホスト側のビルドコンテキストであり、`compose.yml` / `Dockerfile` / `docker/` 構成の変更を次回の app イメージ再ビルドへ反映するためです（アプリのソースコードそのものは work ボリューム側で管理）。 + +--- + +## 5. ソース・`.env` の更新運用 + +populate 済み以降、更新経路は次のように分かれます。 + +| 対象 | 場所 | 更新方法 | +|------|------|---------| +| ビルドコンテキスト | ホスト `./repo` | `pre-up` が毎回 `git pull`（自動） | +| 実行時ソース | work ボリューム `/work/` | **コンテナ内で手動 `git pull`** | +| 実行時 `.env` | work ボリューム `/work//.env` | コンテナ内で手動編集 | + +```bash +# 実行時ソースの更新（dev コンテナ内） +cd /work/ +git pull origin main +``` + +### クリーンに作り直す（再 populate） + +`.env` やソースを S3 / `repo/` の内容からやり直したい場合は、work ボリュームを削除して次回 `up` で populate を再実行させます。 + +```bash +devbase down +docker volume rm _devbase_work_1 # インスタンス番号は環境に応じて +devbase up # pre-up が ②③④ を再実行 +``` + +> **Warning:** work ボリュームには実行時ソースと `.env`、コンテナ内生成物が含まれます。削除前に必要な変更をコミット / 退避してください。DB 等の `sail-*` ボリュームは別管理なので、work ボリュームだけを消してもデータは残ります。 + +--- + +## 6. 関連する環境変数 + +| 変数 | 既定 | 効果 | +|------|------|------| +| `DEVBASE_REPO_PULL` | `1` | `0` にすると ①（`repo/` の `git pull`）を抑止。オフラインや意図的にビルドコンテキストを固定したいとき | +| `DEVBASE_ENV_OVERWRITE` | `backup` | 未 populate 時の既存ホスト `.env` の扱い。`backup`（`.env.bak.` に退避して上書き）/ `skip`（既存があれば S3 取得しない）/ `force`（退避せず上書き） | +| `DEVBASE_WORK_VOLUME` | `devbase_work_` | 共有 work ボリューム名の明示指定。未指定なら `DEVBASE_INSTANCE_INDEX` から解決 | +| `DEVBASE_INSTANCE_INDEX` | `1` | `devbase scale` 時にインスタンスごとの work ボリューム名を切り替えるためのインデックス（devbase 本体が付与） | + +> **Note:** `.env` の環境選択（例: `s3://.../env/local.env` の `local` 部分）など、S3 パスやプロファイルはプロジェクト固有の変数（例: `CARMO_ENV`）で制御することがあります。プロジェクトの `pre-up` 冒頭コメントを参照してください。 + +--- + +## 7. チェックリスト（新規に repo 連携プロジェクトを作るとき） + +- [ ] `env` に `GIT_USER` / `GIT_REPO` を定義した +- [ ] `compose.yml` で work ボリュームを `external: true` + `name: ${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` で宣言した +- [ ] app サービスの `build.context` をホスト `./repo` にした +- [ ] `pre-up` で ①clone/pull → ②`.env`取得 → ③populate → ④`.env`配置 を実装した +- [ ] `pre-up` が `/work//.git` の有無で populate 済みを判定し、②③④ をスキップする +- [ ] populate 時の owner を `1000:1000`（コンテナ内ユーザー）に設定した +- [ ] `storage/` / `vendor/` / `node_modules/` 等、初回のみ生成され上書きしたくないパスの扱いを決めた +- [ ] README にソース・`.env` の更新運用（手動 pull / 再 populate）を記載した + +--- + +## 参考 + +- リファレンス実装: `projects/carmo-system-console/pre-up` / `compose.yml` / `README.md` +- [プラグイン開発クイックスタート](quickstart.md) — ライフサイクルフックの基本 +- [compose.yml ガイドライン](compose-yml-guidelines.md) — 共有ボリューム・スケール構成 +- [コンテナ操作ガイド](../user/container-operations.md) — `/work` ボリュームの一般論 diff --git a/docs/user/cli-reference/01-toplevel.md b/docs/user/cli-reference/01-toplevel.md new file mode 100644 index 0000000..f9e06b8 --- /dev/null +++ b/docs/user/cli-reference/01-toplevel.md @@ -0,0 +1,41 @@ +# トップレベルコマンド + +[CLI リファレンス目次に戻る](README.md) + +## `devbase init` + +devbase の初期セットアップを実行します。 + +``` +devbase init +``` + +実行内容: +- `bin/devbase` を PATH に追加（`~/.bashrc` / `~/.zshrc`） +- シェル補完スクリプトの登録 +- `plugins.yml` の作成（存在しない場合） + +## `devbase status` + +現在の環境の状態をまとめて表示します。 + +``` +devbase status +``` + +表示項目: +- コンテナの状態（起動中 / 停止中 / 未ビルド） +- インストール済みプラグイン一覧 +- 環境変数の設定状況 +- スナップショットの状態 + +## `bin/rc`（いまのシェルで有効化） + +`devbase init` 後に **いま開いているシェル**で devbase（PATH / 補完）を即時有効化するための source 用スクリプトです。`devbase` のサブコマンドではなく、`bin/rc` を直接 source して使います。 + +```bash +./bin/devbase init +. ./bin/rc # = source ./bin/rc （bash / zsh 共通） +``` + +`bin/rc` は自身の場所から `DEVBASE_ROOT` を解決し、`DEVBASE_ROOT/bin` を PATH へ追加（冪等）したうえで、シェル補完を読み込みます（`init` が rc ファイルへ追記する有効化と同じ内容）。新しく開くシェルは init が rc に追記したブロックで自動有効化されるため、この手順は不要です。 diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference/02-project.md similarity index 51% rename from docs/user/cli-reference.md rename to docs/user/cli-reference/02-project.md index 9fb90f2..1f2ae9e 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference/02-project.md @@ -1,125 +1,10 @@ -# CLI リファレンス - -devbase の全コマンドの構文、オプション、使用例をまとめたリファレンスです。 - -## コマンド体系 - -devbase のコマンドは 4 つのグループとトップレベルコマンドで構成されています。 - -```mermaid -graph TD - A[devbase] --> B[init] - A --> C[status] - A --> D[project] - A --> E[env] - A --> F[plugin / pl] - A --> G[snapshot / ss] - D --> D1["up / down / ps / logs / scale [name]"] - D --> D3["login [index]"] - D --> D4["build [image] / rebuild [name]"] - D --> D2["list [--no-interactive]"] - E --> E1[init / sync / list / set / get / delete / edit / project / export / import] - F --> F1[list / install / uninstall / update / info / sync / migrate] - F --> F2[repo add / repo remove / repo list / repo refresh] - G --> G1[create / list / restore / copy / delete / rotate] -``` - -> **`container` グループは非推奨になりました。** 旧 `devbase container ` は -> `devbase project ` のエイリアスとして当面動作しますが、実行時に非推奨警告を -> 表示します（移行期間後のリリースで削除予定）。新しいコマンドは `project` を使用してください。 - -### グループエイリアス - -各グループには短縮形が用意されています。 - -| グループ名 | エイリアス | 備考 | -|-----------|-----------|------| -| `plugin` | `pl` | | -| `snapshot` | `ss` | | -| `container` | `ct` | **非推奨**（`project` へ移行してください） | - -### ショートカットコマンド - -頻繁に使用するプロジェクト操作はトップレベルから直接実行できます。これらは `project` グループに自動転送されます。 - -| ショートカット | 転送先 | -|--------------|--------| -| `devbase up [name]` | `devbase project up [name]` | -| `devbase down [name]` | `devbase project down [name]` | -| `devbase login [index]` | `devbase project login [index]` | -| `devbase build [image]` | `bin/devbase` の `cmd_build`（シェル実装）※ | -| `devbase ps [name]` | `devbase project ps [name]` | -| `devbase scale [name] ` | `devbase project scale [name] ` | -| `devbase rebuild [name]` | `devbase project rebuild [name]` | -| `devbase list` | `devbase project list` | - -> **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 -> -> **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / ``）は他の -> ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の -> シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため -> です（名前指定はラッパーの `cd` で解決）。ただし `devbase build --expires[=DAYS]` のみ、作成日の -> 判定が必要なため例外的に Python 経路（`project build`）へ委譲されます。挙動上の入出力は同等です。 - -### ユニークプレフィックスマッチング - -コマンド名が一意に特定できる場合、先頭の数文字だけで実行できます。 - -```bash -# 以下は全て同じコマンド -devbase plugin list -devbase pl list -devbase p l -devbase pl l -``` - -> **Note:** 一意に特定できない場合は候補が表示されます。 - -## トップレベルコマンド - -### `devbase init` - -devbase の初期セットアップを実行します。 - -``` -devbase init -``` - -実行内容: -- `bin/devbase` を PATH に追加（`~/.bashrc` / `~/.zshrc`） -- シェル補完スクリプトの登録 -- `plugins.yml` の作成（存在しない場合） - -### `devbase status` - -現在の環境の状態をまとめて表示します。 - -``` -devbase status -``` - -表示項目: -- コンテナの状態（起動中 / 停止中 / 未ビルド） -- インストール済みプラグイン一覧 -- 環境変数の設定状況 -- スナップショットの状態 - -### `bin/rc`（いまのシェルで有効化） +# project グループ -`devbase init` 後に **いま開いているシェル**で devbase（PATH / 補完）を即時有効化するための source 用スクリプトです。`devbase` のサブコマンドではなく、`bin/rc` を直接 source して使います。 - -```bash -./bin/devbase init -. ./bin/rc # = source ./bin/rc （bash / zsh 共通） -``` - -`bin/rc` は自身の場所から `DEVBASE_ROOT` を解決し、`DEVBASE_ROOT/bin` を PATH へ追加（冪等）したうえで、シェル補完を読み込みます（`init` が rc ファイルへ追記する有効化と同じ内容）。新しく開くシェルは init が rc に追記したブロックで自動有効化されるため、この手順は不要です。 - -## project グループ +[CLI リファレンス目次に戻る](README.md) プロジェクト（コンテナ）のライフサイクル管理と一覧表示を行うコマンド群です。 -### プロジェクト名指定（CWD 非依存） +## プロジェクト名指定（CWD 非依存） `up` / `down` / `ps` / `logs` / `scale` は省略可能な `[name]` 引数を取ります。`[name]` を指定すると、**現在のディレクトリに依存せず** `$DEVBASE_ROOT/projects/` を対象に @@ -155,7 +40,7 @@ cd $DEVBASE_ROOT/projects/adminer && devbase project up > トレードオフです。**回避策:** 衝突する場合は対象プロジェクトのディレクトリ内で実行するか、 > 明示的にそのプロジェクトへ切り替えてから（`cd` 済みの状態で）コマンドを実行してください。 -### `devbase project up` +## `devbase project up` コンテナを起動します。 @@ -186,7 +71,7 @@ devbase up [name] > ことがあります。確実に反映するには **`devbase build [name] --no-cache`** で再ビルドしてから > `devbase up` してください（`--no-cache` は `build` のオプションで、`rebuild` にはありません）。 -### `devbase project down` +## `devbase project down` コンテナを停止・削除します。 @@ -197,7 +82,7 @@ devbase down [name] - 停止時にスナップショットのローテーションを自動実行 -### `devbase project login` +## `devbase project login` コンテナにログインします。 @@ -218,7 +103,7 @@ devbase login devbase login 2 ``` -### `devbase project ps` +## `devbase project ps` 対象プロジェクトのコンテナ状態を `docker compose ps` で表示します。複数プロジェクトの 横断一覧は `devbase project list` を使用してください。 @@ -232,7 +117,7 @@ devbase ps [name] [-a] |-----------|------| | `-a` | 停止中のコンテナも表示 | -### `devbase project logs` +## `devbase project logs` コンテナのログを表示します（トップレベルシノニムはありません）。 @@ -250,7 +135,7 @@ devbase project logs [name] [-f] [--tail N] devbase project logs -f --tail 50 ``` -### `devbase project scale` +## `devbase project scale` 既存のコンテナを再起動せずにスケールします。 @@ -272,7 +157,7 @@ devbase project scale 3 devbase project scale adminer 3 ``` -### `devbase project build` +## `devbase project build` コンテナイメージをビルドします。キャッシュの扱いは 3 モードあります。 @@ -297,7 +182,7 @@ devbase build [image] [--no-cache | --expires[=DAYS]] > 単体ビルドでは `--no-cache` のみ反映され、`--expires` は対象外です。`--expires` 付きビルドは > 作成日判定のため Python 経路（`project build`）で処理されます。 -### `devbase project rebuild` +## `devbase project rebuild` `devbase build --expires=7` のシノニムです（既定 7 日）。プロジェクトイメージが 7 日以上古ければ no-cache で再ビルドし、未満なら再ビルドしません（既存イメージを使用）。親イメージ（`FROM devbase-*`）の @@ -312,7 +197,7 @@ devbase rebuild [name] |-----------|------|------| | `name` | いいえ | 対象プロジェクト名（省略時はカレント） | -### `devbase project list` +## `devbase project list` `$DEVBASE_ROOT/projects/` 配下のプロジェクトを `NAME` / `PLUGIN` / `STATUS` の一覧で 表示します。 @@ -332,7 +217,7 @@ devbase list [--no-interactive|--plain|-P] | `--no-interactive` / `--plain` / `-P` | TUI を起動せず一覧表示のみ | | `--interactive` / `-i` | （後方互換）TUI 起動。デフォルトのため通常は不要 | -#### TUI の画面構成とキー操作 +### TUI の画面構成とキー操作 ``` ? プロジェクトまたは操作を選択 (↑↓ 移動 / 名前で絞り込み / ←→ 下部メニュー / Enter 決定 / Esc・Ctrl-C 終了): @@ -406,335 +291,3 @@ devbase container up devbase project up devbase up ``` - -## env グループ - -環境変数の管理を行うコマンド群です。詳細は [環境変数ガイド](environment-variables.md) を参照してください。 - -### `devbase env init` - -環境変数の対話式初期セットアップを実行します。 - -``` -devbase env init [--reset] -``` - -| オプション | 説明 | -|-----------|------| -| `--reset` | 既存の設定をリセットして再設定 | - -### `devbase env sync` - -ソースファイル（`~/.aws/config` 等）の変更を検出し、環境変数を再同期します。 - -``` -devbase env sync -``` - -### `devbase env list` - -設定済みの環境変数を一覧表示します。 - -``` -devbase env list [-g|-p] [-r] [-k] -``` - -| オプション | 説明 | -|-----------|------| -| `-g` | グローバル変数のみ表示 | -| `-p` | プロジェクト変数のみ表示 | -| `-r` | 値も表示（デフォルトではキーのみ） | -| `-k` | キー名でソート | - -```bash -# グローバル変数のみ、値付きで表示 -devbase env list -g -r - -# プロジェクト変数をキー名順で表示 -devbase env list -p -k -``` - -### `devbase env set` - -環境変数を設定します。 - -``` -devbase env set KEY=VALUE [-p] -``` - -| オプション | 説明 | -|-----------|------| -| `-p` | プロジェクトレベルに設定（デフォルトはグローバル） | - -```bash -# グローバルに設定 -devbase env set ANTHROPIC_API_KEY=sk-xxx - -# プロジェクトレベルに設定 -devbase env set GCP_ACTIVE_PROFILE=my-project -p -``` - -### `devbase env get` - -環境変数の値を取得します。 - -``` -devbase env get KEY -``` - -```bash -devbase env get AWS_PROFILE -``` - -### `devbase env delete` - -環境変数を削除します。 - -``` -devbase env delete KEY -``` - -### `devbase env edit` - -デフォルトエディタで `.env` ファイルを開きます。 - -``` -devbase env edit -``` - -### `devbase env project` - -プロジェクト固有の環境変数を対話式で設定します。 - -``` -devbase env project -``` - -### `devbase env export` - -複数プロジェクトの `.env` 群を暗号化したまま 1 つのバンドルにまとめて書き出します。 - -``` -devbase env export -``` - -オプション（age 鍵 / passphrase / S3 入出力など）の詳細は -[環境変数の export / import ガイド](env-export-import.md#devbase-env-export-リファレンス)を参照してください。 - -### `devbase env import` - -`devbase env export` で作成したバンドルを復号し、環境変数を取り込みます。 - -``` -devbase env import -``` - -`--dry-run` での確認や identity 鍵指定などの詳細は -[環境変数の export / import ガイド](env-export-import.md#devbase-env-import-リファレンス)を参照してください。 - -## plugin (pl) グループ - -プラグインの管理を行うコマンド群です。 - -### `devbase plugin list` - -インストール済み、または利用可能なプラグインを一覧表示します。 - -``` -devbase plugin list [--available] -``` - -| オプション | 説明 | -|-----------|------| -| `--available` | リポジトリから取得可能なプラグインを表示 | - -### `devbase plugin install` - -プラグインをインストールします。 - -``` -devbase plugin install -``` - -ソースの指定形式: - -| 形式 | 説明 | 例 | -|------|------|----| -| 名前のみ | 登録済みリポジトリから検索 | `devbase plugin install adminer` | -| リポジトリ直接指定 | 特定リポジトリのプラグイン | `devbase plugin install user/repo:plugin-name` | -| 全プラグイン一括 | リポジトリの全プラグインをインストール | `devbase plugin install user/repo --all` | -| ローカルリンク | ローカルディレクトリからリンク | `devbase plugin install /path:plugin-name --link` | - -### `devbase plugin uninstall` - -プラグインをアンインストールします。 - -``` -devbase plugin uninstall -``` - -### `devbase plugin update` - -プラグインを最新バージョンに更新します。 - -``` -devbase plugin update [name] -``` - -| パラメータ | 必須 | 説明 | -|-----------|------|------| -| `name` | いいえ | 更新するプラグイン名（省略時は全プラグイン） | - -### `devbase plugin info` - -プラグインの詳細情報を表示します。 - -``` -devbase plugin info -``` - -### `devbase plugin sync` - -プロジェクトのシンボリックリンクを再同期します。 - -``` -devbase plugin sync -``` - -### `devbase plugin migrate` - -旧形式 (`plugins/` へのコピー) でインストールされたプラグインを、`repos/` 配下の永続クローンへ移行します。`install` / `update` 実行時にも自動で呼び出されるため、通常は手動実行不要です。 - -``` -devbase plugin migrate -``` - -移行の挙動: - -| 状況 | 動作 | -|---|---| -| コピーがクローンと一致 | 旧コピーを削除し `repos/` へ移行 (migrated) | -| コピーにローカル変更あり | 旧コピーを `plugins/.bak` として保全 (preserved、手動で reconcile) | -| 移行できない (ソース未登録 等) | スキップしてエラーを表示 (skipped) | - -`--link` でインストールしたプラグインは移行対象外です。 - -### `devbase plugin repo add` - -プラグインリポジトリを登録します。 - -``` -devbase plugin repo add -``` - -```bash -# GitHub ショートハンド -devbase plugin repo add user/repo - -# 完全な URL -devbase plugin repo add https://github.com/user/repo.git -``` - -### `devbase plugin repo remove` - -リポジトリの登録を削除します。 - -``` -devbase plugin repo remove -``` - -### `devbase plugin repo list` - -登録済みリポジトリの一覧を表示します。 - -``` -devbase plugin repo list -``` - -### `devbase plugin repo refresh` - -プラグイン一覧をリポジトリから再取得します。 - -``` -devbase plugin repo refresh [name] -``` - -| パラメータ | 必須 | 説明 | -|-----------|------|------| -| `name` | いいえ | 更新するリポジトリ名（省略時は全リポジトリ） | - -## snapshot (ss) グループ - -スナップショットの管理を行うコマンド群です。詳細は [スナップショットガイド](snapshot-guide.md) を参照してください。 - -### `devbase snapshot create` - -スナップショットを作成します。 - -``` -devbase snapshot create [--name NAME] [--full] -``` - -| オプション | 説明 | -|-----------|------| -| `--name NAME` | スナップショット名を指定（デフォルトはタイムスタンプ） | -| `--full` | フルバックアップを強制作成 | - -```bash -# 自動命名で差分スナップショット -devbase snapshot create - -# 名前付きフルバックアップ -devbase snapshot create --name before-upgrade --full -``` - -### `devbase snapshot list` - -スナップショットの一覧を表示します。 - -``` -devbase snapshot list -``` - -### `devbase snapshot restore` - -スナップショットから復元します。 - -``` -devbase snapshot restore [--point N] -``` - -| パラメータ / オプション | 必須 | 説明 | -|----------------------|------|------| -| `` | はい | 復元するスナップショット名 | -| `--point N` | いいえ | N 番目の差分まで復元（省略時は最新まで全適用） | - -> **Warning:** 復元前に現在の状態が `pre-restore-` として自動バックアップされます。 - -### `devbase snapshot copy` - -スナップショットをコピーします。 - -``` -devbase snapshot copy -``` - -### `devbase snapshot delete` - -スナップショットを削除します。 - -``` -devbase snapshot delete -``` - -### `devbase snapshot rotate` - -古い世代のスナップショットを削除します。 - -``` -devbase snapshot rotate [--keep N] -``` - -| オプション | 説明 | -|-----------|------| -| `--keep N` | 保持する世代数（デフォルト: `3`） | diff --git a/docs/user/cli-reference/03-env.md b/docs/user/cli-reference/03-env.md new file mode 100644 index 0000000..408102d --- /dev/null +++ b/docs/user/cli-reference/03-env.md @@ -0,0 +1,126 @@ +# env グループ + +[CLI リファレンス目次に戻る](README.md) + +環境変数の管理を行うコマンド群です。詳細は [環境変数ガイド](../environment-variables.md) を参照してください。 + +## `devbase env init` + +環境変数の対話式初期セットアップを実行します。 + +``` +devbase env init [--reset] +``` + +| オプション | 説明 | +|-----------|------| +| `--reset` | 既存の設定をリセットして再設定 | + +## `devbase env sync` + +ソースファイル（`~/.aws/config` 等）の変更を検出し、環境変数を再同期します。 + +``` +devbase env sync +``` + +## `devbase env list` + +設定済みの環境変数を一覧表示します。 + +``` +devbase env list [-g|-p] [-r] [-k] +``` + +| オプション | 説明 | +|-----------|------| +| `-g` | グローバル変数のみ表示 | +| `-p` | プロジェクト変数のみ表示 | +| `-r` | 値も表示（デフォルトではキーのみ） | +| `-k` | キー名でソート | + +```bash +# グローバル変数のみ、値付きで表示 +devbase env list -g -r + +# プロジェクト変数をキー名順で表示 +devbase env list -p -k +``` + +## `devbase env set` + +環境変数を設定します。 + +``` +devbase env set KEY=VALUE [-p] +``` + +| オプション | 説明 | +|-----------|------| +| `-p` | プロジェクトレベルに設定（デフォルトはグローバル） | + +```bash +# グローバルに設定 +devbase env set ANTHROPIC_API_KEY=sk-xxx + +# プロジェクトレベルに設定 +devbase env set GCP_ACTIVE_PROFILE=my-project -p +``` + +## `devbase env get` + +環境変数の値を取得します。 + +``` +devbase env get KEY +``` + +```bash +devbase env get AWS_PROFILE +``` + +## `devbase env delete` + +環境変数を削除します。 + +``` +devbase env delete KEY +``` + +## `devbase env edit` + +デフォルトエディタで `.env` ファイルを開きます。 + +``` +devbase env edit +``` + +## `devbase env project` + +プロジェクト固有の環境変数を対話式で設定します。 + +``` +devbase env project +``` + +## `devbase env export` + +複数プロジェクトの `.env` 群を暗号化したまま 1 つのバンドルにまとめて書き出します。 + +``` +devbase env export +``` + +オプション（age 鍵 / passphrase / S3 入出力など）の詳細は +[環境変数の export / import ガイド](../env-export-import.md#devbase-env-export-リファレンス)を参照してください。 + +## `devbase env import` + +`devbase env export` で作成したバンドルを復号し、環境変数を取り込みます。 + +``` +devbase env import +``` + +`--dry-run` での確認や identity 鍵指定などの詳細は +[環境変数の export / import ガイド](../env-export-import.md#devbase-env-import-リファレンス)を参照してください。 diff --git a/docs/user/cli-reference/04-plugin.md b/docs/user/cli-reference/04-plugin.md new file mode 100644 index 0000000..f635056 --- /dev/null +++ b/docs/user/cli-reference/04-plugin.md @@ -0,0 +1,132 @@ +# plugin (pl) グループ + +[CLI リファレンス目次に戻る](README.md) + +プラグインの管理を行うコマンド群です。 + +## `devbase plugin list` + +インストール済み、または利用可能なプラグインを一覧表示します。 + +``` +devbase plugin list [--available] +``` + +| オプション | 説明 | +|-----------|------| +| `--available` | リポジトリから取得可能なプラグインを表示 | + +## `devbase plugin install` + +プラグインをインストールします。 + +``` +devbase plugin install +``` + +ソースの指定形式: + +| 形式 | 説明 | 例 | +|------|------|----| +| 名前のみ | 登録済みリポジトリから検索 | `devbase plugin install adminer` | +| リポジトリ直接指定 | 特定リポジトリのプラグイン | `devbase plugin install user/repo:plugin-name` | +| 全プラグイン一括 | リポジトリの全プラグインをインストール | `devbase plugin install user/repo --all` | +| ローカルリンク | ローカルディレクトリからリンク | `devbase plugin install /path:plugin-name --link` | + +## `devbase plugin uninstall` + +プラグインをアンインストールします。 + +``` +devbase plugin uninstall +``` + +## `devbase plugin update` + +プラグインを最新バージョンに更新します。 + +``` +devbase plugin update [name] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `name` | いいえ | 更新するプラグイン名（省略時は全プラグイン） | + +## `devbase plugin info` + +プラグインの詳細情報を表示します。 + +``` +devbase plugin info +``` + +## `devbase plugin sync` + +プロジェクトのシンボリックリンクを再同期します。 + +``` +devbase plugin sync +``` + +## `devbase plugin migrate` + +旧形式 (`plugins/` へのコピー) でインストールされたプラグインを、`repos/` 配下の永続クローンへ移行します。`install` / `update` 実行時にも自動で呼び出されるため、通常は手動実行不要です。 + +``` +devbase plugin migrate +``` + +移行の挙動: + +| 状況 | 動作 | +|---|---| +| コピーがクローンと一致 | 旧コピーを削除し `repos/` へ移行 (migrated) | +| コピーにローカル変更あり | 旧コピーを `plugins/.bak` として保全 (preserved、手動で reconcile) | +| 移行できない (ソース未登録 等) | スキップしてエラーを表示 (skipped) | + +`--link` でインストールしたプラグインは移行対象外です。 + +## `devbase plugin repo add` + +プラグインリポジトリを登録します。 + +``` +devbase plugin repo add +``` + +```bash +# GitHub ショートハンド +devbase plugin repo add user/repo + +# 完全な URL +devbase plugin repo add https://github.com/user/repo.git +``` + +## `devbase plugin repo remove` + +リポジトリの登録を削除します。 + +``` +devbase plugin repo remove +``` + +## `devbase plugin repo list` + +登録済みリポジトリの一覧を表示します。 + +``` +devbase plugin repo list +``` + +## `devbase plugin repo refresh` + +プラグイン一覧をリポジトリから再取得します。 + +``` +devbase plugin repo refresh [name] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `name` | いいえ | 更新するリポジトリ名（省略時は全リポジトリ） | diff --git a/docs/user/cli-reference/05-snapshot.md b/docs/user/cli-reference/05-snapshot.md new file mode 100644 index 0000000..d55ad16 --- /dev/null +++ b/docs/user/cli-reference/05-snapshot.md @@ -0,0 +1,77 @@ +# snapshot (ss) グループ + +[CLI リファレンス目次に戻る](README.md) + +スナップショットの管理を行うコマンド群です。詳細は [スナップショットガイド](../snapshot-guide.md) を参照してください。 + +## `devbase snapshot create` + +スナップショットを作成します。 + +``` +devbase snapshot create [--name NAME] [--full] +``` + +| オプション | 説明 | +|-----------|------| +| `--name NAME` | スナップショット名を指定（デフォルトはタイムスタンプ） | +| `--full` | フルバックアップを強制作成 | + +```bash +# 自動命名で差分スナップショット +devbase snapshot create + +# 名前付きフルバックアップ +devbase snapshot create --name before-upgrade --full +``` + +## `devbase snapshot list` + +スナップショットの一覧を表示します。 + +``` +devbase snapshot list +``` + +## `devbase snapshot restore` + +スナップショットから復元します。 + +``` +devbase snapshot restore [--point N] +``` + +| パラメータ / オプション | 必須 | 説明 | +|----------------------|------|------| +| `` | はい | 復元するスナップショット名 | +| `--point N` | いいえ | N 番目の差分まで復元（省略時は最新まで全適用） | + +> **Warning:** 復元前に現在の状態が `pre-restore-` として自動バックアップされます。 + +## `devbase snapshot copy` + +スナップショットをコピーします。 + +``` +devbase snapshot copy +``` + +## `devbase snapshot delete` + +スナップショットを削除します。 + +``` +devbase snapshot delete +``` + +## `devbase snapshot rotate` + +古い世代のスナップショットを削除します。 + +``` +devbase snapshot rotate [--keep N] +``` + +| オプション | 説明 | +|-----------|------| +| `--keep N` | 保持する世代数（デフォルト: `3`） | diff --git a/docs/user/cli-reference/README.md b/docs/user/cli-reference/README.md new file mode 100644 index 0000000..b81e0ad --- /dev/null +++ b/docs/user/cli-reference/README.md @@ -0,0 +1,84 @@ +# CLI リファレンス + +devbase の全コマンドの構文、オプション、使用例をまとめたリファレンスです。コマンドグループごとにファイルを分けています。 + +| ファイル | 内容 | +|---------|------| +| [トップレベルコマンド](01-toplevel.md) | `init` / `status` / `bin/rc` | +| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `list`）と非推奨の `container` グループ | +| [env グループ](03-env.md) | 環境変数の管理（`init` / `sync` / `list` / `set` / `get` / `delete` / `edit` / `project` / `export` / `import`） | +| [plugin グループ](04-plugin.md) | プラグインの管理（`list` / `install` / `uninstall` / `update` / `info` / `sync` / `migrate` / `repo *`） | +| [snapshot グループ](05-snapshot.md) | スナップショットの管理（`create` / `list` / `restore` / `copy` / `delete` / `rotate`） | + +## コマンド体系 + +devbase のコマンドは 4 つのグループとトップレベルコマンドで構成されています。 + +```mermaid +graph TD + A[devbase] --> B[init] + A --> C[status] + A --> D[project] + A --> E[env] + A --> F[plugin / pl] + A --> G[snapshot / ss] + D --> D1["up / down / ps / logs / scale [name]"] + D --> D3["login [index]"] + D --> D4["build [image] / rebuild [name]"] + D --> D2["list [--no-interactive]"] + E --> E1[init / sync / list / set / get / delete / edit / project / export / import] + F --> F1[list / install / uninstall / update / info / sync / migrate] + F --> F2[repo add / repo remove / repo list / repo refresh] + G --> G1[create / list / restore / copy / delete / rotate] +``` + +> **`container` グループは非推奨になりました。** 旧 `devbase container ` は +> `devbase project ` のエイリアスとして当面動作しますが、実行時に非推奨警告を +> 表示します（移行期間後のリリースで削除予定）。新しいコマンドは `project` を使用してください。 + +### グループエイリアス + +各グループには短縮形が用意されています。 + +| グループ名 | エイリアス | 備考 | +|-----------|-----------|------| +| `plugin` | `pl` | | +| `snapshot` | `ss` | | +| `container` | `ct` | **非推奨**（`project` へ移行してください） | + +### ショートカットコマンド + +頻繁に使用するプロジェクト操作はトップレベルから直接実行できます。これらは `project` グループに自動転送されます。 + +| ショートカット | 転送先 | +|--------------|--------| +| `devbase up [name]` | `devbase project up [name]` | +| `devbase down [name]` | `devbase project down [name]` | +| `devbase login [index]` | `devbase project login [index]` | +| `devbase build [image]` | `bin/devbase` の `cmd_build`（シェル実装）※ | +| `devbase ps [name]` | `devbase project ps [name]` | +| `devbase scale [name] ` | `devbase project scale [name] ` | +| `devbase rebuild [name]` | `devbase project rebuild [name]` | +| `devbase list` | `devbase project list` | + +> **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 +> +> **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / ``）は他の +> ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の +> シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため +> です（名前指定はラッパーの `cd` で解決）。ただし `devbase build --expires[=DAYS]` のみ、作成日の +> 判定が必要なため例外的に Python 経路（`project build`）へ委譲されます。挙動上の入出力は同等です。 + +### ユニークプレフィックスマッチング + +コマンド名が一意に特定できる場合、先頭の数文字だけで実行できます。 + +```bash +# 以下は全て同じコマンド +devbase plugin list +devbase pl list +devbase p l +devbase pl l +``` + +> **Note:** 一意に特定できない場合は候補が表示されます。 diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index c5b1838..e29770b 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -7,7 +7,7 @@ devbase のコンテナ管理機能について、ライフサイクル、並行 > 非推奨となり、`project` へのエイリアスとして警告付きで当面動作します。`project` では > `up` / `down` / `ps` / `logs` / `scale` に `[name]` を指定することで **任意のディレクトリ > から** 対象プロジェクトを操作できます。プロジェクト一覧は `devbase project list` を参照 -> してください。詳細は [CLI リファレンス](cli-reference.md#project-グループ) を参照。 +> してください。詳細は [CLI リファレンス: project グループ](cli-reference/02-project.md) を参照。 ## コンテナライフサイクル @@ -181,7 +181,7 @@ AI CLI ツールの設定や認証情報は、コンテナを再生成しても - `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（[環境変数](environment-variables.md) 参照）。 > **Note:** symlink 対象は entrypoint にビルド時 `COPY` で焼き込まれます。エントリを増減した場合は -> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス](cli-reference.md) の `devbase project up` の注記参照）。 +> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス: project グループ](cli-reference/02-project.md#devbase-project-up) の `devbase project up` の注記参照）。 ## コンテナイメージ階層 @@ -278,7 +278,7 @@ devbase list --no-interactive # --plain / -P も同義 > スナップショット / ステータス）へ ←→ キーで移動して各管理操作を実行できます。 > パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示のみに > フォールバックします。画面構成とキー操作の詳細は -> [CLI リファレンス](cli-reference.md#devbase-project-list) を参照してください。 +> [CLI リファレンス: project グループ](cli-reference/02-project.md#devbase-project-list) を参照してください。 `devbase project ps` が「対象プロジェクト 1 つのコンテナ状態」を表示するのに対し、 `devbase list` は「全プロジェクトの横断一覧」を表示します。 diff --git a/docs/user/env-export-import.md b/docs/user/env-export-import.md index 6f515d5..8eb9ce2 100644 --- a/docs/user/env-export-import.md +++ b/docs/user/env-export-import.md @@ -452,5 +452,5 @@ Phase 2 (commit) の途中で異常終了した可能性があります。次回 ## 関連ドキュメント - [環境変数ガイド](environment-variables.md) — 3 レベル構造とコレクター -- [CLI リファレンス](cli-reference.md) — 全コマンド一覧 +- [CLI リファレンス](cli-reference/README.md) — 全コマンド一覧 - [はじめに](getting-started.md) — 初回セットアップ diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md index 0b5112f..5940abb 100644 --- a/docs/user/getting-started.md +++ b/docs/user/getting-started.md @@ -249,7 +249,7 @@ devbase/ ## 次のステップ -- [CLI リファレンス](cli-reference.md) -- 全コマンドの詳細な使い方 +- [CLI リファレンス](cli-reference/README.md) -- 全コマンドの詳細な使い方 - [環境変数ガイド](environment-variables.md) -- 環境変数の3レベル構造とコレクター - [コンテナ操作ガイド](container-operations.md) -- 並行開発やボリュームの詳細 - [スナップショットガイド](snapshot-guide.md) -- バックアップと復元の仕組み diff --git a/docs/user/plugin-registries.md b/docs/user/plugin-registries.md index 6a3872a..66e8d4c 100644 --- a/docs/user/plugin-registries.md +++ b/docs/user/plugin-registries.md @@ -62,6 +62,6 @@ devbase plugin repo refresh ## 関連ドキュメント - [はじめに](getting-started.md) -- [CLI リファレンス](cli-reference.md) -- `plugin repo` サブコマンドの詳細 +- [CLI リファレンス: plugin グループ](cli-reference/04-plugin.md) -- `plugin repo` サブコマンドの詳細 - [プラグイン開発クイックスタート](../plugin-dev/quickstart.md) - [plugin.yml リファレンス](../plugin-dev/plugin-yml-reference.md)