A small collection of pre commit hooks to format and lint dart code

• Features
• Installation
• Activation
  • Simple dart wrapper
  • When using FVM
  • Using git_hooks
    • Handling the case where the git_hooks is setup in a child folder of the repository
• Configuration
  • Format task
    • Options
  • Analyze Task
    • Options
  • Custom Lint Task
    • Options
  • Flutter Compatibility Task
  • Outdated Task
    • Options
  • Pull Up Dependencies Task
    • Options
  • OSV-Scanner Task
• Documentation

Table of contents generated with markdown-toc

• Provides multiple built in hooks to run on staged files
  • Run dart format
  • Check for invalid imports in test files
  • Run dart analyze
  • Ensure all src files that are publicly visible are exported somewhere
  • Checks if a dart package is compatible with the current stable flutter version
  • Checks if any packages are outdated
  • Checks if any packages have newer versions in the lock file
• Only processes staged files
  • Automatically stages modified files again
  • Fails if partially staged files had to be modified
• Can be used as binary or as library
• Integrates well with most git hook solutions

Simply add dart_pre_commit to your pubspec.yaml (preferably as dev dependency) and run dart pub get (or flutter pub get).

dart pub add --dev dart_pre_commit

To make use of the hooks, you have to activate them first. This package only comes with the hook-code itself, not with a way to integrate it with git as actual hook. Here are a few examples on how to do so:

If this is the only hook you need and you don't really need anything more then "just run the thing", you can simply create a file named tool/setup_git_hooks.dart as detailed below and run dart run tool/setup_git_hooks.dart to initialize the hooks on each of your machines.

import 'dart:io';

Future<void> main() async {
  final preCommitHook = File('.git/hooks/pre-commit');
  await preCommitHook.parent.create();
  await preCommitHook.writeAsString(
    '''
#!/bin/sh
exec dart run dart_pre_commit # specify custom options here
# exec flutter pub run dart_pre_commit # Use this instead when working on a flutter project
''',
  );

  if (!Platform.isWindows) {
    final result = await Process.run('chmod', ['a+x', preCommitHook.path]);
    stdout.write(result.stdout);
    stderr.write(result.stderr);
    exitCode = result.exitCode;
  }
}

When using FVM, you may want to adjust the dart script from above to run dart_pre_commit via FVM:

import 'dart:io';

Future<void> main() async {
  // Add this part
  final useFvm = !arguments.contains('--no-fvm');
  final command = useFvm
      ? 'fvm dart run dart_pre_commit'  // or "fmv flutter pub run dart_pre_commit" for flutter projects
      : 'dart run dart_pre_commit';  // or "flutter pub run dart_pre_commit" for flutter projects

  final preCommitHook = File('.git/hooks/pre-commit');
  await preCommitHook.parent.create();
  await preCommitHook.writeAsString(
    '''
#!/bin/sh
exec $command # use the previously selected command here
''',
  );

  if (!Platform.isWindows) {
    final result = await Process.run('chmod', ['a+x', preCommitHook.path]);
    stdout.write(result.stdout);
    stderr.write(result.stderr);
    exitCode = result.exitCode;
  }
}

The second example uses the git_hooks package to activate the hook. Take the following steps to activate the hook:

1. Add git_hooks as dev dependency to your project
2. Follow the installation instructions here: https://pub.dev/packages/git_hooks#create-files-in-githooks
3. Modify bin/git_hooks.dart to look like the following:

import "package:dart_pre_commit/dart_pre_commit.dart";
import "package:git_hooks/git_hooks.dart";

void main(List<String> arguments) {
  final params = {
    Git.preCommit: _preCommit
  };
  GitHooks.call(arguments, params);
}

Future<bool> _preCommit() async {
  final result = await DartPreCommit.run();
  return result.isSuccess;
}

In cases where your project is in a child folder of the repository ie. Repo/project, when you run DartPreCommit.run(), it'll run from the root of your repository and hence will not be able to find pubspec.yaml file. To handle this case we need to direct the DartPreCommit to run its command from a child folder. To do so, you need to add the following line in the _preCommit() function before we invoke DartPreCommit:

