gecko-dev/docs/code-quality/lint/usage.rst

Running Linters Locally
=======================

Using the Command Line
----------------------

You can run all the various linters in the tree using the ``mach lint`` command. Simply pass in the
directory or file you wish to lint (defaults to current working directory):

.. parsed-literal::

    ./mach lint path/to/files

Multiple paths are allowed:

.. parsed-literal::

    ./mach lint path/to/foo.js path/to/bar.py path/to/dir

To force execution on a directory that would otherwise be excluded:

.. parsed-literal::

    ./mach lint -n path/in/the/exclude/list

``Mozlint`` will automatically determine which types of files exist, and which linters need to be run
against them. For example, if the directory contains both JavaScript and Python files then mozlint
will automatically run both ESLint and Flake8 against those files respectively.

To restrict which linters are invoked manually, pass in ``-l/--linter``:

.. parsed-literal::

    ./mach lint -l eslint path/to/files

You can see a list of the available linters by running:

.. parsed-literal::

    ./mach lint --list

Finally, ``mozlint`` can lint the files touched by outgoing revisions or the working directory using
the ``-o/--outgoing`` and ``-w/--workdir`` arguments respectively. These work both with mercurial and
git. In the case of ``--outgoing``, the default remote repository the changes would be pushed to is
used as the comparison. If desired, a remote can be specified manually. In git, you may only want to
lint staged commits from the working directory, this can be accomplished with ``--workdir=staged``.
Examples:

.. parsed-literal::

    ./mach lint --workdir
    ./mach lint --workdir=staged
    ./mach lint --outgoing
    ./mach lint --outgoing origin/master
    ./mach lint -wo

.. _lint-vcs-hook:

Using a VCS Hook
----------------

There are also both pre-commit and pre-push version control hooks that work in
either hg or git. To enable a pre-push hg hook, add the following to hgrc:

.. parsed-literal::

    [hooks]
    pre-push.lint = python:./tools/lint/hooks.py:hg


To enable a pre-commit hg hook, add the following to hgrc:

.. parsed-literal::

    [hooks]
    pretxncommit.lint = python:./tools/lint/hooks.py:hg


To enable a pre-push git hook, run the following command:

.. parsed-literal::

    $ ln -s /path/to/gecko/tools/lint/hooks.py .git/hooks/pre-push


To enable a pre-commit git hook, run the following command:

.. parsed-literal::

    $ ln -s /path/to/gecko/tools/lint/hooks.py .git/hooks/pre-commit


Fixing Lint Errors
==================

``Mozlint`` has a best-effort ability to fix lint errors:

.. parsed-literal::

    $ ./mach lint --fix

Not all linters support fixing, and even the ones that do can not usually fix
all types of errors. Any errors that cannot be automatically fixed, will be
printed to stdout like normal. In that case, you can also fix errors manually:

.. parsed-literal::

    $ ./mach lint --edit

This requires the $EDITOR environment variable be defined. For most editors,
this will simply open each file containing errors one at a time. For vim (or
neovim), this will populate the `quickfix list`_ with the errors.

The ``--fix`` and ``--edit`` arguments can be combined, in which case any
errors that can be fixed automatically will be, and the rest will be opened
with your $EDITOR.

Editor Integration
==================

Editor integrations are highly recommended for linters, as they let you see
errors in real time, and can help you fix issues before you compile or run tests.

Although mozilla-central does not currently have an integration available for
`./mach lint`, there are various integrations available for some of the major
linting tools that we use:

* `ESLint`_
* `Black (Python)`_

.. _quickfix list: http://vimdoc.sourceforge.net/htmldoc/quickfix.html
.. _ESLint: https://eslint.org/docs/user-guide/integrations#editors
.. _Black (Python): https://black.readthedocs.io/en/stable/editor_integration.html