vscode-clang-format

The extension requires clang-format (version 3.8 or higher) to be installed on your operating system.

Linux

Use your package manager (e.g., apt):

sudo apt install clang-format

Windows

Install LLVM via the official installer or using winget:

winget install -e --id LLVM.LLVM

After installing LLVM on Windows, you may need to point the extension to the specific executable in your settings.json:

{
    "clang-format.executable": "c:\Program Files\LLVM\bin\clang-format.exe"
}

This extension enables clang-format (version 3.8 or higher) to format C/C++, JavaScript, and other supported languages directly within Visual Studio Code.

Manual Formatting

• Right-click: Right-click anywhere in the document and select Format Document.
• Keyboard Shortcuts:
  • Windows: Ctrl+⇧+F
  • Linux: Ctrl+⇧+I
  • macOS: ⇧+⌥+F

Automatic Formatting on Save

To enable automatic formatting whenever you save a file, add the following to your settings.json:

{
    "editor.formatOnSave": true
}

The extension attempts to find clang-format on your system PATH automatically. If it cannot be found, or if you want to use a specific version, you can specify the absolute path in your settings.json using the clang-format.executable setting.

Supported Placeholders for clang-format.executable

You can use the following placeholders to make paths portable across different environments or workspaces:

• ${workspaceRoot}: Absolute path of the current VS Code workspace root.
• ${workspaceFolder}: Absolute path of the current VS Code workspace (expands to the first available workspace for files outside a workspace).
• ${cwd}: The current working directory of VS Code.
• ${env.VAR}: An environment variable (e.g., ${env.HOME} expands to $HOME).

{
    "clang-format.executable": "/absolute/path/to/clang-format"
}

The clang-format.assumeFilename setting allows you to tell clang-format to treat a file as if it has a different name (useful for formatting header files as if they were source files).

This setting supports standard VS Code editor variables:

• ${file}
• ${fileNoExtension}
• ${fileBasename}
• ${fileBasenameNoExtension}
• ${fileExtname}

Example: If you have a file /home/src/foo.h, setting the value to ${fileNoExtension}.cpp will cause clang-format to run with -assume-filename /home/src/foo.cpp.

{
    "clang-format.assumeFilename": "${fileNoExtension}.cpp"
}

When configuring clang-format.executable, you can use placeholders to point to local installations or environment-specific paths.

Examples:

• Use a version installed via npm in your workspace: ${workspaceRoot}/node_modules/.bin/clang-format
• Use a specific version in your home directory: ${env.HOME}/tools/clang38/clang-format

{
    "clang-format.executable": "${workspaceRoot}/node_modules/.bin/clang-format"
}

The extension uses workspace configuration keys to determine which language modes should be active. To enable clang-format for a specific language, set the enable property under the corresponding language.<language_id> key in your VS Code settings.

Supported language IDs include:

• cpp, c, csharp, objective-c, objective-cpp, java, javascript, json, typescript, proto, textproto, apex, glsl, hlsl, cuda, cuda-cpp

Note: proto3 is aliased to proto in the configuration.

{
  "clang-format.language.cpp.enable": true,
  "clang-format.language.proto.enable": true
}

If clang-format requires a specific filename context to format correctly (e.g., to determine the language), you can configure clang-format.assumeFilename. This setting supports placeholders that are replaced based on the current document:

• ${file}: The full path of the current file.
• ${fileNoExtension}: The file path without the extension.
• ${fileBasename}: The filename including the extension.
• ${fileBasenameNoExtension}: The filename without the extension.
• ${fileExtname}: The file extension.

The extension attempts to resolve the clang-format executable automatically. If the automatic resolution fails, you can provide a specific absolute path to the clang-format binary via the extension settings. The extension searches for the binary in the following order:

1. The absolute path provided in your configuration.
2. The system PATH environment variable using common executable extensions (e.g., .exe, .bat, .cmd on Windows).

If no valid path is found, the extension will attempt to use the raw binary name, which will likely result in a failure during formatting.

The extension determines the formatting style using a hierarchy of settings. It first looks for language-specific styles, then falls back to a global style.

Style Hierarchy

1. Language-specific style: clang-format.language.<languageId>.style (e.g., clang-format.language.cpp.style)
2. Global style: clang-format.style (defaults to file)

Fallback Style

If the primary style fails, the extension uses a fallback style:

1. Language-specific fallback: clang-format.language.<languageId>.fallbackStyle
2. Global fallback: clang-format.fallbackStyle (defaults to none)

You can specify the path to the clang-format binary using the clang-format.executable setting. The extension supports platform-specific overrides and variable expansion.

Platform-specific overrides

You can provide a specific path for different operating systems using:

• clang-format.executable.windows
• clang-format.executable.linux
• clang-format.executable.osx

Variable expansion

The executable path supports the following placeholders:

• ${workspaceRoot}: The root path of the workspace.
• ${workspaceFolder}: The path of the current workspace folder.
• ${cwd}: The current working directory.
• ${env.VARIABLE_NAME}: An environment variable (e.g., ${env.PATH}).