Command line tutorial

Introduction

Now that you've installed ESLint and have it configured, this tutorial will familiarize you with some common command-line options and their applications.

Topics covered in this document:

Syntax review and common options
Use cases with examples (linting a single file, linting two files, linting contents of directories, ignoring files, fixing errors, formatting output, redirecting output)

Syntax

npx eslint [options] [ file | dir | glob ]

Options

Option	Usage
`-h`, `--help`	Provide a list of available options.
`-f`, `--format`	Allows you to format ESLint console output.
`--fix`	Automatically fixes errors when possible. Files are updated.
`--fix-dry-run`	Preview-only version of `--fix`. Files are not updated.
`--ignore-path`	Allows you to specify the path to an ignore file.
-`-ignore-pattern`	Allows you to specify ignore patterns in addition to those found in an ignore file.
`-o`, `--output-file`	Allows you to redirect ESLint output to a file.

NOTES:

Full options list - At any time, you can always obtain a full list of options by running:
```
npx eslint -h
```
If you require more detailed information on any of the available options, a full command-line interface reference guide is provided on the ESLint project site.
Short-form options - In some cases, ESLint supports short-form equivalents of the standard long-form options (e.g., -f (format), -h (help), -v (version), -o (output), etc.).

Prerequisites

This tutorial assumes that all commands will be run either in a terminal window or their equivalent on your system.
Familiarity with .eslintignore files.
In much the same way git uses .gitignore files, ESLint relies on patterns in .eslintignore files to guide its execution. In fact, since eslintignore follows the same specification as gitignore, your git experience will be of assistance when creating .eslintignore files for your project. For further details, please refer to the ESLint documentation.
There are 2 major aspects of this specification that you should keep in mind for this tutorial:
- Glob patterns - like .gitignore, .eslintignore files will accept patterns like *.jpg or lib*
- Priority - By default, ESLint will use the .eslintignore in the current directory. If a .eslintignore is found, then those preferences are used when linting files. Since only one .eslintignore file can be used at a time, ESLint will ignore any other .eslintignore files it encounters when traversing directories.
Familiarity with the structure and contents of the tutorial project.
To review the project's directory structure and the contents of its test files, please review the Sample project section before continuing with the tutorial.

Use cases

For this tutorial, a sample project, outlined below, will be used as the basis of all examples. In addition, ESLint's default output format (stylish) will be used in each explored use case.

NOTE:

If you would like more information on alternate output formats, please see the formatting output section below.

Case 1: single file

[ Present working directory (PWD): C:\Tutorials\files ]

npx eslint hello.js

C:\Tutorials\files\hello.js
1:10    error   'helloworld' is defined but never used          no-unused-vars

5:5     error   'greeter' is assigned a value but never used    no-unused-vars

6:1     error   'helloWorld' is not defined                     no-undef

6:12    error   'greeter2' is not defined                       no-undef

?       4 problems (4 errors, 0 warnings)

Output review

At this point, please take a moment to look over the output above. In this simple example, several obvious JavaScript errors have been intentionally included to illustrate the capabilities of ESLint. Here, ESLint correctly caught both the undefined (no-undef) terms (helloWorld and greeter2) and the unused (no-unused-vars) terms (helloworld, greeter).

As you can see, ESLint displays a separate line for each error it encounters while linting hello.js. Each line follows the format described below.

Error format:

<line #> : <position>    <error level>  <error text>            <rule>

Problem summary:

At the end of the error report, ESLint displays a cumulative summary of problems (errors and warnings) encountered while linting. When multiple files are linted, the output will include a list of errors for each file.

Case 2: two files

[ PWD: C:\Tutorials\files ]

npx eslint hello.js hello2.js

C:\Tutorials\files\hello.js
[<errors>]

C:\Tutorials\files\hello2.js
3:2     error   Unnecessary semicolon                           no-extra-semi

?       5 problems (5 errors, 0 warnings)
        1 error and 0 warnings potentially fixable with the `--fix` option.

Case 3: directory

This example will illustrate how to lint the contents of the "files2" directory.

NOTE:

Without specifying any ignore criteria, the linter will traverse all subdirectories within "files2." In this example, the contents of "lib" would be linted as well.

In the next section, Ignoring files, you will learn how to use some of ESLint's options to restrict output.

[ PWD: C:\Tutorials ]

npx eslint files2

C:\Tutorials\files2\hello4.js
1:10    error   'helloworld' is defined but never used          no-unused-vars

5:5     error   'greeter' is assigned a value but never used    no-unused-vars

6:1     error   'helloWorld' is not defined                     no-undef

6:12    error   'greeter2' is not defined                       no-undef

C:\Tutorials\files2\lib\hello3.js
1:10    error   'helloworld' is defined but never used          no-unused-vars

5:5     error 'greeter' is assigned a value but never used      no-unused-vars

6:1     error 'helloWorld' is not defined                       no-undef

6:12    error 'greeter2' is not defined                         no-undef

?       9 problems (9 errors, 0 warnings)

        1 error and 0 warnings potentially fixable with the `--fix` option.

Case 4: ignoring files

`--ignore-path`

