habitat-usage

Habitat 使用ガイド

Habitat は、複数の Git リポジトリとアセットのダウンロードから構成されるモノレポ的なレイアウト向けの依存関係同期ツールです。このスキルでは、セットアップのガイダンス、コピー＆ペースト可能な設定スニペット、よくある同期失敗のトラブルシューティングチェックリストを提供します。

適用する場面

• .habitat + DEPS を使って「メインリポジトリ + 依存リポジトリ/アセット」のワークスペースをセットアップするとき
• 依存関係の種類（Git リポジトリ、ネストされたソリューション、HTTP ダウンロード、カスタムアクション）を追加または変更するとき
• 設定、認証、ネットワーク、整合性チェックに関連する hab sync の失敗をデバッグするとき

トラブルシューティングの入力情報

同期が失敗したとき（フェッチエラー、権限の問題、タイムアウトなど）は、以下を収集してください:

• Habitat のバージョンと配布形態（リポジトリ内の ./hab ラッパー、hab.pex など）
• OS とアーキテクチャ（darwin/windows/linux + arm64/x86_64）
• 実行した正確なコマンドと完全なエラー出力（シークレットは貼り付けないでください）
• 関連する設定スニペット:
  • .habitat
  • DEPS（または .habitat の deps_file が指すファイル）

インストールとバージョニング

開発者と CI が同じバージョンと設定を使うように、Habitat のラッパー（hab）と設定ファイル（.habitat、DEPS）をリポジトリにコミットすることを推奨します。

自動化の中で releases/latest をダウンロードするのは、再現性がないため避けてください。代わりに特定のリリースバージョン（タグ）に固定し、その固定したバージョンを開発者と CI の間で一貫させてください。

HABITAT_VERSION="0.3.145"
curl -L -o hab "https://github.com/lynx-family/habitat/releases/download/${HABITAT_VERSION}/hab"
chmod +x hab

Habitat をローカルで試したいだけの場合（CI には推奨しません）、最新リリースをダウンロードできます:

curl -L -o hab "https://github.com/lynx-family/habitat/releases/latest/download/hab"
chmod +x hab

整合性検証が必要な場合は、リポジトリ/CI で hab の期待される SHA-256 を固定し、ダウンロード後に検証してください:

EXPECTED_SHA256="<fill-me>"

if command -v shasum >/dev/null 2>&1; then
  echo "${EXPECTED_SHA256}  hab" | shasum -a 256 -c -
else
  echo "${EXPECTED_SHA256}  hab" | sha256sum -c -
fi

マルチリポジトリのセットアップ（ソリューション + 依存関係）

1) .habitat の生成（ソリューション設定）

メインリポジトリのルートで Habitat 設定を生成します:

./hab config <repo remote uri>

.habitat は 1 つ以上のソリューションを記述します。最小限の例:

solutions = [
    {
        "name": ".",
        "deps_file": "DEPS",
        "url": "[email protected]:namespace/repo.git",
    }
]

フィールド:

• name: ソリューション名。通常、メインリポジトリでは "." を指定します
• deps_file: 依存関係マニフェストのパス（メインリポジトリのルートからの相対パス）
• url: メインリポジトリのリモート URL（ツール/CI が使用します）

2) DEPS の記述（依存関係マニフェスト）

DEPS では deps = { ... } を定義します。キーはメインリポジトリ内の配置先パスで、値は依存関係の種類とパラメータを記述します。

2.1 git 依存関係（ソースリポジトリ）

deps = {
    "lib/example": {
        "type": "git",
        "url": "[email protected]:namespace/lib.git",
        "branch": "dev",
    }
}

補足:

• 再現性のために安定した ref（コミットなど）を推奨します。ローリング更新が必要な場合はブランチを使用してください。
• 配置先のディレクトリがすでに存在し、ローカルの変更を含む場合は、同期する前に上書きしてよいか判断してください。

2.2 ソリューション依存関係（ネストされたソリューション）

依存関係が独自の依存関係ツリーを持つ場合、それをソリューションとして取り込み、再帰的に同期できます:

deps = {
    "third_party/some_solution": {
        "type": "solution",
        "url": "[email protected]:namespace/solution_repo.git",
        "branch": "main",
        "deps_file": "DEPS",
    }
}

2.3 http 依存関係（アセット/アーカイブ/バイナリ）

アーカイブ、ツールチェーン、モデルファイルなどをダウンロードする場合に使用します。検証可能性と再現性のために、整合性チェックを提供することを推奨します:

deps = {
    "third_party/tooling": {
        "type": "http",
        "url": "https://example.com/tooling.zip",
        "sha256": "SHA256_HEX",
    }
}

2.4 action 依存関係（カスタム同期アクション）

同期中に追加のステップ（ファイル生成、アセットのコピー、パッチの適用など）を実行する場合に使用します。例:

def example_function():
    from pathlib import Path
    import shutil

    dest_dir = Path("scripts/sync_something")
    dest_dir.mkdir(parents=True, exist_ok=True)
    src = dest_dir / "input.txt"
    dst = dest_dir / "output.txt"
    src.write_text("example\n", encoding="utf-8")
    shutil.copyfile(src, dst)


deps = {
    "scripts/sync_something": {
        "type": "action",
        "function": example_function,
    }
}

依存関係の同期（hab sync）

メインリポジトリのルートで実行します:

./hab sync .

同期後、依存関係は DEPS のキーで指定されたパスに展開されます。

設定をバージョン管理で追跡する

ラッパーと設定ファイルをコミットして、開発者と CI がワンコマンドでブートストラップできるようにします:

git add hab .habitat DEPS && git commit -m "Add habitat to manage dependencies."

FAQ / よくある失敗

1) git の権限/認証の失敗

症状:

• Permission denied、Authentication failed、Could not read from remote repository などのエラー

対処:

• 依存関係の url プロトコルが環境に合っている（SSH/HTTPS）ことを確認してください。
• SSH の場合は、SSH キーが設定され、対象リポジトリへのアクセス権があることを確認してください。
• CI の場合は、ランナーに適切な認証情報がプロビジョニングされていることを確認してください。

2) http 整合性チェックの失敗（sha256 の不一致）

症状:

• ダウンロードは成功するが、整合性検証が失敗する

修正:

• url の内容が変更されたか、異なる内容にリダイレクトされていないかを確認します。
• 実際の成果物の sha256 を再計算し、DEPS の sha256 を更新します。
• URL がローリング形式（例: 「latest」）の場合は、不変でバージョン固定された URL を優先します。

3) 同期のハング／タイムアウト

修正:

• どの依存関係が遅いのかを特定します（一時的に他をコメントアウトして二分探索します）。
• プロキシ設定、DNS、ネットワーク到達性を確認します。
• 大きな git 依存関係については、コミットに固定し、不要な履歴を削減することを検討します（セットアップが対応している場合）。

応答形式（ユーザーを支援する場合）

ユーザーが deps の設定、エラーの修正、同期の高速化について助けを求めた場合は、次の順序で応答します:

1. 結論を先に（根本原因 + 修正方法）
2. 最小限のコピー＆ペースト可能なコマンド／スニペット（.habitat / DEPS / ./hab sync .）
3. 危険な操作を明示する（ローカルディレクトリの上書き、再現性を損なうローリング deps など）
4. それでも失敗する可能性がある場合は、次に必要な入力（バージョン、完全なエラーログ、関連する設定スニペット）を列挙する