habitat-usage

# Habitat Usage Guide Habitat is a dependency-sync tool for mono-repo-like layouts built from multiple Git repos and asset downloads. This skill provides setup guidance, copy-pastable config snippets, and a troubleshooting checklist for common sync failures. ## When to Apply - Setting up a “main repo + dependency repos/assets” workspace using `.habitat` + `DEPS` - Adding or changing dependency types: git repos, nested solutions, HTTP downloads, or custom actions - Debugging `hab sync` failures related to config, auth, network, or integrity checks ## Troubleshooting Inputs When sync fails (fetch errors, permission issues, timeouts), collect: - Habitat version and distribution (`./hab` wrapper in repo, `hab.pex`, etc.) - OS and architecture (darwin/windows/linux + arm64/x86_64) - The exact command and full error output (do not paste any secrets) - Relevant config snippets: - `.habitat` - `DEPS` (or the file pointed to by `deps_file` in `.habitat`) ## Installation and Versioning Prefer committing the Habitat wrapper (`hab`) and config files (`.habitat`, `DEPS`) into the repository so developers and CI use the same version and configuration. Avoid downloading `releases/latest` in automation, because it is not reproducible. Instead, pin to a specific release version (tag) and keep that pinned version consistent across developers and CI. ```bash HABITAT_VERSION="0.3.145" curl -L -o hab "https://github.com/lynx-family/habitat/releases/download/${HABITAT_VERSION}/hab" chmod +x hab ``` If you just want to try Habitat locally (not recommended for CI), you can download the latest release: ```bash curl -L -o hab "https://github.com/lynx-family/habitat/releases/latest/download/hab" chmod +x hab ``` If you need integrity verification, pin an expected SHA-256 for `hab` in your repo/CI and verify after download: ```bash 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 ``` ## Multi-Repo Setup (solutions + deps) ### 1) Generate `.habitat` (solution config) Generate the Habitat config at the main repo root: ```bash ./hab config <repo remote uri> ``` `.habitat` describes one or more solutions. Minimal example: ```python solutions = [ { "name": ".", "deps_file": "DEPS", "url": "git@github.com:namespace/repo.git", } ] ``` Fields: - `name`: solution name, typically `"."` for the main repo - `deps_file`: dependency manifest path (relative to the main repo root) - `url`: the main repo remote URL (used by the tool/CI) ### 2) Write `DEPS` (dependency manifest) In `DEPS`, define `deps = { ... }`. The key is the destination path in the main repo, and the value describes the dependency type and parameters. #### 2.1 git deps (source repositories) ```python deps = { "lib/example": { "type": "git", "url": "git@github.com:namespace/lib.git", "branch": "dev", } } ``` Notes: - Prefer stable refs (e.g., commit) for reproducibility; use branches when you want rolling updates. - If the destination directory already exists and contains local changes, decide whether overwriting is acceptable before syncing. #### 2.2 solution deps (nested solutions) If a dependency has its own dependency tree, you can bring it in as a solution and sync recursively: ```python deps = { "third_party/some_solution": { "type": "solution", "url": "git@github.com:namespace/solution_repo.git", "branch": "main", "deps_file": "DEPS", } } ``` #### 2.3 http deps (assets/archives/binaries) Use this to download archives, toolchains, model files, etc. Prefer providing integrity checks for verifiability and reproducibility: ```python deps = { "third_party/tooling": { "type": "http", "url": "https://example.com/tooling.zip", "sha256": "SHA256_HEX", } } ``` #### 2.4 action deps (custom sync actions) Use this to run extra steps during sync (generate files, copy assets, apply patches, etc.). Example: ```python 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, } } ``` ## Sync Dependencies (hab sync) Run at the main repo root: ```bash ./hab sync . ``` After sync, dependencies are materialized into the paths specified by the keys in `DEPS`. ## Track Config in Version Control Commit the wrapper and config files to enable one-command bootstrapping for developers and CI: ```bash git add hab .habitat DEPS && git commit -m "Add habitat to manage dependencies." ``` ## FAQ / Common Failures ### 1) git permission/auth failures Symptoms: - Errors like `Permission denied`, `Authentication failed`, or `Could not read from remote repository` Fix: - Ensure the dependency `url` protocol matches your environment (SSH/HTTPS). - For SSH, confirm your SSH key is configured and has access to the target repo. - In CI, confirm the runner is provisioned with the right credentials. ### 2) http integrity check failures (sha256 mismatch) Symptoms: - Download succeeds but integrity verification fails Fix: - Check whether `url` content changed or redirects to different content. - Recompute sha256 for the actual artifact and update `sha256` in `DEPS`. - If the URL is rolling (e.g., “latest”), prefer an immutable, versioned URL. ### 3) Sync hangs/timeouts Fix: - Identify which dependency is slow (temporarily comment out others and bisect). - Check proxy settings, DNS, and network reachability. - For large git deps, consider pinning to a commit and reducing unnecessary history (if supported by your setup). ## Response Format (when assisting users) When a user asks for help configuring deps, fixing errors, or speeding up sync, respond in this order: 1) Conclusion first (root cause + fix) 2) Minimal copy-pastable commands/snippets (`.habitat` / `DEPS` / `./hab sync .`) 3) Call out risky operations (overwriting local dirs, rolling deps harming reproducibility, etc.) 4) If it can still fail, list the next required inputs (version, full error log, relevant config snippets)