1 files changed, 133 insertions, 0 deletions
diff --git a/docs/code-quality/lint/usage.rst b/docs/code-quality/lint/usage.rst
new file mode 100644
index 0000000000..d0eb1d5b02
--- /dev/null
+++ b/docs/code-quality/lint/usage.rst
@@ -0,0 +1,133 @@
+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