Configuration Reference

Configuration Reference

Covers every wip.yml key. Reorganizes README's Configuration section into a Kubernetes/Docker-Compose-style reference: key → meaning → default → caveats.

Outline

wip.yml basics

• What version: and mode: do
• Config file discovery rules (running from a subdirectory, --config PATH)
• The wslc: block (command: auto's lookup order)

Container Mode

• container: (naming the primary container; required once dependencies: has entries)
• network:
• Each dependencies: entry (image, command, env, ports, volumes, workdir, restart)
• Primary vs. sidecar: operational differences (what up/down/exec/run/build/interaction: target)
• interaction: (the commands: alias, and the ConfigError from declaring both)
  • type: exec / type: run / type: build
  • Collisions with built-in command names (working around them with wip dispatch NAME)
• restart: and wip up --watch
  • Supported values (no/always/unless-stopped/on-failure[:MAX_RETRIES])
  • Polling-based limitations (not event-based; doesn't inspect on-failure exit codes)

Compose Mode

• The compose: block (service, command, file, project)
• Mutual exclusivity with dependencies:/network:
• Where third-party compose-for-wslc tools fit (wip doesn't pick a winner)
• Supported command surface (up/down/exec/logs; run falls back to exec; type: run/build unsupported)

Compose Mode (Native)

• The compose: block (service, file, project) vs. mode: compose — no command:, no top-level container:
• Supported compose.yml subset
  • Per-service: image, build, command, environment, ports/volumes (short syntax only), working_dir, user, restart, depends_on (service_started only)
  • Accepted-but-ignored keys: tty, stdin_open, networks
  • Top-level sections ignored outright: networks:, volumes:, configs:, secrets:
  • What happens when an unsupported key is used (ConfigError naming the offending key)
• wip logs's single-service limitation

Dependencies & Networking (cross-cutting)

• Diagramming the primary/sidecar design
• When the network gets created (at wip up, if missing)

.env

• Loading rules (KEY=VALUE, comments, export, quoted values)
• Precedence (env: always wins over .env)
• --env-file PATH

.dockerignore & Build Context

• How wip build honors .dockerignore
• Build-context optimization via shadow_context (WSL2 only; disabled on /mnt/<drive>)

Source Sync (sync:)

• Full parameter list (source, target, volume, mount, exclude, delete, command, options, interval, mode, image, build)
• sync.mode: exec vs. run, and how image requirements differ
• Default differences by mode (container/compose-native vs. compose)
• Default exclude list per wip init --template
• Mount-rewriting rules driven by the volume
• sync.build behavior (built once per wip up/wip sync invocation, once before a --watch loop starts)
• Caveats (one-way sync; when to reach for delete: false)