aspect format - Aspect Build

Rosetta’s format task (Workflows 5.x) ran a rules_lint format_multirun target against changed files, archived a diff, and surfaced an annotation if the formatter modified anything. aspect format replaces it. aspect format builds your formatter target, determines the changed file set, and runs the formatter against it. Formatters edit files in place. Whether modified files fail the step is set by --severity: the default auto fails on CI and only reports off CI.

What changed

Area	YAML-configured tasks	Aspect CLI tasks
Invocation	`bazel format` (legacy Aspect CLI command)	`aspect format`
Formatter target	`target:` (default `//:format`)	`--formatter-target` (default `//tools/format`)
Scope	`format_changed: true` formats changed files only	`--scope=changed` (default) formats changed files only; pass `--scope=all` for every file the formatter handles
Changed-file detection	Local `git diff-tree` / `git diff-index` against the head commit, with a GitHub PR Files API fallback	Local `git diff <merge-base>` by default; GitHub PR Files API as fallback when `git diff` can’t resolve the diff base (on a PR + authenticated)
Detection	Checked `git diff` after the formatter to detect “formatting required”	`aspect format` snapshots the tree pre-run via `git stash create`, then diffs against that snapshot: non-destructive, and unaffected by a pre-existing dirty tree
Diff archival	Archived to artifacts, plus a CI annotation pointing to it	`--upload-format-diff` (on by default) uploads the patch as a CI artifact via the same uploader build/test use; download URL is recorded on `ArtifactsTrait.artifact_urls["format_diff"]`
Soft-fail	`soft_fail: true` downgraded the failure to a warning	`--severity=warn`: the status is a warning and the task exits 0 instead of failing. The default, `auto`, is `fail` on CI and `info` off it. The formatter binary’s own non-zero exit still fails the task regardless
Workspaces	`respect_workspaces: true` filtered changed files to the current workspace	`--exclude-pattern='nested/**'` (or in `.aspect/config.axl`) filters nested Bazel workspaces. Combine with `cd <dir>` in CI when you want different formatter targets per workspace
Ignore patterns	`ignore_patterns: [glob, …]` excluded matching files from the diff outcome	`--exclude-pattern` (repeatable): same effect, plus also drops the matched files from the formatter’s input in changed-files mode so it never runs on them. Pattern syntax: ``, `*`, `?`; case-sensitive

Configuration

Most settings below can be applied either way:

