Writing a coala Configuration File (coafile and coarc)

This document gives a short introduction to the specification of acoala configuration file. It is meant to be rather factual. If you wishto learn by example, please take a look at Getting Started with coala. It alsoteaches how to change settings inside a coala file to suit your taste.

Naming, Scope and Location

You can use up to three coafiles to configure your project.

  • A project-wide coafile.
  • A user-wide coafile.
  • A system-wide coafile.

Project-Wide coafile

It is a convention that the project-wide coafile is named .coafileand lies in the project root directory. If you follow this convention,simply executing coala from the project root will execute theconfiguration specified in that file.

Settings given in the project-wide coafile override all settings givenby other files and can only be overridden by settings given via thecommand line interface.

User-Wide and System-Wide coafile

You can place a .coarc file in your home directory to set certainuser wide settings. Those settings will automatically be taken for allprojects executed with that user.

All settings specified here override only settings given by the systemwide coafile which has the lowest priority. The system_coafile mustlie in the coala installation directory and is valid for everyone usingthis coala installation.

It can be used to define the type of files you usually don’t want to lint,like minified files (e.g. .min.js) and backup files (e.g. .orig):

  1. ignore = **.min.js, **.orig

Explicit Setting Inheritance

Every coafile contains one or more sections. Section names are caseinsensitive. The old(pre 0.11.x) implicit section inheritance syntaxhas been deprecated and has been scheduled for removal in coala version 0.12.0.Instead, define section inheritance explicitly by naming a section in theformat [basesection.newsection]. Extra values can be appended to aninherited setting using the += operator.

Consider the following coafile:

  1. [all]
  2. enabled = True
  3. overridable = 2
  4. ignore = vendor1/
  5.  
  6. [all.section1]
  7. overridable = 3
  8. ignore += vendor2/
  9. other = some_value
  10.  
  11. [all.section2]
  12. overridable = 4
  13. ignore += vendor3/
  14. other = some_other_value

This is the same file without section inheritance:

  1. [all]
  2. enabled = True
  3. overridable = 2
  4. ignore = vendor1/
  5.  
  6. [section1]
  7. enabled = True
  8. overridable = 3
  9. ignore = vendor1/, vendor2/
  10. other = some_value
  11.  
  12. [section2]
  13. enabled = True
  14. overridable = 4
  15. ignore = vendor1/, vendor3/
  16. other = some_other_value

All settings must be part of a section, so don’t do this for implicitinheritance (this is also deprecated behavior). Implicit inheritancewas leading to a section automatically getting inherited to all othersections without semantically making sense:

  1. # bad!
  2. setting1 = 1
  3.  
  4. [section1]
  5. # setting1 is inherited
  6. setting2 = 2

Instead, make the inheritance explicit:

  1. # better!
  2. [all]
  3. setting1 = 1
  4.  
  5. [all.section1]
  6. # setting1 is inherited
  7. setting2 = 2

Defining Aspects and Tastes

Aspects is an alternative way to configure coala. In this mode, we don’t needto explicitly state list of bears, coala will choose it automatically based onrequested aspects in coafile. To run coala in this mode, we need to defineaspects, files, languages, and optionally aspect tastes setting. Seethe following example:

  1. [all]
  2. files = **
  3. aspects = aspectname1, AspectName2 # case-insensitive
  4. # defining an aspect's taste
  5. aspectname1:aspect_taste = 80
  6. # we can define subaspect taste through its parent
  7. aspectname1:subaspect_taste = word1, word2, word3
  8.  
  9. [all.python]
  10. files = **.py
  11. language = Python
  12. # appending additional aspect
  13. aspects += aspectname3
  14. # excluding certain subaspect
  15. excludes = AspectName2Subaspect

Comments, Escaping and Multiline Values and Keys

Comments are simply done with a preceding #. If you want to use a# within a value, you can simply escape it:

  1. a_key = a\#value # And a comment at the end!

Any line not containing an unescaped = is simply appended to thevalue of the last key:

  1. a_key = a
  2. value
  3. # this is not part of the value
  4. that /= is
  5. very long!

Similarly, you can also set a value to multiple keys:key_1, key_2 = value is equivalent to key_1 = value andkey_2 = value in separate lines.

As the backslash \ is the escape character it is recommended to useforward slashes / as path separator even on Windows (to keep relativepaths platform independent), use double-backslashes \ if you really mean abackslash in all places.

You can now proceed to an example with Getting Started with coala.