Advanced Topics¶
Environment File Chaining¶
Environment files are loaded in order; later files can reference variables set by earlier ones. This enables layered configuration where a base file sets roots and a dev file builds on them:
sequenceDiagram
participant L as Loader
participant B as base_env.json
participant D as dev_env.json
participant E as Environment
L->>B: load
B-->>E: APP_ROOT = "${__BUNDLE__}"
B-->>E: LOG_LEVEL = "WARNING"
L->>D: load
D-->>E: APP_CONFIG = "${APP_ROOT}/config/dev.json"
Note over E: APP_ROOT already set — expands correctly
D-->>E: LOG_LEVEL = "DEBUG" (overrides WARNING)
base_env.json:
dev_env.json:
Command Conflicts¶
When multiple bundles define the same command name, the last discovered bundle wins. Bundle discovery order is:
- Order of entries in
--stack/-s(top-to-bottom) - Order of roots in
ENVOY_BNDL_ROOTS(left-to-right), then alphabetical within each root
Run en --verbose --list to see these warnings and identify the conflict source.
Local Fallback¶
If no bundles are found through auto-discovery or a config file, Envoy walks up from the current working directory looking for .envoy/commands.json:
flowchart TD
CWD["Current directory\nR:/project/src/module"] --> C1{".envoy/\ncommands.json?"}
C1 -- No --> P1["R:/project/src"]
P1 --> C2{".envoy/\ncommands.json?"}
C2 -- No --> P2["R:/project"]
P2 --> C3{".envoy/\ncommands.json?"}
C3 -- Yes --> FOUND["Commands loaded\n(single-bundle mode)"]
C3 -- No --> P3["... continues to root"]
This allows running envoy from inside a project without any environment setup.
--trace — Variable Mutation Debugging¶
Use --trace VAR to see exactly how a variable is built through each env file:
Shows each assignment/append/prepend as it happens across global_env.json and the command's env files — useful when a path is missing or appearing in the wrong position.
Path Normalization¶
All values produced by env file processing are normalized to OS-native path separators before being applied to the subprocess environment. On Windows, forward slashes are converted to backslashes.
You can write paths with either separator in JSON files:
The subprocess will see R:\repo\my-bundle\py on Windows.
Python API Initialization Hooks (ENVOY_PYINIT)¶
Set ENVOY_PYINIT to a platform-separated (; on Windows, : elsewhere)
list of directories to have import envoy run every *.py file in each
directory (non-recursive, sorted by filename) once the module has finished
initializing:
Scripts run after the full public API is available, so they can freely
import envoy themselves. A script that raises is reported to stderr and
does not prevent the remaining scripts (or the import envoy itself) from
completing -- treat this the same as any other best-effort extension point
in envoy (e.g. bundle cache warmup). Unset or empty, ENVOY_PYINIT is a
no-op.
Bundle Publishing¶
The engit publish bundle command produces a clean, deployment-ready copy of any bundle:
flowchart LR
SRC["Bundle root\n(live checkout)"]
PUB["engit publish bundle"]
FOLD["output/\nbundle/v1.2.3/\n .envoy/\n py/\n LICENSE"]
ZIP["bundle-v1.2.3.zip\n(internal: bundle/v1.2.3/...)"]
SRC --> PUB
PUB -- "default" --> FOLD
PUB -- "--zip" --> ZIP
The default exclusions strip git artifacts, build outputs, and caches automatically. See
engit publish bundle
for full details.
GitHub Actions — Reusable Bundle Publish Workflow¶
Simple bundles can adopt a one-file release workflow by calling the versioned workflow from the Envoy Utils repository:
.github/workflows/build-release.yml in any bundle repo:
name: Release
on:
push:
tags:
- 'v*'
jobs:
publish:
uses: gtvfx-envoy/envoy_utils/.github/workflows/bundle-publish.yml@v0.1.0
with:
extra_excludes: 'scripts pyproject.toml' # optional
secrets: inherit
permissions:
contents: write
When a v* tag is pushed, GitHub runs engit publish bundle --zip --output dist
and uploads the resulting zip to the release assets automatically.