pacwichpacwich
v0.1.0-test.2

    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 your package manager's lockfile 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 project 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)
pacwich ls-affected

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

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

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

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

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

    Using a list of changed files

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

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

# Paths with leading / are relative to the project root
pacwich 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
pacwich ls-affected --explain

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

    API features

    The API and CLI have practical parity for affected features.