lint_staged 0.5.1

Run linters on git staged files for your Flutter and Dart projects.

example/README.md

lint_staged

Run linters on git staged files for your Flutter and Dart projects.

Inspired by Javascript lint-staged

Why

Linting makes more sense when run before committing your code. By doing so you can ensure no errors go into the repository and enforce code style. But running a lint process on a whole project is slow, and linting results can be irrelevant. Ultimately you only want to lint files that will be committed.

This project contains a script that will run arbitrary shell tasks with a list of staged files as an argument, filtered by a specified glob pattern.

Installation and setup

To install lint_staged in the recommended way, you need to:

1. Install lint_staged itself:
   • dart pub add --dev lint_staged
2. Set up the pre-commit git hook to run lint_staged
   • Husky is a recommended choice for configuring git hooks
   • Read more about git hooks here
3. Configure lint_staged to run linters and other tasks:
   • for example, add following in pubspec.yaml:

   lint_staged:
     'lib/**.dart': dart format --fix && dart fix --apply
   

   to automatically format & fix all staged dart files.
   • See Configuration for more info

Don't forget to commit changes to pubspec.yaml and .husky to share this setup with your team!

Now change a few files, git add or git add --patch some of them to your commit, and try to git commit them.

See examples and configuration for more information.

Changelog

See CHANGELOG.md.

Command line flags

❯ dart lint_staged --help
Usage: lint_staged [options]

Options:
  --allow-empty                      allow empty commits when tasks revert all staged changes (default: false)
  --diff [string]                    override the default "--staged" flag of "git diff" to get list of files. Implies
                                     "--no-stash".
  --diff-filter [string]             override the default "--diff-filter=ACMR" flag of "git diff" to get list of files
  --no-stash                         disable the backup stash, and do not revert in case of errors

• --allow-empty: By default, when linter tasks undo all staged changes, lint_staged will exit with an error and abort the commit. Use this flag to allow creating empty git commits.
• --diff: By default linters are filtered against all files staged in git, generated from git diff --staged. This option allows you to override the --staged flag with arbitrary revisions. For example to get a list of changed files between two branches, use --diff="branch1...branch2". You can also read more from about git diff and gitrevisions. This option also implies --no-stash.
• --diff-filter: By default only files that are added, copied, modified, or renamed are included. Use this flag to override the default ACMR value with something else: added (A), copied (C), deleted (D), modified (M), renamed (R), type changed (T), unmerged (U), unknown (X), or pairing broken (B). See also the git diff docs for --diff-filter.
• --no-stash: By default a backup stash will be created before running the tasks, and all task modifications will be reverted in case of an error. This option will disable creating the stash, and instead leave all modifications in the index when aborting the commit. Can be re-enabled with --stash

Configuration

Lint_staged must be configured in your pubspec.yaml

pubspec.yaml example:

lint_staged:
  'lib/**.dart': your-cmd

This config will execute your-cmd with staged dart files passed as arguments.

Filtering files

Linter commands work on a subset of all staged files, defined by a glob pattern. lint_staged uses glob for matching files with the following syntax:

Match any characters in a filename: *

