f8/tools/fx/cmd/multi.md

# fx multi

Run an `fx` command across multiple build directories.

```none
Usage: fx multi [add | list | remove | rm | save FILE | use FILE]
       fx multi [[-p | --parallel] | [-f | --fail]] COMMAND ...
       fx multi set {PRODUCT.BOARD | SPEC}... [SWITCHES...]

fx multi maintains lists of build directories and runs fx commands
across multiple builds in sequence.

The first form uses subcommands that maintain the current multi list:

  add                   Adds the current build to the multi list.
                        e.g. `fx --dir out/foo multi add`
                        If the directory is already present, rotates it
                        to the end of the list.

  clear                 Resets the current multi list to empty.

  list                  Displays the current multi list.
                        Just `fx multi` does this too.

  remove [-f] | rm [-f] Removes the current build from the multi list.
                        With -f it's not an error if it's not in the list.

  save FILE             Saves the multi list in FILE.

  use FILE              Resets the multi list to the one saved in FILE.

The second form runs any other `fx` subcommand you like, several times.
For each build in the multi list, it runs `fx --dir <build-dir> COMMAND ...`
With `--fail` (or `-f`), `fx multi` exits as soon as one COMMAND fails.
By default, it runs each one in sequence even if the previous one failed.
At the end it reports which ones failed.
With `--parallel` (or `-p`), `fx multi` executes COMMAND on all directories
in parallel. Fail and parallel are mutually exclusive.

The third form resets the multi list to empty and then runs several `fx set`
commands, adding each new build dir to the multi list (if it succeeded).
It's like running `fx multi clear` and then a series of:

  fx set PRODUCT.BOARD --auto-dir SWITCHES... && fx multi add

Arguments before SWITCHES... can be explicit PRODUCT.BOARD or can be
one of a fixed set of SPEC strings.  Run `fx multi set` alone to see
the set of available SPEC strings.  Each string corresponds to a list
of PRODUCT.BOARD + FIXED_SWITCHES... combinations.  The FIXED_SWITCHES...
are prepended to any SWITCHES... on the `fx multi set` command line.

```

[multi source code](https://cs.opensource.google/fuchsia/fuchsia/+/main:tools/devshell/multi)