mix workspace.list (Workspace v0.3.2)

Shows workspace project info

$ mix workspace.list

By default the following are displayed:

• the project app name
• the project path with respect to workspace path
• the description if set
• the project tags

Command line options

• --format (string) - The output format of the list. It can be one of the following:
  • json - pretty prints the list as a json.
  • pretty - pretty prints the list. Allowed values: ["json", "pretty"]. [default: "pretty"]

Workspace status options

Status is retrieved from the diff between the given --base and --head. Knowing the changed files we can limit the execution of workspace commands only to relevant projects.

• -a, --affected (boolean) - Run only on affected projects [default: false]
• --base (string) - The base git reference to compare the head to. Applied only when --affected or --modified are set.
• --head (string) - A reference to the git head. Applied only if --base is set for getting the changed files [default: "HEAD"]
• -m, --modified (boolean) - Run only on modified projects [default: false]

Filtering options

• --dependency (string) - If set, only projects that have the given dependency will be considered.
• --dependent (string) - If set, only projects that are dependencies of the given project are considered.
• -e, --exclude... (string) - Ignore the given projects [values can be grouped with the , separator]
• --exclude-tag... (string) - If set, any projects with any of the given tag(s) will be excluded. For scoped tags you should provide a colon separated string (examples: shared, scope:api, type:utils). For selecting a specific tag use --tag [values can be grouped with the , separator]
• -i, --include... (string) - Always include the given projects, even if they were filtered out by other flags. Acts as a union with the filtered results. Note that :exclude has highest priority. [values can be grouped with the , separator]
• --maintainer (string) - Search for projects with the given maintainer. A partial case insensitive string search is performed so you can provide only part of the maintainer's name.
• --path... (string) - A path under which projects will be considered. Paths should be relative with respect to the workspace root. All other projects can be ignored. Can be set multiple times.
• -p, --project... (string) - The project name, can be defined multiple times. If not set all projects are considered [values can be grouped with the , separator]
• --recursive (boolean) - If set, when used with --dependency or --dependent, it will consider all transitive dependencies instead of just first-level ones. [default: false]
• --tag... (string) - If set, only projects with the given tag(s) will be considered. For scoped tags you should provide a colon separated string (examples: shared, scope:api, type:utils). For excluding a specific tag use --exclude-tag [values can be grouped with the , separator]

Display options

• --show-status (boolean) - If set the status of each project will be included in the output graph [default: false]

Export options

• --json (boolean) - DEPRECATED Use --format json with --output instead. If set a json file will be generated with the list of workspace projects and associated metadata. By default it will be saved in workspace.json in the current directory. You can override the output path by setting the --output option. [default: false]
• --output (string) - Save the list to a file. Applicable only if --format is set to json.
• --relative-paths (boolean) - If set the paths in the exported json file will be relative with respect to the workspace path. Applicable only if --format is set to json. [default: false]

Global workspace options

• --config-path (string) - The path to the workspace config to be used, relative to the workspace path [default: ".workspace.exs"]
• --workspace-path (string) - If set it specifies the root workspace path, defaults to current directory

Filtering projects

Several command line options can limit the returned projects and filter the workspace.

You can list only projects with a specific tag:

$ mix workspace.list --tag core

Or exclude projects with a specific tag:

$ mix workspace.list --exclude-tag deprecated

If your monorepo has a nested structure you can list projects only under one or more specific paths.

$ mix workspace.list --path packages/shared --path packages/infra

In large monorepos you may want to get all projects depending on a specific package. You can achieve this through the --dependency option:

$ mix workspace.list --dependency foo

Additionally you can specify the --dependent flag to consider only dependencies of a given project:

$ mix workspace.list --dependent foo

By default, both --dependency and --dependent consider only direct (first-level) dependencies. You can use the --recursive flag to include all transitive dependencies:

# Get all projects that transitively depend on foo (direct and indirect)
$ mix workspace.list --dependency foo --recursive

# Get all transitive dependencies of foo (direct and indirect)
$ mix workspace.list --dependent foo --recursive

You can also filter by the project's maintainer. The search is case insensitive. The maintainers are expected to be defined under package:

def project do
  [
    package: [
      maintainers: ["Jack Sparrow"]
    ],
    # rest project options
  ]

In order to get all projects associated with a specific maintainer:

$ mix workspace.list --maintainer "Jack Sparrow"

# notice that the search is case insensitive, this works as well
$ mix workspace.list --maintainer sparrow

Using --include for union operations

The --include option allows you to add projects back to the filtered set, even if they were filtered out by other flags. This is useful when you want to combine filtering logic with specific additions.

# Get all dependencies of 'my_api' plus the project itself
$ mix workspace.list --dependent my_api --include my_api >   --relative-paths --format json --output projects.json

# Generate a VS Code workspace file
$ jq '{folders: [.projects[] | {path: .path}]}' projects.json > my_api.code-workspace

# Open the focused workspace in VS Code
$ code my_api.code-workspace