Future<bool> _preCommit() async {
  Directory.current = '/project_sub_directory'; // <--- This line switches the scan directory to a subdirectory
  final result = await DartPreCommit.run();
  return result.isSuccess;
}

The tool follows the zero config principle - this means you can run it without having to configure anything. However, there are a bunch of configuration options if you need to adjust the tool. For simplicity, you can just define them in your pubspec.yaml below the dart_pre_commit key, but it is also possible to move it to a separate file.

The configuration uses the following pattern:

dart_pre_commit:
  exclude: null # special key
  task_1: null
  task_2: false
  task_3: true
  task_4:
    option1: true
    option2: info
    option3:
      - a
      - b
    ...
  ...

Each task corresponds to the configuration of the task with that name. The values can be:

• null (or missing): The default configuration of the task is used
• true or false: Explicitly enable or disable the task. If enabled, still uses the default configuration.
• <config-map>: Explicitly enable the task and use the given configuration in addition to the default configuration. This allows you to overwrite either some or all of the configuration options of a task.

The default tasks and their options, if they have any, are defined follows. However, you can always create your own, custom tasks with customized configurations.

The tool also accepts some command line arguments. Run dart_pre_commit --help to get more information on them.

One special key is the exclude key. If specified, it can either be a simple string or a list of strings, each treated as a Regular Expression to match staged files against. If any staged file is matched by any of those patterns, it will be excluded. Path are tested relative to the scanned dart project root.

Important: This does NOT mean these files will not have any impact on the results, it only means that they are not detected as staged. That leads to per file tasks not being executed on those files and may or may not influence the behavior of repository tasks. For example, the analyze task will still report errors for these files, unless ignore-unstaged-files is set to true.

Task-ID: format
Configurable: Yes
Enabled: Always

This tasks checks all staged files for their formatting and corrects the formatting, if necessary. Internally, it uses the dart format command to accomplish this.

Task-ID: analyze
Configurable: Yes
Enabled: Always

This tasks checks all files for static analysis issues. Internally, this runs dart analyze to check for problems.

Values for error-level:

• error: Only fatal errors are reported
• warning: fatal errors and warnings are reported
• info: fatal errors, warnings and linter issues are reported

Task-ID: custom-lint
Configurable: Yes
Enabled: Only if custom_lint is installed as direct dev dependency

This tasks runs the custom_lint tool on your project to run additional, customized lints, if you have any. This can be very useful, especially for framework packages like riverpod, but also simpler ones like equatable.

Pro-Hint: You can use this customized pub.dev search query to find linter plugins for your packages: https://pub.dev/packages?q=dependency%3Acustom_lint_builder

Values for error-level:

• error: Only fatal errors are reported
• warning: fatal errors and warnings are reported
• info: fatal errors, warnings and linter issues are reported

Task-ID: flutter-compat
Configurable: No
Enabled: Only for pure dart projects

If changes have been made to the pubspec.yaml, this task will try to add this project as dependency to an empty, newly created flutter project to check if all version constraints of all dependencies are compatible with the latest flutter version.

Important: This task requires you to have flutter installed the the flutter binary to be available in your path. If this is not the case, you should explicitly disable the task.

Task-ID: outdated
Configurable: Yes
Enabled: Always

Checks if any packages have available updates. This task always runs, even if no changes to the dependencies have been made. If any package has updates greater than the defined allowed level, the commit will fail.

Values for level:

• major: only check for major package updates
• minor: check for major and minor updates
• patch: check for major, minor and patch updates
• any: check for all updates, except pre-releases

Task-ID: pull-up-dependencies
Configurable: Yes
Enabled: Always

Checks if any dependencies in the pubspec.yaml have version constraints that allow lower versions than the ones resolved in the lockfile. If thats the case, the task will reject the commit. If the lockfile is ignored, this task always runs, otherwise it only runs if changes to the lockfile have been staged.

Task-ID: osv-scanner
Configurable: Yes
Enabled: Only if the osv-scanner binary is found in your PATH

When enabled, the pubspec.lock file is analyzed by the OSV-Scanner for known vulnerabilities in dependent packages. The task will fail in case such dependencies are found.

The documentation is available at https://pub.dev/documentation/dart_pre_commit/latest/. A full example can be found at https://pub.dev/packages/dart_pre_commit/example.