Add linters to a project

From Apertis
Jump to: navigation, search

To add Phabricator linters to a project (specifically, clang-format-linter):


Install clang-format-linter locally

A custom local install of the clang-format-linker can be easily done:

On an Apertis image or on Debian stretch:

apt-get install arcanist-clang-format-linter

Or when packages for clang-format-linter aren’t available for your distribution:

<change to the path where you want to put the linter, e.g. ~/source>
git clone clang-format-linter
arc set-config load "[ \"$(pwd)/clang-format-linter\" ]"

Check the installation:

arc linters  # should list ‘clang-format’ as ‘configured’

We are using a custom clone of the original clang-format-linter which adds support for splitting the diff into chunks and adds some more help.

Make sure clang-format is recent

Again, this should be done on each developer’s machine.

Install clang-format 3.7 or later, and make sure that running "clang-format" results in running that version. For instance, in Debian unstable as of January 2016 it's called clang-format-3.7, so you might add ~/bin to your PATH and make a symbolic link:

ln -s /usr/bin/clang-format-3.7 ~/bin/clang-format

Update .arcconfig

Update the .arcconfig file for the project (in git) to add the linter configuration and load the clang-format-linter arcanist extension:

"lint.engine": "ArcanistConfigurationDrivenLintEngine"

Add a .clang-format file

clang-format accepts its format options from a hidden file, defined in YAML format. Create .clang-format and commit it to git:

# See
BasedOnStyle: GNU
AlwaysBreakAfterDefinitionReturnType: All
BreakBeforeBinaryOperators: None
BinPackParameters: false
SpaceAfterCStyleCast: true

These are the current recommended formatting options from the coding conventions, but may change in future as clang-format evolves or corner cases in the configuration are found and fixed.

Add a .arclint file

To enable the linters to be used with arc lint (and hence with arc diff and git-phab attach), add a .arclint file to the project and commit it to git. This example file contains XML, Python and C linters. Note that you should adjust the include path for the clang-format-default linter to include the source directories in your project, while excluding any generated C or H files.

  "linters": {
    "clang-format-default": {
      "type": "clang-format",
      "version": ">=3.7.0",
      "include": "(^(src|tests|canterbury)/.*\\.(c|h)$)"
    "pep8-default": {
      "type": "pep8",
      "flags": ["--ignore=E402"],
      "include": "(\\.py$)"
    "xml-default": {
      "type": "xml",
      "include": "(\\.xml$)"

We ignore PEP8 error E402 because the recommended copyright headers, editor modelines and encoding lines push the first import statement below the recommended line number according to PEP8.

Personal tools