Apply Clang Replacement YAML Safely on Linux

clang-apply-replacements-20 rewrites source files in place from YAML another Clang tool generated. There's no backup, no branch and no confirmation prompt, so this guide covers applying the edits, inspecting the result, and recovering if it wasn't what you expected. The examples use clang-apply-replacements-20 20.1.8 from the Debian clang-tools-20 package installed on this machine.

Allow 15 to 20 minutes. You need a shell, a working copy already under version control, and replacement YAML files produced by a Clang-based tool. Do not run it as root.

1. Make a reversible checkpoint

Start in the repository containing the files to change. Check the working tree, then create a branch or commit for the current state. A branch is usually the least disruptive option:

$ cd /path/to/project
$ git status --short
$ git switch -c apply-clang-replacements
$ clang-apply-replacements-20 --version
clang-apply-replacements version 20.1.8

Keep unrelated edits out of this run. The command can touch more than one source file when the YAML collection holds replacements for several files. If you can't use version control, copy the whole working tree to a separate location before continuing.

2. Inspect the replacement files

Clang tools commonly write YAML change descriptions containing a source path, byte offsets, lengths and replacement text. The search-root argument tells clang-apply-replacements-20 where to look for those descriptions. Treat every file below that directory as input to this operation, including anything left over from an earlier run.

$ find /path/to/project -type f \( -name '*.yaml' -o -name '*.yml' \) -print
$ sed -n '1,120p' /path/to/project/path/to/change.yaml

Read the paths and replacement ranges before applying anything. Confirm the referenced source files belong to this checkout and that the changes came from the tool invocation you intend to run. Never place an untrusted YAML file in the search root: it can direct edits to files you never meant to touch.

A minimal description has this shape:

---
MainSourceFile: /path/to/project/src/example.cpp
Replacements:
- FilePath: /path/to/project/src/example.cpp
  Offset: 20
  Length: 1
  ReplacementText: "1"

Offsets and lengths are byte positions used by the Clang replacement format, not line and column numbers. Never adjust them by eye after editing the source. Regenerate the description instead if the source has changed since the tool produced it.

3. Apply the collected changes

Run the command with the directory that contains the replacement files, or a parent directory when the descriptions are arranged below it:

$ clang-apply-replacements-20 /path/to/project
$ git status --short
 M src/example.cpp

The program merges compatible replacements, applies them to the referenced files, and returns to the shell. A zero exit status means the operation completed; it is not a code review and it does not prove the resulting program builds.

Inspect the diff immediately:

$ git diff --check
$ git diff -- src/example.cpp
$ git diff --stat

Don't run a second pass just because the first one succeeded. A second pass can consume another set of descriptions or repeat a generated change. Remove or archive input files only after you've checked which files the tool actually used.

4. Format the changed code when required

Formatting stays off unless you pass --format. With that option, use a named preset, a repository configuration, or an explicit format file:

$ clang-apply-replacements-20 \
    --format \
    --style=file \
    /path/to/project
$ git diff --check

--style=file is the default style selection. It searches for a .clang-format file in a parent directory of the source file, and falls back to its configured fallback style if none is found. Don't assume a formatter run uses your editor's style. For a controlled one-off, choose a preset such as LLVM or provide --style=file:/path/to/format-file. --style-config supplies the directory containing the configuration used by --style=file.

Formatting is another source of diff noise. Apply replacements first without formatting when you need to review only the semantic edits, then run the project's normal formatter as a separate, visible decision. If the project requires formatting in the same operation, record that choice in the review.

5. Handle conflicts without hiding them

Overlapping or order-dependent insertions can conflict. The normal behaviour reports the problem instead of silently picking an order, so stop and inspect the source, the YAML, and whatever tool generated it.

$ clang-apply-replacements-20 /path/to/project
error: ...
$ git status --short
$ git diff

The exact diagnostic depends on the replacements involved. Don't treat --ignore-insert-conflict as a general repair switch: it tells the tool to ignore an insertion conflict and continue, which can produce a result that needs manual correction. Use it only when you understand the competing insertions and will review the complete diff.

If the result is wrong, discard only this checkpoint's changes when they're isolated:

$ git diff --name-only
$ git restore -- src/example.cpp
$ git status --short

6. Remove change descriptions only after review

By default, the YAML descriptions stay in place, which is useful while diagnosing a failed run, but it also means a later invocation can see them again. Once the source diff has passed review and tests, you can ask the tool to remove its change descriptions regardless of whether merging or replacement succeeded:

$ clang-apply-replacements-20 \
    --remove-change-desc-files \
    /path/to/project
$ git status --short

This option deletes the descriptions it collects. It's an irreversible filesystem change unless the files are tracked or backed up. Check the file list first, and never use it on a directory holding unrelated YAML. To preserve the descriptions for an audit, leave the option off and move the reviewed files to an explicit archive instead.