gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/04-indentation.md

Indentation Options

← Prev: Braces | Back to Index | Next: Spacing →

Navigation: Alignment | Breaking | Braces | Indentation | Spacing | Includes | Languages | Comments | Advanced

Control indentation behavior for various code constructs.

Basic Indentation

IndentWidth

Number of columns for each indentation level.

Type: Unsigned Default: 2

IndentWidth: 4

Example:

void function() {
    if (condition) {
        doSomething();
    }
}

UseTab

The way to use tab characters in the resulting file.

Type: UseTabStyle Values:

• Never - Never use tab
• ForIndentation - Use tabs only for indentation
• ForContinuationAndIndentation - Fill all leading whitespace with tabs, and use spaces for alignment that appears within a line (e.g. consecutive assignments and declarations)
• AlignWithSpaces - Use tabs for line continuation and indentation, and spaces for alignment
• Always - Use tabs whenever we need to fill whitespace that spans at least from one tab stop to the next one

Examples:

Never:

void f() {
••••int i;
}

ForIndentation:

void f() {
→   int i;
}

Always:

void f() {
→   int i;
}

TabWidth

Visual width of a tab character.

Type: Unsigned Default: 8

TabWidth: 4

Affects how existing tabs are displayed and formatted.

ContinuationIndentWidth

Indent for line continuations.

Type: Unsigned Default: 4

ContinuationIndentWidth: 4

Example:

int var = function1() +
    function2();

result = longFunction(
    parameter1,
    parameter2);

Access Modifiers

AccessModifierOffset

Offset for access modifiers (public, private, protected).

Type: Integer Default: 0

Negative values indent left, positive values indent right.

Examples:

AccessModifierOffset: -2:

class C {
public:
  void f();
};

AccessModifierOffset: 0:

class C {
  public:
  void f();
};

AccessModifierOffset: 2:

class C {
    public:
  void f();
};

IndentAccessModifiers

Indent access modifiers

.

Type: Boolean Default: false

Example:

true:

class C {
    public:
        void f();
};

false:

class C {
  public:
    void f();
};

Case Labels and Switch

IndentCaseLabels

Indent case labels from switch statement.

Type: Boolean Default: false

Examples:

false:

switch (fool) {
case 1:
  bar();
  break;
default:
  plop();
}

true:

switch (fool) {
  case 1:
    bar();
    break;
  default:
    plop();
}

IndentCaseBlocks

Indent case blocks.

Type: Boolean Default: false

Examples:

false:

switch (fool) {
case 1: {
  bar();
} break;
default: {
  plop();
}
}

true:

switch (fool) {
case 1:
  {
    bar();
  }
  break;
default:
  {
    plop();
  }
}

Preprocessor Directives

PPIndentWidth

Number of columns for preprocessor statement indentation.

Type: Integer Default: -1 (uses IndentWidth)

PPIndentWidth: 1

Example:

#ifdef __linux__
# define FOO
#else
# define BAR
#endif

When set to -1 (default), IndentWidth is used also for preprocessor statements.

IndentPPDirectives

Indent preprocessor directives.

Type: PPDirectiveIndentStyle Values:

• None - Don't indent directives
• AfterHash - Indent after the hash
• BeforeHash - Indent before the hash
• Leave - Leave indentation as-is (ignores PPIndentWidth)

Examples:

None:

#if FOO
#if BAR
#include <foo>
#endif
#endif

AfterHash:

#if FOO
#  if BAR
#    include <foo>
#  endif
#endif

BeforeHash:

#if FOO
  #if BAR
    #include <foo>
  #endif
#endif

Leave:

#if FOO
    #if BAR
#include <foo>
    #endif
#endif

Special Constructs

IndentGotoLabels

Indent goto labels.

Type: Boolean Default: true

Examples:

true:

int f() {
  if (foo()) {
  label1:
    bar();
  }
label2:
  return 1;
}

false:

int f() {
  if (foo()) {
label1:
    bar();
  }
label2:
  return 1;
}

IndentExternBlock

Indent extern blocks.

Type: IndentExternBlockStyle Values:

• AfterExternBlock - Indent after extern
• NoIndent - Don't indent
• Indent - Indent extern block

Examples:

AfterExternBlock:

extern "C" {
void f();
}

extern "C"
{
void g();
}

NoIndent:

extern "C" {
void f();
}

Indent:

extern "C" {
  void f();
}

IndentRequiresClause

