brave-core/docs/plaster.md

🩹 Plaster and semantical patching

Plaster is an experimental tool being introduced in Brave to allow us to apply changes to upstream sources files, by relying on regex transformations to search for patterns and apply substitutions.

Why 🩹 Plaster

The two traditional approaches to introduce changes to Chromium have been git patches (i.e. patches/), and language overrides (i.e. chromium_src/). The use of patches is in general avoided whenever possible, as they tend to easily run into conflicts when rebasing Brave onto a newer Chromium version. With language overrides, although more flexible than patches, they tend to be invisible in the source code target, hard to interpret, and lead to many cases of unintended replacements.

Using regexes, Plaster avoids the brittleness of patch files, while providing matching mechanisms that are more flexible than the methods currently employed for macro replacement. This also means a language-agnostic way to approach source changes semantically, and in place. Plaster changes can be both seen in place, as well as audited as patch files.

How does it work

Plaster files are placed under rewrite/, using a .yaml extension, and they are supposed to match the path for the file being plastered. A deprecated .toml form is also accepted while existing plasters are being migrated — see Legacy TOML format (deprecated) at the end of this document.

Warning

At the moment, only plaster files to sources in Chromium's src repo are supported.

Each plaster file will be used to apply changes into a given source, and then generate a patch for the effected changes.

For example, imagine you want to append Brave-specific entries to the upstream RequestType enum in components/permissions/request_type.h. You would care about the following files.

• Plaster file: brave/rewrite/components/permissions/request_type.h.yaml
• Source file: components/permissions/request_type.h
• Patch file: brave/patches/components-permissions-request_type.h.patch

Creating a plaster file

A plaster file is a YAML file that lists regex operations to be applied to the corresponding source, based on its path. The following plaster appends Brave-specific values to the upstream RequestType enum.

Creating the source file with vscode:

code rewrite/components/permissions/request_type.h.yaml

We can use a regex that anchors on the enum's outer braces and on the existing kMaxValue = <something> line, and then inserts the Brave entries plus a new kMaxValue just before the closing }:

# Copyright (c) 2026 The Brave Authors. All rights reserved.
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this file,
# You can obtain one at https://mozilla.org/MPL/2.0/.

substitutions:
  - description: |
      Append Brave-specific entries to `RequestType`

      This plaster is generic enough to guarantee that our entries are always last,
      and that they also become the new kMaxValue.
    re_pattern: '(enum class RequestType \{.+?,)(\s+)kMaxValue = \w+'
    re_flags: [DOTALL]
    replace: |-
      \1
        kWidevine,
        kBraveEthereum,
        kBraveSolana,
        kBraveOpenAIChat,
        kBraveGoogleSignInPermission,
        kBraveCardano,
        kBraveMinValue = kWidevine,
        kBraveMaxValue = kBraveCardano,
        kMaxValue = kBraveCardano

Plaster substitutions are listed under substitutions:. Plaster loads the contents of a source from git, as the source of truth, not from whatever is on disk, and then it applies each substitution cumulatively to the contents of the target source, updating the upstream source at the end.

Each entry has the following format:

substitutions:
  - description: ''
    # One of either pattern or re_pattern must be specified.
    pattern: '' # non-regex pattern (string will be escaped)
    re_pattern: '' # regex pattern
    replace: ''
    re_flags: [] # traditional Python `re` flag names, e.g. [DOTALL]
    count: 1 # 1 is the default; 0 means no count, not advised.

Use YAML's | / |- block scalars when you need multi-line replace or description values — | keeps a trailing newline, |- strips it. Single-quoted YAML strings preserve backslashes literally, which is useful for regex patterns ('\s' stays as the two characters \s, not interpreted by YAML).

To apply this plaster file, just run plaster.py:

tools/cr/plaster.py apply

Running plaster.py will cause the substitution to be applied in components/permissions/request_type.h, and trigger the creation or update of the corresponding patch file for this source. For example, it may produce a diff file like this:

diff --git a/patches/components-permissions-request_type.h.patch b/patches/components-permissions-request_type.h.patch
new file mode 100644
index 00000000000..bec88027991
--- /dev/null
+++ b/patches/components-permissions-request_type.h.patch
@@ -0,0 +1,20 @@
+diff --git a/components/permissions/request_type.h b/components/permissions/request_type.h
+--- a/components/permissions/request_type.h
++++ b/components/permissions/request_type.h
+@@ -... @@ enum class RequestType {
+   ...,
+   kStorageAccess,
+   kWindowManagement,
+-  kMaxValue = kWindowManagement,
++  kWidevine,
++  kBraveEthereum,
++  kBraveSolana,
++  kBraveOpenAIChat,
++  kBraveGoogleSignInPermission,
++  kBraveCardano,
++  kBraveMinValue = kWidevine,
++  kBraveMaxValue = kBraveCardano,
++  kMaxValue = kBraveCardano,
+ };

So at the end, you get a regular patch, and everything works as usual with how our Brave machinery handles patch files.

Checking if files are up-to-date

You can verify if all plaster files are applied, with Chromium sources updated and patch files checked under path with the following command:

tools/cr/plaster.py check

This is the equivalent of a dry run of plaster.py apply.

Best practices

See https://github.com/brave-experiments/brave-core-tools/blob/master/docs/best-practices/plaster.md

Legacy TOML format (deprecated)

Important

The .toml form is deprecated and kept only so existing plasters keep working until they are migrated. New plasters must use .yaml while the existing .toml ones are migrated. Migration progress is tracked in brave/brave-browser#55738.

Pre-existing plasters under rewrite/ use a .toml file with the same fields as their YAML counterparts, written as TOML array-of-tables:

[[substitution]]
description = ''
re_pattern = ''
pattern = ''
replace = ''
re_flags = []
count = 1