clang-format-node

Node repackaging(wrapping) of the clang-format native binary inspired by 'angular/clang-format'.🐉

This package intends to release a new npm package for every latest release of the clang-format. It checks for the latest LLVM release every week, builds clang-format using its own pipeline, and makes a pull request. All processes are run automatically. If you are interested in build process, take a look at .github/workflows/llvm-build-bump-pr.yml

Why I started this project

'angular/clang-format' is no longer maintained. (See #79 #82 #83) Nevertheless, new versions of clang-format continue to be released. Bugs are fixed, and new features are added. However, using clang-format directly in a Node.js environment without any support can be somewhat cumbersome. So I decided to make a new, maintained one.

Note that some feautures from 'angular/clang-format' are not included in this package. Specifically check-clang-format and git-clang-format are not used. There are a few reasons for this. Both commands rely on Python, so if you haven't installed Python, they cannot be executed. Many people would prefer if this package worked without dependencies beyond Node.js. So, this package relies only on Node.js. See the Migration for alternative methods to check-clang-format and git-clang-format.

Supported OS platforms and architectures

It supports ALL Tier1 and some Tier2 platforms of Node.js. Note that the functionality cannot be guaranteed on platforms which is not mentioned below.

(To see the full list of platforms supported by Node.js, click here.)

	Operating System	Architectures	Versions	Support Type
1	macOS	arm64	>= 11.0	Tier 1
2	macOS	x64	>= 11.0	Tier 1
3	GNU/Linux	armv7	kernel >= 4.18, glibc >= 2.28	Tier 1
4	GNU/Linux	arm64	kernel >= 4.18, glibc >= 2.28	Tier 1
5	GNU/Linux	ppc64le >=power8	kernel >= 4.18, glibc >= 2.28	Tier 2
6	GNU/Linux	s390x	kernel >= 4.18, glibc >= 2.28	Tier 2
7	GNU/Linux	x64	kernel >= 4.18, glibc >= 2.28	Tier 1
8	Windows	x64	>= Windows 10/Server 2016	Tier 1

Tip

If your platform isn't yet supported, you can build the clang-format native binary from the latest upstream clang sources. Refer to docs/llvm-build-linux.sh and docs/llvm-build-linux-x64.yml for the Linux build scripts for Shell and GitHub Actions, respectively.
Or you can download clang-format native binary from LLVM release assets that match your operating system platform and architecture like the lists below.
- clang+llvm-18.1.7-aarch64-linux-gnu.tar.xz
- clang+llvm-18.1.7-armv7a-linux-gnueabihf.tar.gz
- clang+llvm-18.1.7-powerpc64-ibm-aix-7.2.tar.xz
- clang+llvm-18.1.7-x86_64-pc-windows-msvc.tar.xz
- and more...

Installation

global

npm install -g clang-format-node

yarn global add clang-format-node

local(devDependencies)

npm install --save-dev clang-format-node

yarn add --dev clang-format-node

Usages

If you want to learn more about clang-format itself, see the clang-format style options.

Tip

clang-format can take multiple files as arguments.

npx clang-format -n -Werror file1.cpp file2.cpp src/file3.cpp

Basic

Global

clang-format [options] [@<file>] [<file> ...]

Local

Use npx to run a locally installed package.

npx clang-format [options] [@<file>] [<file> ...]

Frequently used commands

--version: Check the version of clang-format.
```
npx clang-format --version
```
Output example
```
clang-format version 18.1.8 (https://github.com/llvm/llvm-project 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff)
```
- https://github.com/llvm/llvm-project: Git repository URL for the LLVM project, which includes Clang.
- 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff: The commit hash of the Git repository where the source code for that version is stored. This hash allows you to precisely trace which source code version was used to generate clang-format.
--help: Help view additional options.
```
npx clang-format --help
```
--dry-run or -n: Makes an WARNING when example.cpp is not correctly formatted.

--dry-run and -n options are equivalent.
```
npx clang-format --dry-run example.cpp
```
```
npx clang-format -n example.cpp
```
-Werror --dry-run or -Werror -n: Makes an ERROR when example.cpp is not correctly formatted.

Similar to eslint or prettier --check commands.

--dry-run and -n options are equivalent.
```
npx clang-format -Werror --dry-run example.cpp
```
```
npx clang-format -Werror -n example.cpp
```
-i: Automatically fix unformatted files.

Similar to eslint --fix or prettier --write commands.
```
npx clang-format -i example.cpp
```

Glob patterns

Unfortunately, there is no way to apply clang-format recursively. *.cpp will only match files in the current directory, not subdirectories. Even **/* doesn't work.

So, you need to use the find command in Linux. If you are a Windows user, use git bash. then you can use the find command. The find command recursively searches through directories.

It is simple but can produce an error if the Argument list is too long. In that case, use xargs

Basic

To recursively search for all .cpp files in the current directory, use:

npx clang-format $(find . -name "*.cpp")

If the argument list is too long, use xargs. And if file names contain spaces or special characters, use -print0 and -0 options. -print0 makes find output file names separated by null characters (\0), and -0 tells xargs to correctly handle these null-separated file names.

find . -name "*.cpp" -print0 | xargs -0 npx clang-format

With regular expressions

To recursively search for all .cpp and .h files in the current directory using a regular expression, use:

npx clang-format $(find . -regex ".*\.\(cpp\|h\)")

With negation patterns

To exclude excluded_file.cpp from the .cpp files, use:

npx clang-format $(find . -name "*.cpp" ! -name "excluded_file.cpp")

`.clang-format-ignore`

You can create .clang-format-ignore files to make clang-format ignore certain files. A .clang-format-ignore file consists of patterns of file path names. It has the following format:

A blank line is skipped.
Leading and trailing spaces of a line are trimmed.
A line starting with a hash (#) is a comment.
A non-comment line is a single pattern.
The slash (/) is used as the directory separator.
A pattern is relative to the directory of the .clang-format-ignore file (or the root directory if the pattern starts with a slash). Patterns containing drive names (e.g. C:) are not supported.
Patterns follow the rules specified in POSIX 2.13.1, 2.13.2, and Rule 1 of 2.13.3.
A pattern is negated if it starts with a bang (!).

To match all files in a directory, use e.g. foo/bar/*. To match all files in the directory of the .clang-format-ignore file, use *. Multiple .clang-format-ignore files are supported similar to the .clang-format files, with a lower directory level file voiding the higher level ones.

Use with `husky` and `lint-staged`

Ensuring that changes to your code are properly formatted is an important part of your development workflow. Use husky and lint-staged for your continuous integration process.

`husky` (v8.x)

# .husky/pre-commit

npx lint-staged

`lint-staged` (v15.x)

Check

/* package.json */

{
  // ...
  "lint-staged": {
    "*.{c,cpp,h}": "npx clang-format -Werror -n",
  }
  // ...
}

Fix

/* package.json */

{
  // ...
  "lint-staged": {
    "*.{c,cpp,h}": "npx clang-format -i",
  }
  // ...
}

Tip

If example1.cpp and example2.c are staged, then npx clang-format -Werror -n example1.cpp example2.c will be excuted.

Migration from 'angular/clang-format'

`check-clang-format`

This package only uses native clang-format features to check formatting. The following commands will produce an error if the target files are not correctly formatted. So use them with husky and lint-staged. (--dry-run and -n options are equivalent.)

npx clang-format -Werror --dry-run example.cpp

npx clang-format -Werror -n example.cpp

`git-clang-format`

Use husky and lint-staged for the pre-commit hook instead. See Use with husky and lint-staged for details.

Contributing

Thanks for having attention to this package.🙇‍♂️ Issues and PRs are always welcome.🎉

I recommend you to read the guides on LLVM and clang-format mentioned in issues tab before contributing.

Installation

Fork it.

Clone it to your local directory. (Git is required.)

git clone https://github.com/lumirlumir/npm-clang-format-node.git

Move to the npm-clang-format-node directory.
```
cd npm-clang-format-node
```
Install npm packages. (Node.js is required.)
```
npm install
```
Edit codes.
Create my-branch branch.
```
git switch -c my-branch
```
Commit your changes. (husky and lint-staged will lint and test your changed files!)
```
git commit -am "commit type: title"
```
Push them to your remote branch.
Submit a pull request.👍

About `os.platform()` and `os.arch()` in Node.js

os.platform()

The return value is equivalent to process.platform.

OS	return value of `os.platform()`
macOS	`darwin`
Linux	`linux`
Windows	`win32`

os.arch()

The return value is equivalent to process.arch.

Architecture	return value of `os.arch()`	LLVM	Docker Platform	Docker Ubuntu Image
arm(armv7, armv7l)	`arm`	`ARM`	`arm/v7`	`arm32v7`
arm64	`arm64`	`AArch64`	`arm64/v8`	`arm64v8`
ppc64le¹	`ppc64`	`PowerPC`	`ppc64le`	`ppc64le`
s390x	`s390x`	`SystemZ`	`s390x`	`s390x`
x64	`x64`	`X86`	`amd64`	`amd64`

Build process

Some packages for cross-compilation have been deprecated, making it difficult to make build processes directly, so cross-compilation is not used.

Linux is built using QEMU and Docker. macOS and Windows are built using the macos-13, macos-14, and windows-latest runners on GitHub Actions.

Versioning

This project adheres to Semantic Versioning.

LLVM versions are managed as dependencies, so upgrading the LLVM version is treated as a 'patch'. Additionally, the release title includes the LLVM version, like v1.0.0 (llvmorg-18.1.8).

See .clang-format-version to check the exact current LLVM version.

Change Log

See CHANGELOG.md

License

MIT under LLVM Apache License 2.0

Footnotes

le stands for little-endian, but the os.arch() function does not distinguish between endianness and returns a single value. ↩

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

clang-format-node

Why I started this project

Supported OS platforms and architectures

Installation

global

local(devDependencies)

Usages

Basic

Global

Local

Frequently used commands

Glob patterns

Basic

With regular expressions

With negation patterns

`.clang-format-ignore`

Use with `husky` and `lint-staged`

`husky` (v8.x)

`lint-staged` (v15.x)

Migration from 'angular/clang-format'

`check-clang-format`

`git-clang-format`

Contributing

Installation

About `os.platform()` and `os.arch()` in Node.js

os.platform()

os.arch()

Build process

Versioning

Change Log

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

clang-format-node

Why I started this project

Supported OS platforms and architectures

Installation

global

local(devDependencies)

Usages

Basic

Global

Local

Frequently used commands

Glob patterns

Basic

With regular expressions

With negation patterns

.clang-format-ignore

Use with husky and lint-staged

husky (v8.x)

lint-staged (v15.x)

Migration from 'angular/clang-format'

check-clang-format

git-clang-format

Contributing

Installation

About os.platform() and os.arch() in Node.js

os.platform()

os.arch()

Build process

Versioning

Change Log

License

Footnotes

`.clang-format-ignore`

Use with `husky` and `lint-staged`

`husky` (v8.x)

`lint-staged` (v15.x)

`check-clang-format`

`git-clang-format`

About `os.platform()` and `os.arch()` in Node.js