.. image:: https://candolint.dwimlabs.net/bitbucket.org/av6/candolint/status.svg
    :target: https://candolint.dwimlabs.net/bitbucket.org/av6/candolint
    :alt: Lint Status
Project configuration
=====================
Here's an example similar to *candolint.yml* of this project itself:
.. code:: yaml
    # bootstrapping data, optional
    url: https://bitbucket.org/av6/candolint
    scm: hg
    # linter config, required
    linters:
      - name: flake8
        vars:
          python_version: 2
        include:
          - '**.py'
      - name: yamllint
        include:
          - '**.yaml'
          - '**.yml'
      - name: jshint
        flags: ['--extract', 'always']
        include:
          - '**.html'
Bootstrapping data
------------------
This is the two most basic things needed to check out project source code: its
URL and SCM.
If you use push hooks or polling, this data is already present in the payload.
You only need to put it in *projects/<name>.yml* file on the worker if you want
to run checks manually (e.g. for testing).
Linter configuration
--------------------
This is the list of linters to run on project source code. Each item only
requires two parameters:
- ``name``: determines what configuration file from *linters/\*.yml* will be
  used (often named after the actual executable)
- ``include``: a sequence of file patterns for checking
Optional parameters include:
- ``vars``: variables used for installing and running linters (e.g.
  ``python_version``)
- ``codes``: allowed exit codes (by default ``0`` and ``1`` are allowed); note
  that this is only for the actual checking, so if *linter --version* exits
  with code ``1``, it's considered a failure
- ``exclude``: a sequence of file patterns to exclude from checks
- ``flags``: additional command line flags passed to the linter (before passing
  file path)
- ``post_flags``: like ``flags``, but passed after file path
The exact base command executed for each linter is specified in
*linters/\*.yml* and cannot be modified in project configuration file, see the
next section.
Base linter configuration
=========================
Every linter needs to be configured via *linters/\*.yml* file. Some files are
already there, they are used to check various projects, including this one
itself. Here's what they look like:
.. code:: yaml
    vars:
      python_version: 2
    setup:
      - ['virtualenv', '--python=python%(python_version)s', '../venv%(python_version)s']
      - ['../venv%(python_version)s/bin/pip', 'install', 'flake8', 'pep8-naming']
    exec: ['../venv%(python_version)s/bin/flake8']
    version: ['--version']
Required parameters:
- ``exec``: a list of strings that will be fed to Python's ``subprocess.Popen``
  for running this linter
- ``version``: a list of strings that will be used as command line flags for
  testing that this linter works after installation
Optional parameters:
- ``setup``: a list of commands (as lists of strings), each will be executed
  consecutively to install this linter
- ``vars``: default values for variables, these can be tweaked in project
  configuration file