Concept: Affected Workspaces#

Overview#

The idea of an affected workspace is simply a workspace that can be considered meaningfully changed.

If one can determine which workspaces are affected by some code change, that can be helpful for orchestrating DevOps tasks, such as running builds for only those changed workspaces.

What is considered a meaningful change?#

By default, a workspace is considered to have a set of inputs, the sources of potential chang to a workspace.

When not configured, the default inputs are:

• All git-trackable files in the workspace's directory
• All workspace dependencies. If a workspace dependency is affected for any reason, its dependents are also considered affected.
• The version resolved in bun.lock for all other dependencies in a workspace's package.json.

Inputs can be configured per script as well. See the inputs page for more information.

How is an affected workspace determined?#

There are two main ways to determine affected workspaces:

Using git diff (default)#

The default behavior of affected features is to use the git diff between the current HEAD and the default base ref in git.

The default base ref is main except when overridden via root configuration or an environment variable.

Uncommitted changes (staged, unstaged, untracked) are considered a part of the diff by default. Files that are gitignored are never considered a part of the diff.

# Uses diff of current HEAD against the default base ref (main when not configured)
bw ls-affected

# Compare specific refs (can also pass commit SHA, tag, etc.)
bw ls-affected --base=my-branch-a --head=my-branch-b

# Ignore uncommitted changes
bw ls-affected --ignore-uncommitted # (staged, unstaged and untracked)
bw ls-affected --ignore-untracked
bw ls-affected --ignore-unstaged
bw ls-affected --ignore-staged

# Ignore changes to workspace dependencies derived from package.json files
bw ls-affected --ignore-workspace-deps

# Ignore changes to external dependencies (e.g. npm packages)
bw ls-affected --ignore-external-deps

# Run script across affected workspaces with similar options
bw run-affected my-script --base=my-branch --ignore-uncommitted

• See CLI docs for list-affected/ls-affected.
• See CLI docs for run-affected.

Using a list of changed files#

You can bypass using git entirely and simply pass a list of changed files that match inputs.

bw ls-affected --files="packages/example/**/*.ts packages/example/my-file.json"

# Paths with leading / are relative to the project root
bw run-affected --files="/tsconfig.json packages/example/**/*.ts"

Debugging#

You can use the --explain flag to get detailed reasoning for the affected workspaces.

# Summary for each affected workspaces
bw ls-affected --explain

# More detailed output about every changed file and dependency
bw ls-affected --explain --detailed

API features#

The API and CLI have practical parity for affected features.

• FileSystemProject.determineAffectedWorkspaces()
• FileSystemProject.runAffectedWorkspaceScript()