usage.rst (4483B)
1 Running Linters Locally 2 ======================= 3 4 Using the Command Line 5 ---------------------- 6 7 You can run all the various linters in the tree using the ``mach lint`` command. Simply pass in the 8 directory or file you wish to lint (defaults to current working directory): 9 10 .. parsed-literal:: 11 12 ./mach lint path/to/files 13 14 Multiple paths are allowed: 15 16 .. parsed-literal:: 17 18 ./mach lint path/to/foo.js path/to/bar.py path/to/dir 19 20 To force execution on a directory that would otherwise be excluded: 21 22 .. parsed-literal:: 23 24 ./mach lint -n path/in/the/exclude/list 25 26 ``Mozlint`` will automatically determine which types of files exist, and which linters need to be run 27 against them. For example, if the directory contains both JavaScript and Python files then mozlint 28 will automatically run both ESLint and Flake8 against those files respectively. 29 30 To restrict which linters are invoked manually, pass in ``-l/--linter``: 31 32 .. parsed-literal:: 33 34 ./mach lint -l eslint path/to/files 35 36 You can see a list of the available linters by running: 37 38 .. parsed-literal:: 39 40 ./mach lint --list 41 42 Finally, ``mozlint`` can lint the files touched by outgoing revisions or the working directory using 43 the ``-o/--outgoing`` and ``-w/--workdir`` arguments respectively. 44 In the case of ``--outgoing``, the default remote repository the changes would be pushed to is 45 used as the comparison. If desired, a remote can be specified manually. In git, you may only want to 46 lint staged commits from the working directory, this can be accomplished with ``--workdir=staged``. 47 Examples: 48 49 .. parsed-literal:: 50 51 ./mach lint --workdir 52 ./mach lint --workdir=staged 53 ./mach lint --outgoing 54 ./mach lint --outgoing origin/master 55 ./mach lint -wo 56 57 58 Automatically Fixing Lint Errors 59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 61 ``Mozlint`` has a best-effort ability to fix lint errors: 62 63 .. parsed-literal:: 64 65 $ ./mach lint --fix 66 67 Not all linters support fixing, and even the ones that do can not usually fix 68 all types of errors. Any errors that cannot be automatically fixed, will be 69 printed to stdout like normal. In that case, you can also fix errors manually: 70 71 .. parsed-literal:: 72 73 $ ./mach lint --edit 74 75 This requires the $EDITOR environment variable be defined. For most editors, 76 this will simply open each file containing errors one at a time. For vim (or 77 neovim), this will populate the `quickfix list`_ with the errors. 78 79 The ``--fix`` and ``--edit`` arguments can be combined, in which case any 80 errors that can be fixed automatically will be, and the rest will be opened 81 with your $EDITOR. 82 83 VCS Integrations 84 ---------------- 85 86 .. _lint-vcs-hook: 87 88 Using a Git Hook 89 ~~~~~~~~~~~~~~~~ 90 91 There are also both pre-commit and pre-push version control hooks that work in 92 git. 93 94 To enable a pre-push git hook, run the following command: 95 96 .. code-block:: console 97 98 $ ln -s ../../tools/lint/hooks.py .git/hooks/pre-push 99 100 101 To enable a pre-commit git hook, run the following command: 102 103 .. code-block:: console 104 105 $ ln -s ../../tools/lint/hooks.py .git/hooks/pre-commit 106 107 Note that the symlink will be interpreted as ``.git/hooks/../../tools/lint/hooks.py``. 108 109 Jujutsu Integration 110 ~~~~~~~~~~~~~~~~~~~ 111 112 Mach lint can also integrate with `Jujutsu SCM's`_ ``jj fix`` command. Add 113 the following to your repo config: 114 115 .. code-block:: toml 116 117 [fix.tools.mozlint] 118 command = ["path/to/mozilla-unified/tools/lint/pipelint", "$path"] 119 patterns = ["glob:'**/*'"] 120 121 122 .. note:: 123 On Windows you must explicitly prepend ``"python3",`` to `command`. 124 125 126 .. code-block:: toml 127 128 [fix.tools.mozlint] 129 command = ["python3", "path/to/mozilla-unified/tools/lint/pipelint", "$path"] 130 patterns = ["glob:'**/*'"] 131 132 .. _Jujutsu SCM's: https://jj-vcs.github.io/jj/latest/ 133 134 Editor Integrations 135 ------------------- 136 137 .. note:: 138 139 See details on `how to set up your editor here </contributing/editor.html#editor-ide-integration>`_ 140 141 Editor integrations are highly recommended for linters, as they let you see 142 errors in real time, and can help you fix issues before you compile or run tests. 143 144 Although mozilla-central does not currently have an integration available for 145 `./mach lint`, there are various integrations available for some of the major 146 linting tools that we use: 147 148 * `ESLint`_ 149 * `Black (Python)`_ 150 151 .. _quickfix list: http://vimdoc.sourceforge.net/htmldoc/quickfix.html 152 .. _ESLint: https://eslint.org/docs/user-guide/integrations#editors 153 .. _Black (Python): https://black.readthedocs.io/en/stable/editor_integration.html