Indent C++20 requires clause. This only applies when RequiresClausePosition is OwnLine, OwnLineWithBrace, or WithFollowing.

Type: Boolean

Note: In clang-format 12, 13 and 14 this was named IndentRequires.

Example:

true:

template <typename It>
  requires Iterator<It>
void sort(It begin, It end) {
  //....
}

false:

template <typename It>
requires Iterator<It>
void sort(It begin, It end) {
  //....
}

IndentWrappedFunctionNames

Indent wrapped function names after line break.

Type: Boolean

Example:

true:

LoooooooooooooooooooooooooooooongReturnType
    LoooooooooooooooooooongFunctionDeclaration();

false:

LoooooooooooooooooooooooooooooongReturnType
LoooooooooooooooooooongFunctionDeclaration();

ConstructorInitializerIndentWidth

Indent width for constructor initializers and inheritance lists.

Type: Unsigned Default: Uses IndentWidth

ConstructorInitializerIndentWidth: 2

Example:

Constructor()
  : member1(),
    member2() {}

BracedInitializerIndentWidth

Number of columns to indent braced init list contents.

Type: Integer Default: Uses ContinuationIndentWidth if unset or negative Since: clang-format 17

AlignAfterOpenBracket: AlwaysBreak
BracedInitializerIndentWidth: 2

Example:

void f() {
  SomeClass c{
    "foo",
    "bar",
    "baz",
  };
  auto s = SomeStruct{
    .foo = "foo",
    .bar = "bar",
    .baz = "baz",
  };
  SomeArrayT a[3] = {
    {
      foo,
      bar,
    },
    {
      foo,
      bar,
    },
    SomeArrayT{},
  };
}

Language-Specific

IndentExportBlock

Indent export blocks (JavaScript). If true, clang-format will indent the body of an export { ... } block. This doesn't affect the formatting of anything else related to exported declarations.

Type: Boolean Since: clang-format 20

Example:

true:

export { foo, bar };

false:

export { foo, bar };

ObjCBlockIndentWidth

Number of columns for indentation of ObjC blocks.

Type: Unsigned

ObjCBlockIndentWidth: 4

Example:

[operation setCompletionBlock:^{
    [self onOperationDone];
}];

Common Patterns

Minimal Indentation (2 spaces)

IndentWidth: 2
UseTab: Never
ContinuationIndentWidth: 2
AccessModifierOffset: -2
IndentCaseLabels: false
IndentCaseBlocks: false
IndentGotoLabels: true
IndentPPDirectives: None
IndentWrappedFunctionNames: false

Standard Indentation (4 spaces)

IndentWidth: 4
UseTab: Never
TabWidth: 4
ContinuationIndentWidth: 4
AccessModifierOffset: 0
IndentAccessModifiers: false
IndentCaseLabels: true
IndentCaseBlocks: false
IndentGotoLabels: true
IndentPPDirectives: AfterHash
PPIndentWidth: -1
IndentWrappedFunctionNames: true
BracedInitializerIndentWidth: 4

Tab-Based Indentation

IndentWidth: 4
UseTab: ForIndentation
TabWidth: 4
ContinuationIndentWidth: 4
AccessModifierOffset: -4
IndentCaseLabels: true
IndentPPDirectives: AfterHash

Large Indentation (8 spaces, Linux style)

IndentWidth: 8
UseTab: Always
TabWidth: 8
ContinuationIndentWidth: 8
AccessModifierOffset: -8
IndentCaseLabels: false
IndentGotoLabels: false
IndentPPDirectives: None

Tips

1. Consistency: Use the same indentation throughout your project
2. Tab Width: If using tabs, ensure TabWidth matches team editor settings
3. Continuation: Set ContinuationIndentWidth to help distinguish continuations from blocks
4. Access Modifiers: Negative AccessModifierOffset creates outdent effect
5. Preprocessor: Be careful with IndentPPDirectives in complex macro code; use PPIndentWidth to control preprocessor indentation separately
6. Mixed Tabs/Spaces: Avoid mixing; use Never or ForIndentation for consistent results
7. Braced Initializers: Use BracedInitializerIndentWidth (clang-format 17+) to control indentation of braced init lists independently
8. Leave Option: The Leave value for IndentPPDirectives preserves existing preprocessor indentation without changes

See Also

• Alignment - Align code elements
• Spacing - Control whitespace
• Braces - Configure brace placement
• Full Style Options Reference

---

← Prev: Braces | Back to Index | Next: Spacing →