Skip to main content

envy sync

Install every package the manifest requests, then deploy product wrapper scripts into the project's bin directory. sync is install plus deploy. Run it after editing the manifest, and whenever you are unsure. It is idempotent and incremental, and on a terminal a run with nothing to do says nothing.

A fresh clone does not need it. The committed wrappers bootstrap envy and install what they need on first call, so sync is for maintaining the bin directory and for installing everything up front rather than on demand.

A run does the following, in order:

  1. Re-exec into the envy version the manifest pins.
  2. Refresh the .luarc.json type paths for that version.
  3. Install every target package concurrently, skipping anything already cached. A package the manifest vendors also gets its copy in the project tree made or checked, as the last step of its own pipeline.
  4. Restamp the bootstrap scripts.
  5. Write, refresh, and prune the product wrappers in the bin directory.

Usage​

envy sync [<queries>...] [--manifest=<path>] [--strict] [--subproject]
          [--platform=posix|windows|all] [--ignore-depot]

Arguments and flags​

Argument or flagMeaning
queriesWhich manifest entries to sync. See query forms. No queries means everything.
--manifest <path>Use this manifest instead of discovery.
--strictError instead of skipping when a file in the bin directory collides with a product script name and is not envy-managed.
--subprojectStop discovery at the nearest manifest instead of walking to the project root. Mutually exclusive with --manifest.
--platform posix|windows|allWhich wrapper flavors to write: shell scripts, .bat files, or both. Defaults to the current OS.
--ignore-depotIgnore the package depot and build from source. Env: ENVY_IGNORE_DEPOT.

@envy bin is required, because sync has nowhere to deploy without it. envy creates the bin directory if it is missing. Deployment also needs @envy deploy "true". Without it, packages install and sync warns that deployment is off, which is install with a warning attached.

Reach for sync when the bin directory has to change: after a manifest edit that touched a product, after envy use, or to restore a directory you cleaned. A version bump, a cache wipe, and a switch to a project-local cache all leave the wrappers correct, because a wrapper resolves its package at call time.

Examples​

To install everything up front​

envy sync

Running a tool would install it on demand, so this is for when you want the whole manifest resolved now. The committed bin/envy bootstrap script downloads the pinned envy, which installs every package and deploys a wrapper per product.

If all you want is the packages, install is the smaller command: going offline, timing a build, warming a CI or Docker cache. sync earns its deploy half when the manifest edit changed which products exist.

To pick up a package you just added to the manifest​

envy sync

The same command. Cached packages are skipped, the new one installs, and the new product's wrapper appears in the bin directory.

To install one package while iterating on its spec​

envy sync envy.cmake@r0

Dependencies come along. Unrelated packages are left alone.

warning

A filtered sync only knows about the filtered subgraph, and the deploy step prunes envy-managed wrappers it does not recognize. In a project with ten products, sync envy.cmake@r0 leaves cmake's wrappers and removes the others. Run a bare envy sync to restore them. Wrappers you own are never pruned, because they carry no marker.

To commit wrappers for a platform you are not on​

envy sync --platform all

This writes both the POSIX scripts and the .bat files, so a Windows colleague gets working wrappers from a repo synced on macOS. Pruning is limited to the flavors you name, so --platform posix never touches .bat files.

To sync only the component you are standing in​

cd libs/firmware && envy sync --subproject

In a superproject, discovery normally walks up to the manifest marked @envy root "true". --subproject stops at the nearest manifest instead, syncing that component's packages into that component's bin directory.

To rebuild from source rather than from the depot​

envy sync --ignore-depot

Or set ENVY_IGNORE_DEPOT=1 in the environment, which is the usual form in CI. Every package rebuilds through its full pipeline instead of downloading from the depot.

For the nightly that only proves a spec has not rotted, use envy install --ignore-depot. It answers the same question without writing anything into the work tree.

To catch a name collision instead of skipping it​

envy sync --strict

Without --strict, a hand-written bin/format that shadows a format product is left in place and skipped. With it, the run fails and names the file. Worth having in CI.

To see why a package rebuilt​

envy --verbose sync
envy --trace=file:/tmp/sync.jsonl sync

--verbose narrates each package's decisions. --trace records the machinery underneath. Both are global flags, so they go before the subcommand.

See also​