Configuring Restyled

The restyling process can be configured through a YAML file committed in your repository. Restyled will use the first file found at any of the following locations:

• .restyled.yaml
• .restyled.yml
• .github/restyled.yaml
• .github/restyled.yml

The contents of that file are documented here. The current default configuration is available here. Any differences or additional notes in that source file take precedence over what's described in this wiki page. When referring to the file, we use .restyled.yaml -- but of course this documentation applies regardless of location.

The .restyled.yaml in the branch being Restyled is what is used. If you make a configuration change on another branch (e.g. main), you will need to bring that change into any open Pull Requests (e.g. rebase) before Restyled will see it there.

General notes

• All keys are optional and default values begin each section below
• All list values can also be given a single value, to indicate a single-element list.

Core Configuration

Enabled

enabled: true

Do anything at all?

Exclude

exclude:
  - "**/*.patch"
  - "**/node_modules/**/*"
  - "**/vendor/**/*"
  - ".github/workflows/**/*"

Patterns to exclude from all Restylers.

By default, we ignore directories that are often checked-in but rarely represent project code. Some globs are slightly complicated to match paths within directories of names appearing at any depth.

This behavior can be disabled in your project with:

exclude: []

Also Exclude

If you wish to exclude patterns while retaining our default exclude, add them to also_exclude instead.

also_exclude: []

Changed paths

changed_paths:
  maximum: 1000
  outcome: error

Pull Requests with too many changed paths will not be restyled. The limit is controlled by the maximum key and outcome can either be error or skip.

Remote files

remote_files: []

Files to download before restyling.

Example:

remote_files:
  - url: https://raw.github.com/.../hlint.yaml
    path: .hlint.yaml

If omitted, path is the basename of url.

Restyling Outcomes

Auto

auto: false

Push the restyled commits directly to the original PR.

Commit Template

commit_template: |
  Restyled by ${restyler.name}

Control the commit messages used when Restyler makes fixes. Supports limited interpolation, currently just ${restyler.name}.

Pull Requests

pull_requests: true

Open Restyle PRs?

Comments

comments: false

🗑️ This feature was removed and this option no longer has any effect.

Pull Request Statuses

statuses:
  skipped: true         # Green when skipped
  differences: true     # Red when style differences are found
  no_differences: true  # Green when no differences are found

A single value can be used to disable/enable all:

statuses: false

Or separate values as shown in the defaults.

Note that PR statuses are always sent on errors. This is because errors may occur (and are always handled) outside of the repository clone operation, so we are unable to use the in-repository configuration from this logic.

Review requests

request_review: none

Possible values:

• author: From the author of the original PR
• owner: From the owner of the base repository
• none: Don't
• {any text}: From this GitHub user or team name

One value will apply to both origin and forked PRs:

request_review: author

Or you can specify separate values. If you specify only one, the other is defaulted as shown:

request_review:
  origin: author
  forked: none

Therefore,

request_review: {}

Is a method to opt into review-requests but with default choices about from who.

Labels

labels: []

Labels to add to any created Restyle PRs.

These can be used to tell other automation to avoid our PRs.

Example:

labels:
  - pullassigner-ignore

⚠️ Labels may not always be respected.

Ignore Authors

ignore_authors:
  - "*[bot]"

Authors to ignore, supports globs.

PRs opened by authors whose login matches any patterns will be ignored by Restyled.

Ignore Branches

ignore_branches:
  - "renovate/*"

Branches to ignore, supports globs.

PRs whose head branches match any patterns will be ignored by Restyled.

Ignore labels

ignore_labels:
  - restyled-ignore

Labels to ignore, supports globs.

PRs labels match any patterns will be ignored by Restyled.

⚠️ Labels may not always be respected.

Restylers

Restylers version

restylers_version: stable

Version of the set of Restylers to run.

This name corresponds to a manifest at (e.g.) https://docs.restyled.io/data-files/restylers/manifests/stable/restylers.yaml. Feel free to specify dev to get new versions more quickly, but stable does not lag far behind.

Restylers

restylers:
  - "*"

Restylers to run, and how

Elements in this list can be specified in one of three forms:

1. A string, which means to run that Restyler with all defaults

   restylers:
     - prettier

2. A single key, that is a name, and override object as the value:

   restylers:
     - prettier:
         include:
           - "**/*.js"

3. An object with a name key

   restylers:
     - name: prettier
       include:
         - "**/*.js"

All three of the above are equivalent. The latter two are useful if you want to run the same Restyler multiple ways:

restylers:
  - name: prettier
    arguments: ["--one-thing"]
    include: ["needs-one-thing/**/*.js"]

  - name: prettier
    arguments: ["--another"]
    include: ["needs-another/**/*.js"]

Omitted keys inherit defaults for the Restyler of that name, which can be seen in Available Restylers.

Note that the enabled key is not inherited. Adding an item to this list, without specifying enabled: false, automatically enables that Restyler.

In string form, prefixing the name with ! is short-hand for disabling. The following two configurations are equivalent:

restylers:
  - "!astyle"  # quoting is required for this
  - astyle:
      enabled: false

Wildcard

The special value * (wildcard) means all Restylers not configured. One wildcard may be placed anywhere in the restylers list and remaining Restylers will be run, with their default values, at that point.

Note that the Restylers added by the * entry will not run if they're default configuration includes enabled: false. You must explicitly add such Restylers for them to run.

Examples:

• Just run all Restylers with default values, i.e. the default configuration value

  restylers:
    - "*"

• Enable jdt, and run all others after

  restylers:
    - jdt
    - "*"

• Enable jdt, and run it after all others

  restylers:
    - "*"
    - jdt

• Ensure stylish-haskell runs before brittany, and before all others

  restylers:
    - stylish-haskell
    - brittany
    - "*"

• Run only clang-format

  restylers:
    - clang-format

• Run clang-format, astyle, everything else, then clang-format again with different options

  restylers:
    - clang-format
    - astyle
    - "*"
    - clang-format:
        arguments: ["--special"]
        include:
          - "special/**/*.cs"

• Disable the astyle Restyler, maintaining all other defaults

  restylers:
    - "!astyle"
    - "*"

Restyler Override

Valid keys in the override object are:

• enabled: true|false

  Restylers present in the list are considered enabled and those not in the list are considered not enabled, however this key is an explicit way to disable a Restyler without removing it from the list (e.g. temporarily).

• arguments: string or array of string

  Any additional argument(s) to pass to the restyling command.

• include: pattern or array of pattern

  Pattern(s) to match files that should be Restyled.

  NOTE: these are processed in order, so be careful you don't accidentally do something like:

  - "!/bad-file.hs"
  - "**/*.hs"

  which says to exclude bad-file.hs, then immediately re-includes it via the wildcard.

• interpreters: interpreter or array of interpreters

  Extension-less files will be Restyled if they match interpreter(s) given here. Valid values are sh, bash, python, and ruby.

• image: string|object

  The Docker image to run. Can be anything publicly pull-able. This can be a full image, or you can override individual parts.

  restylers:
    - clang-format:
        image: ghcr.io/my-org/clang-format:edge
  
    - clang-format:
        # these are the available keys, multiple can be given, all
        # are optional with defaults coming from the manifest
        registry: restyled
        name: restyler-clang-format
        tag: v16.0.1
  
    - clang-format:
        # equivalent to restyled/restyler-clang-format:v16
        image:
          tag: v16

  See Restyler Versions for more details about so-called "series images", such as the v16 tag shown above.

• command: string or array of string

  The command (and any required argument(s)) to perform the Restyling.