The * character matches zero or more of any character other than /. This means that it can be used to match all files in a given directory that match a pattern without also matching files in a subdirectory. For example, lib/*.dart will match lib/glob.dart but not lib/src/utils.dart.

Match any characters across directories: **

** is like *, but matches / as well. It's useful for matching files or listing directories recursively. For example, lib/**.dart will match both lib/glob.dart and lib/src/utils.dart.

If ** appears at the beginning of a glob, it won't match absolute paths or paths beginning with ../. For example, **.dart won't match /foo.dart, although /**.dart will. This is to ensure that listing a bunch of paths and checking whether they match a glob produces the same results as listing that glob. In the previous example, /foo.dart wouldn't be listed for **.dart, so it shouldn't be matched by it either.

This is an extension to Bash glob syntax that's widely supported by other glob implementations.

Match any single character: ?

The ? character matches a single character other than /. Unlike *, it won't match any more or fewer than one character. For example, test?.dart will match test1.dart but not test10.dart or test.dart.

Match a range of characters: [...]

The [...] construction matches one of several characters. It can contain individual characters, such as [abc], in which case it will match any of those characters; it can contain ranges, such as [a-zA-Z], in which case it will match any characters that fall within the range; or it can contain a mix of both. It will only ever match a single character. For example, test[a-zA-Z_].dart will match testx.dart, testA.dart, and test_.dart, but not test-.dart.

If it starts with ^ or !, the construction will instead match all characters not mentioned. For example, test[^a-z].dart will match test1.dart but not testa.dart.

This construction never matches /.

Match one of several possibilities: {...,...}

The {...,...} construction matches one of several options, each of which is a glob itself. For example, lib/{*.dart,src/*} matches lib/glob.dart and lib/src/data.txt. It can contain any number of options greater than one, and can even contain nested options.

This is an extension to Bash glob syntax, although it is supported by other layers of Bash and is often used in conjunction with globs.

Escaping a character: \

The \ character can be used in any context to escape a character that would otherwise be semantically meaningful. For example, \*.dart matches *.dart but not test.dart.

Syntax errors

Because they're used as part of the shell, almost all strings are valid Bash globs. This implementation is more picky, and performs some validation to ensure that globs are meaningful. For instance, unclosed { and [ are disallowed.

Reserved syntax: (...)

Parentheses are reserved in case this package adds support for Bash extended globbing in the future. For the time being, using them will throw an error unless they're escaped.

Exclude pattern: !

For any files you wish to exclude, use the same glob pattern but prepend it with !

lint_staged:
  'lib/**.dart': your-cmd
  '!lib/**.g.dart': your-cmd

This would include all .dart files, but exclude .g.dart files.

What commands are supported?

Supported are any executables installed locally or globally via pub as well as any executable from your $PATH.

Using globally installed scripts is discouraged, since lint_staged may not work for someone who doesn't have it installed.

lint_staged uses Process.run to locate locally installed scripts.

Pass arguments to your commands separated by space as you would do in the shell. See examples below.

Running multiple commands in a sequence

You can run multiple commands in a sequence on every glob. To do so, pass a list of commands joined with &&. This is useful for running autoformatting tools like dart format or dart analyze but can be used for any arbitrary sequences.

For example:

lint_staged:
  'lib/**.dart': dart format --fix && dart fix --apply

going to execute dart format --fix and if it exits with 0 code, it will execute dart fix --apply on all staged dart files.

Examples

All examples assume you've already set up lint_staged in the pubspec.yaml file and husky in its own config file.

  lint_staged:

In .husky/pre-commit

#!/usr/bin/env sh
. "$(dirname "$0")/_/husky.sh"

dart run lint_staged

Note: we don't pass a path as an argument for the runners. This is important since lint_staged will do this for you.

Automatically fix analyze issues for .dart running as a pre-commit hook

Click to expand

lint_staged:
  'lib/**.dart': dart fix --apply

Automatically fix code format and add to commit

Click to expand

lint_staged:
  'lib/**.dart': dart format --fix

This will run dart format --fix and automatically add changes to the commit.

Frequently Asked Questions

Can I use lint_staged via dart code?

Click to expand

Yes!

import 'package:lint_staged/lint_staged.dart';

try {
  final success = await lintStaged()
  print(success ? 'Linting was successful!' : 'Linting failed!')
} catch (e) {
  print(e);
}

Parameters to lintStaged are equivalent to their CLI counterparts:

const success = await lintStaged({
  allowEmpty: false,
  stash: true,
})

Using with JetBrains IDEs (WebStorm, PyCharm, IntelliJ IDEA, RubyMine, etc.)

Click to expand

Update: The latest version of JetBrains IDEs now support running hooks as you would expect.

When using the IDE's GUI to commit changes with the precommit hook, you might see inconsistencies in the IDE and command line. This is known issue at JetBrains so if you want this fixed, please vote for it on YouTrack.

Until the issue is resolved in the IDE, you can use the following config to work around it:

{
  "husky": {
    "hooks": {
      "pre-commit": "lint_staged",
      "post-commit": "git update-index --again"
    }
  }
}

Thanks to this comment for the fix!

Can I run lint_staged in CI, or when there are no staged files?

Click to expand

Lint_staged will by default run against files staged in git, and should be run during the git pre-commit hook, for example. It's also possible to override this default behaviour and run against files in a specific diff, for example all changed files between two different branches. If you want to run lint_staged in the CI, maybe you can set it up to compare the branch in a Pull Request/Merge Request to the target branch.

Try out the git diff command until you are satisfied with the result, for example:

git diff --diff-filter=ACMR --name-only master...my-branch

This will print a list of added, changed, modified, and renamed files between master and my-branch.

You can then run lint_staged against the same files with:

dart run lint_staged --diff="master...my-branch"

The output of commit hook looks weird (no colors, duplicate lines, verbose output on Windows, …)

Click to expand

Git 2.36.0 introduced a change to hooks where they were no longer run in the original TTY. This was fixed in 2.37.0:

https://raw.githubusercontent.com/git/git/master/Documentation/RelNotes/2.37.0.txt

• In Git 2.36 we revamped the way how hooks are invoked. One change that is end-user visible is that the output of a hook is no longer directly connected to the standard output of "git" that spawns the hook, which was noticed post release. This is getting corrected. (merge a082345372 ab/hooks-regression-fix later to maint).

If updating Git doesn't help, you can try to manually redirect the output in your Git hook; for example:

# .husky/pre-commit

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

if sh -c ": >/dev/tty" >/dev/null 2>/dev/null; then exec >/dev/tty 2>&1; fi

dart run lint_staged