This option allows you to specify the file to use as your .eslintignore. By default, ESLint looks in the current working directory for .eslintignore. You can override this behavior by providing a path to a different file.

Example: lint files in the current directory using a non-local .eslintignore file

[ PWD: C:\Tutorials\files2 ]

npx eslint --ignore-path ..\.eslintignore .\*

`--ignore-pattern`

This option allows you to specify patterns of files to ignore (in addition to those in .eslintignore). If you wish to filter on multiple patterns, ESLint allows you to repeat the option, one for each pattern.

Example: lint using a glob pattern

[ PWD: C:\Tutorials\ ]

npx eslint --ignore-pattern "hello[1-3]*.js" files

NOTE:

Similar to --rule and .eslintrc files, the syntax for the --ignore-pattern option matches that for .eslintignore files. In general, if your ignore pattern contains a glob (e.g., hello[1-3]*.js, it is recommended that you enclose the pattern in quotes in order to avoid interpretation by the shell.

Example: linting with a non-local .eslintignore file

This command lints files in the current directory (files) as well as those in \lib.
It also makes use of the .eslintignore file in the Tutorials directory rather than the one present in files (the current directory).

[ PWD: C:\Tutorials\files\ ]

npx eslint --ignore-path ..\.eslintignore .\

C:\Tutorials\files\hello.js
1:10    error   'helloworld' is defined but never used          no-unused-vars

5:5     error   'greeter' is assigned a value but never used    no-unused-vars

6:1     error   'helloWorld' is not defined                     no-undef

6:12    error   'greeter2' is not defined                       no-undef

C:\Tutorials\files\hello2.js
3:2     error   Unnecessary semicolon                           no-extra-semi

C:\Tutorials\files\lib\hello3.js
1:10    error   'helloworld' is defined but never used          no-unused-vars

5:5     error   'greeter' is assigned a value but never used    no-unused-vars

6:1     error   'helloWorld' is not defined                     no-undef

6:12    error   'greeter2' is not defined                       no-undef

?       9 problems (9 errors, 0 warnings)
        1 error and 0 warnings potentially fixable with the `--fix` option.

Example: restrict linting to avoid the lib subdirectory

If you wish to confine linting to just the current directory (files) you can exclude the lib subdirectory with the use of the ignore-pattern option:

[ PWD: C:\Tutorials\files\ ]

npx eslint --ignore-path ..\.eslintignore --ignore-pattern "lib*" .\

C:\Tutorials\files\hello.js
[errors]

C:\Tutorials\files\hello2.js
[errors]

C:\Tutorials\files\lib\hello3.js
[errors]

?   9 problems (9 errors, 0 warnings)
    1 error and 0 warnings potentially fixable with the `--fix` option.

Example: a simpler method to restrict linting to avoid the lib subdirectory

In this example, you'll see how to exclude the lib subdirectory by letting the local .eslintignore file do all the heavy lifting. This particular command makes use of 2 properties that you were introduced to earlier in the tutorial:

By default, eslint will always look for a .eslintignore file in the current directory.
From the Directory structure section above, you can see that the files directory contains an ignore file.
Patterns attached to any --ignore-pattern options are applied after those in an ignore file.
This means that you could simply include these patterns in the ignore file from the start.

[ PWD: C:\Tutorials\files ]

npx eslint .\

NOTE:

Since C:\Tutorials\files\.eslintrc already contains the ignore pattern "lib*" (see Test files, below), the lib subdirectory will be excluded from linting.

C:\Tutorials\files\hello.js
[errors]

C:\Tutorials\files\hello2.js
[errors]

?   5 problems (5 errors, 0 warnings)
    1 error and 0 warnings potentially fixable with the `--fix` option.

As you can see from the above output, eslint has avoided linting any files within the lib subdirectory.

Case 5: fixing errors

`--fix`

When this option is included, ESLint will try and fix as many detected issues as possible while linting.

NOTE:

This is a destructive process. If ESLint is able to apply the recommended fixes, they will be made directly to files themselves without any additional warning or user input.
Any uncorrectable issues will be included in the standard error report.
If you wish to preview the fix process without committing to the original files, you can use the --fix-dry-run option (please see below).

Example: lint contents of the files directory

[ PWD: C:\Tutorials\ ]

npx eslint files

C:\Tutorials\files\hello.js
[<errors>]

C:\Tutorials\files\hello2.js
3:2 error   Unnecessary semicolon                       no-extra-semi

C:\Tutorials\files\lib\hello3.js
[<errors>]

?   9 problems (9 errors, 0 warnings)
    1 error and 0 warnings potentially fixable with the `--fix` option.

Example: lint contents of the files directory and fix errors

npx eslint --fix files

C:\Tutorials\files\hello.js
[<errors>]

C:\Tutorials\files\lib\hello3.js
[<errors>]

?   8 problems (8 errors, 0 warnings)

`--fix-dry-run`

This option allows you to preview potential fixes to your code without committing them to the files themselves.

NOTE:

If the --fix-dry-run option was used instead of the --fix option in the example above, the output of the command would have been identical. However, unlike with the --fix option, the fix would not have been applied to hello2.js.

Case 6: formatting output

`-f`, `--format`

This option allows you to specify a particular format for ESLint's console output.

Currently, there are 10 output formats that ESLint supports: checkstyle, compact, html, jslint-xml, json, junit, stylish (default), tap, unix, and Visualstudio.

The default format, stylish, is the one that you have seen throughout this tutorial.
If you wish to suppress the default color style for this format, add the --no-color option when running the eslint command.

Depending on your personal preferences and use cases, other formats may be a better choice. The json format captures eslint console output in a more structured manner, for instance, while html offers a more human-readable, report-style format.

NOTE:

Both the json and html formats are good candidates for redirecting output to a file. This will be covered in the redirecting output section below.

`--format=json`

npx eslint --format=json files\hello2.js

[{"filePath":"C:\Tutorials\\files\\hello2.js","messages":[{"ruleId":"no-extra-semi","severity":2,"message":"Unnecessary semicolon.","line":3,"column":2,"nodeType":"EmptyStatement","messageId":"unexpected","endLine":3,"endColumn":3,"fix":{"range":[68,77],"text":"}\r\n\r\nvar"}}],"suppressedMessages":[],"errorCount":1,"fatalErrorCount":0,"warningCount":0,"fixableErrorCount":1,"fixableWarningCount":0,"source":"function helloWorld(greeter) {\r\n  alert(\"Hello, \" + greeter + \"!\")\r\n};\r\n\r\nvar greeter = window.prompt(\"Enter your name: \");\r\nhelloWorld(greeter);\r\n","usedDeprecatedRules":[]}]

`--format=html`

[ PWD: C:\Tutorials ]

npx eslint --format=html files

htmlFormat

Case 7: redirecting output

`-o`, `--output-file`

This format allows you to redirect output to a file.

Example: redirect html-formatted output to a file

[ PWD: C:\Tutorials ]

npx eslint --format=html -o errorSummary.html files

Once again, ESLint inspects the content of the files directory and formats the linting output. In this case, however, the formatted output is now directed to the file errorSummary.html instead of the console.

NOTE:

The ESLint Report screen capture shown in the formatting output section above is generated from this errorSummary.html file.

Sample project

Directory structure

Tutorials
 ┣ files
 ┃ ┣ lib
 ┃ ┃ ┣ .eslintrc.js
 ┃ ┃ ┗ hello3.js
 ┃ ┣ .eslintignore
 ┃ ┣ hello.js
 ┃ ┣ hello2.js
 ┃ ┗ sComand.json
 ┣ files2
 ┃ ┣ lib
 ┃ ┃ ┗ hello3.js
 ┃ ┗ hello4.js
 ┣ .eslintignore
 ┗ .eslintrc.js

Test files

C:\Tutorials\.eslintignore:
```
# comments allowed
.eslintrc.*
```

C:\Tutorials\files\.eslintignore:

# comments allowed  
*.json
.eslintrc.*
lib*

hello.js

function helloworld(greeter) {
  alert("Hello, " + greeter + "!")
}

var greeter = window.prompt("Enter your name: ");
helloWorld(greeter2);

hello2.js

function helloWorld(greeter) {
  alert("Hello, " + greeter + "!")
};

var greeter = window.prompt("Enter your name: ");
helloWorld(greeter);

NOTES:

For simplicity, both hello3.js and hello4.js are the same as hello.js.
For compactness, linting results for a file will be abbreviated after having been displayed in full.

Command line tutorial

Introduction​

Syntax​

Options​

Prerequisites​

Use cases​

Case 1: single file​

Output review​

Case 2: two files​

Case 3: directory​

Case 4: ignoring files​

--ignore-path​

Example: lint files in the current directory using a non-local .eslintignore file​

--ignore-pattern​

Example: lint using a glob pattern​

Example: linting with a non-local .eslintignore file​

Example: restrict linting to avoid the lib subdirectory​

Example: a simpler method to restrict linting to avoid the lib subdirectory​

Case 5: fixing errors​

--fix​

Example: lint contents of the files directory​

Example: lint contents of the files directory and fix errors​

--fix-dry-run​

Case 6: formatting output​

-f, --format​

--format=json​

--format=html​

Case 7: redirecting output​

-o, --output-file​

Example: redirect html-formatted output to a file​

Sample project​

Directory structure​

Test files​

Introduction

Syntax

Options

Prerequisites

Use cases

Case 1: single file

Output review

Case 2: two files

Case 3: directory

Case 4: ignoring files

`--ignore-path`

Example: lint files in the current directory using a non-local .eslintignore file

`--ignore-pattern`

Example: lint using a glob pattern

Example: linting with a non-local .eslintignore file

Example: restrict linting to avoid the lib subdirectory

Example: a simpler method to restrict linting to avoid the lib subdirectory

Case 5: fixing errors

`--fix`

Example: lint contents of the files directory

Example: lint contents of the files directory and fix errors

`--fix-dry-run`

Case 6: formatting output

`-f`, `--format`

`--format=json`

`--format=html`

Case 7: redirecting output

`-o`, `--output-file`

Example: redirect html-formatted output to a file

Sample project

Directory structure

Test files