如何让clang-format忽略Jinja模板的{{ ... }}和{% .. %}语法？

问题背景 #

我在参与一个大型项目，里面有很多生成C++文件的Jinja模板。用clang-format格式化这些模板时，工具会把Jinja的{{ ... }}标记拆得七零八落，比如原本的代码：

{{NAMESPACE | join("::")}}::{{CLASSNAME}}     {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_particlesThatCanNotBeLiftedWithinTheirTree;
{{NAMESPACE | join("::")}}::{{CLASSNAME}}     {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_particlesThatHaveToBeSieved;

int {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_numberOfLifts                        = 0;
int {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_numberOfDrops                        = 0;
int {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_numberOfSieves                       = 0;
int {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_numberOfReassignments                = 0;
int {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_numberOfAssignmentsToGlobalSieve     = 0;

会被格式化成这样，直接导致Jinja模板失效：

{
  { NAMESPACE | join("::") }
}
::{{CLASSNAME}} {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_particlesThatCanNotBeLiftedWithinTheirTree;
{
  { NAMESPACE | join("::") }
}
::{{CLASSNAME}} {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_particlesThatHaveToBeSieved;


int {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_numberOfLifts = 0;
int {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_numberOfDrops = 0;
int {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_numberOfSieves = 0;
int {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_numberOfReassignments = 0;
int {
  { NAMESPACE | join("::") }
}
::{
  { CLASSNAME }
}
::_numberOfAssignmentsToGlobalSieve = 0;

下面是几种实用的解决方法：

解决方案 #

1. 全局配置：用RawStringFormats保护Jinja标记 #

在项目的.clang-format配置文件中添加以下内容，让clang-format把{{和}}包裹的内容当作不可格式化的原始文本：

RawStringFormats:
  - Language: Cpp
    Delimiters:
      - '{{'
      - '}}'
      - '{%'
      - '%}'
    CanonicalDelimiter: ''
    # 替换成你项目实际使用的代码风格，比如llvm、google等
    BasedOnStyle: google

这段配置会全局生效，一次性解决所有Jinja标记被破坏的问题，适合整个项目的模板文件。

2. 局部保护：用注释跳过格式化 #

如果只是个别代码片段需要保留Jinja结构，可以用clang-format的注释标记临时关闭格式化：

// clang-format off
{{NAMESPACE | join("::")}}::{{CLASSNAME}}     {{NAMESPACE | join("::")}}::{{CLASSNAME}}::_particlesThatCanNotBeLiftedWithinTheirTree;
// clang-format on

// clang-format off和// clang-format on之间的代码会完全保留原样，适合零散的模板片段，但大型项目中逐个添加注释效率较低。

3. 预处理占位符（适合自动化流程） #

编写简单脚本，先把Jinja标记替换为合法的C++占位符（比如将{{NAMESPACE | join("::")}}替换成NS_PLACEHOLDER），对替换后的文件执行clang-format，最后再把占位符换回原来的Jinja语法。

这种方式需要额外的脚本支持，但能确保C++代码被正确格式化，同时Jinja结构丝毫不差，适合集成到CI/CD流程中。

4. 调整大括号解析规则（效果有限） #

在.clang-format中设置BreakBeforeBraces: Attach，减少clang-format对大括号的换行拆分：

BreakBeforeBraces: Attach

但这种方法只能缓解部分问题，无法完全避免Jinja标记被破坏，优先级低于前三种方法。

内容的提问来源于stack exchange，提问作者mivkov