CLI flag: pass the flag at invocation time (e.g. aspect format --scope=all //...). Good for overrides on individual task invocations, or experimenting with a setting before committing it.
.aspect/config.axl: declare it once in your repo’s AXL config so every aspect format invocation picks it up. Good for settings that should apply to all invocations of a task type.

Pick whichever fits; you only need one. Where both work, the sections below show them side-by-side under After.

Formatter target

Before: .aspect/workflows/config.yaml:

tasks:
  format:
    target: //:format

After: CLI flag or config.axl (only needed if your formatter target isn’t at the new default //tools/format):

aspect format --formatter-target=//:format

def config(ctx: ConfigContext):
    ctx.tasks["format"].args.formatter_target = "//:format"

The default formatter target moved from //:format to //tools/format. Putting format_multirun in a sibling package keeps its load(…) out of your root BUILD.bazel, so commands that touch the root package don’t fetch and analyze format-only machinery.If your formatter still lives at the root, set —formatter-target=//:format (or pin it in config.axl). Repos that already have their formatter at //tools/format don’t need to set the flag at all.

Scope: changed files vs. the whole tree

Before: .aspect/workflows/config.yaml:

tasks:
  format:
    format_changed: true   # default

After: default behavior already formats changed files only. Pass --scope=all to run on every file the formatter handles:

aspect format                     # --scope=changed (default)
aspect format --scope=all //...   # every file the formatter knows how to handle

aspect format detects changed files in this order:

Local git diff <merge-base>: the default. With no --base-ref, the base is the CI host’s PR or MR target branch (GITHUB_BASE_REF, BUILDKITE_PULL_REQUEST_BASE_BRANCH, CI_MERGE_REQUEST_TARGET_BRANCH_NAME), then the remote’s default branch, then origin/main. Override with --base-ref, or pass an explicit --merge-base=<sha>.
GitHub PR Files API: fallback when git diff can’t resolve the diff base (shallow clones, fetch-depth-restricted runners), on a PR with the Aspect Workflows GitHub App authenticated.

Detection: when does `aspect format` decide formatting is required?

Most rules_lint formatters rewrite files in place and exit 0 even when they made changes. So “did the formatter exit non-zero?” isn’t a useful signal. aspect format instead takes a tree snapshot before running the formatter, then diffs against that snapshot afterward:

pre_snap = git stash create        # SHA, or "" if working tree was clean
run formatter
formatter_diff = git diff <pre_snap | HEAD>
if formatter_diff is non-empty:
    formatting required → fail (or warn under --severity=warn)

git stash create is non-destructive: it writes a commit object to the object store and returns its SHA without touching the working tree, the index, or the stash list. As a result, the detection works on a dirty local clone: any pre-existing changes are absorbed into the snapshot and don’t false-positive as “formatter modified”.

Soft-fail

Before: .aspect/workflows/config.yaml:

tasks:
  format:
    soft_fail: true

After: --severity=warn (default auto, which is fail on CI and info off it):

aspect format --severity=warn

def config(ctx: ConfigContext):
    ctx.tasks["format"].args.severity = "warn"

With --severity=warn, when the formatter modified files the task reports a warning status and exits 0. --severity=info passes outright. The formatter binary’s own non-zero exit (e.g. config error) still fails the task regardless.

Diff archival

Before: .aspect/workflows/config.yaml: the legacy task auto-archived format.diff as a CI artifact and pointed an annotation at it. After: --upload-format-diff, on by default:

aspect format --upload-format-diff

def config(ctx: ConfigContext):
    ctx.tasks["format"].args.upload_format_diff = True

When the formatter modified files, the task writes the diff to a job-scoped tmpfile and uploads it as format.patch via the same uploader build/test use for testlogs. Works on GitHub Actions, Buildkite, CircleCI, and GitLab. Turn it off with --upload-format-diff=false. No-op when the working tree is clean post-format, or when not running on a recognized CI host.

Ignore patterns / workspace awareness

The legacy ignore_patterns: [glob, …] excluded matching files from the diff outcome; respect_workspaces: true filtered changed files to the current Bazel workspace. Both map to --exclude-pattern in the new task:

aspect format \
  --exclude-pattern='vendor/**' \
  --exclude-pattern='**/*.generated.go' \
  --exclude-pattern='nested-bazel-workspace/**'

def config(ctx: ConfigContext):
    ctx.tasks["format"].args.exclude_patterns = [
        "vendor/**",
        "**/*.generated.go",
        "nested-bazel-workspace/**",
    ]

Pattern syntax: * (one segment), ** (zero or more segments), ? (one char). Patterns are case-sensitive and matched against repo-relative file paths. In --scope=changed (default), ignored paths are dropped from the file list passed to the formatter, so it never runs on them. In --scope=all, the formatter walks the tree itself, so ignored files may still be rewritten on disk; ignored paths are excluded only from the post-format diff used to decide whether the task fails. The legacy format task had the same constraint: ignore_patterns filtered the failure-decision diff but couldn’t stop the formatter from rewriting files it discovered itself. If you need a hard guarantee the formatter never touches a directory in --scope=all, configure exclusion at the formatter level too (most rules_lint helpers accept include/exclude lists).

The “nested Bazel workspace” case (where aspect format from the parent would otherwise stomp the child’s files) is a common motivator for —exclude-pattern. List each nested workspace’s directory and the parent’s formatter leaves them untouched.

Other flags with no Rosetta equivalent

Flag	What it does
`--include-pattern`	The allowlist counterpart of `--exclude-pattern`: only matching paths are formatted
`--formatter-arg`	An extra argument passed to the formatter target on every invocation. Repeat the flag
`--formatter-arg-for-tree-walk`	The same, but only on a whole-tree run, where the formatter walks the tree itself rather than receiving a file list
`--run-in`	The directory to run the formatter from, when it resolves paths relative to its own working directory

aspect buildifier builds its recipe out of these.

Examples

Standard format check on PRs

Before: .aspect/workflows/config.yaml:

tasks:
  format:
    target: //tools/format
    format_changed: true

After: CI configuration:

on:
  pull_request:
    branches: [main]

jobs:
  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Format
        run: aspect format --task:name format

steps:
  - label: ":hammer_and_wrench: Format"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect format --task:name format
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

format:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - aspect format --task:name format
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  format:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Format
          command: aspect format --task:name format

workflows:
  ci:
    jobs:
      - format
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

Soft-fail (annotate but don’t fail)

For teams introducing automated formatting incrementally, downgrade the failure to a warning so the CI step doesn’t block merges:

jobs:
  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Format (soft-fail)
        run: aspect format --task:name format --severity=warn

steps:
  - label: ":hammer_and_wrench: Format (soft-fail)"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect format --task:name format --severity=warn
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

format:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - aspect format --task:name format --severity=warn
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  format:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Format (soft-fail)
          command: aspect format --task:name format --severity=warn

workflows:
  ci:
    jobs:
      - format
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

Format the whole tree (`--scope=all`)

Useful for nightly maintenance jobs or when bringing a new formatter into a repo for the first time:

aspect format --task:name format-all --scope=all //...

Archive the diff as a CI artifact (`--upload-format-diff`)

--upload-format-diff writes the formatter’s patch to a tmpfile and uploads it as format.patch via the same uploader build/test use, so reviewers can apply it locally without re-running the formatter:

jobs:
  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Format
        run: aspect format --task:name format --upload-format-diff

steps:
  - label: ":hammer_and_wrench: Format"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect format --task:name format --upload-format-diff
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

format:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  script:
    - aspect format --task:name format --upload-format-diff
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  format:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          command: aspect format --task:name format --upload-format-diff
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

​What changed

​Configuration

​Formatter target

​Scope: changed files vs. the whole tree

​Detection: when does aspect format decide formatting is required?

​Soft-fail

​Diff archival

​Ignore patterns / workspace awareness

​Other flags with no Rosetta equivalent

​Examples

​Standard format check on PRs

​Soft-fail (annotate but don’t fail)

​Format the whole tree (--scope=all)

​Archive the diff as a CI artifact (--upload-format-diff)

What changed

Configuration

Formatter target

Scope: changed files vs. the whole tree

Detection: when does `aspect format` decide formatting is required?

Soft-fail

Diff archival

Ignore patterns / workspace awareness

Other flags with no Rosetta equivalent

Examples

Standard format check on PRs

Soft-fail (annotate but don’t fail)

Format the whole tree (`--scope=all`)

Archive the diff as a CI artifact (`--upload-format-diff`)