lint_staged 0.1.2

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

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.

If you've written one, please submit a PR with the link to it!

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 popular 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:
     .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 can be configured in ways:

• lint_staged map in your pubspec.yaml

pubspec.yaml example:

lint_staged":
  ".dart": "your-cmd"

This config will execute your-cmd with the list of currently staged files passed as arguments.

So, considering you did git add file1.ext file2.ext, lint_staged will run the following command:

your-cmd file1.ext file2.ext

What commands are supported?

Supported are any executables installed locally or globally via dart 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:
  .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:
  .dart: dart fix --apply

Automatically fix code format and add to commit

Click to expand

lint_staged:
  .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"