Apply Clang Replacement YAML Safely on Linux

You will finish with a repeatable way to apply Clang tooling edits to a C++ tree, inspect the result, and recover if the change is not 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 that is already under version control, and replacement YAML files produced by a Clang-based tool. This command changes source files in place. It does not create a review branch, make a backup, or ask before writing, so make a checkpoint first. 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 may touch more than one source file when the YAML collection contains replacements for several files. If you cannot 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 files left by 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 them. Confirm that the referenced source files belong to this checkout and that the changes are from the tool invocation you intend to run. Do not place an untrusted YAML file in the search root: it can direct edits to files you did not mean to change.

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 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. An exit status of zero means the operation completed; it is not a code review and does not prove that the resulting program builds.

Inspect the diff immediately:

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

Do not run a second pass merely 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 have checked which files the tool used.

4. Format the changed code when required

Formatting is 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. If none is found, the formatter falls back to its configured fallback style. Do not assume that a formatter run uses the style of your editor. For a controlled one-off, choose a preset such as LLVM or provide --style=file:/path/to/format-file. The --style-config option 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 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 choosing an order. Stop and inspect the source, the YAML, and the tool that generated it.

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

The exact diagnostic depends on the replacements. Do not 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 if they are 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 remain in place. That 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 succeeds:

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

This option deletes the descriptions it collects. It is an irreversible filesystem change unless the files are tracked or backed up. Check the file list first and do not use it for a directory containing unrelated YAML. If you need to preserve the descriptions for an audit, leave the option off and move the reviewed files to an explicit archive instead.