Configuration

Also see the tutorial.

Configuration file location

pcg loads the on disk configuration or use the default configuration if none is found.

In decreasing order of preference:

Not checked in: <repo root>/.git/pre-commit-go.yml
Checked in: <repo root>/pre-commit-go.yml
User profile:
- POSIX: ~/.config/pre-commit-go.yml
- Windows: ~/pre-commit-go.yml
Default config. You can generate it with pcg writeconfig

This permits to override settings of a pre-commit-go.yml in a repository by storing an unversionned one in .git.

The pre-commit-go.yml name can be overriden on a per call basis via -c. If -c specifies an absolute path, it is loaded directly. If it can't be found, the default configuration is loaded.

Configuration

The pre-commit-go.yml has the following root keys:

min_version (string): specifies the minimum version of pcg that can be used with this configuration file. When pcg is too old, it bails out with error telling the user to update.
modes (dict, see below): defines all the checks in all modes.
ignore_patterns (list of string): defines the files that should be ignored. By default, vendor, .*, _*, *.pb.go and *_string.go is used which skips files mapped in by vendoring, godep (.e.g. Godeps/_workspace), source files generated by protobuf or stringer.

Sample:

min_version: 0.4.7
modes:
  (...)
ignore_patterns:
- .*
- _*
- *.pb.go

Modes

pcg runs on 4 different modes:

pre-commit: it's the fast tests, e.g. running go test -short, gofmt, etc. Runs checks only on modified files.
pre-push: the slower checks but still bearable for interactive usage. Runs checks only on modified files by what is being pushed.
continuous-integration: runs all checks. It runs on all files and automatically enable verbose mode.
lint: off-by-default checks. This mode is meant to be run manually for checks that trigger false positive by design.

Default checks are meant to be sensible but it can be configured by adding a pre-commit-go.yml configuration file.

Each mode constains a dict of (check type : list of checks with options). This means that check type can be run multiple times with different options. Normally most checks are only specified once per mode.

Sample:

modes:
  pre-commit:
    checks:
      build:
      - build_all: true
        extra_args: []
  continuous-integration:
    checks:
      build:
      - build_all: false
        extra_args: []

Checks

Checks fall in 4 categories:

Go native checks that dot not require any external dependency:
- build builds packages without tests.
- copyright checks files for copyright header.
- gofmt runs gofmt -s.
- test runs tests.
Go checks that are external to the Go standard toolset:
- coverage run tests with coverage. It requires an third party only when using coveralls.io.
- goimports enforces imports order.
Lint checks (e.g. trigger false positives by design):
- errcheck ensures call sites of a function returning error properly handle the error.
- golint includes multiple stylistic rules.
- govet includes multiple stylistic rules.
User specified custom checks.

copyright

copyright enforces that all files have a copyright header. If there are files that need to be not enforced, add them to the global ignored list. It has the following options:

header (string): Header that all files must have.

Sample:

copyright:
- header: |-
    // Copyright 2015 YOUR NAME HERE. All rights reserved.
    // Use of this source code is governed under the Apache License, Version 2.0
    // that can be found in the LICENSE file.

coverage

coverage runs all tests with coverage. Each testable package is run with go test -cover. It has the following options:

use_global_inference (bool): determines if coverage from any unit test should be considered for coverage calculation for all package.
- false means only the package's unit test is used for coverage calculation. Directories with no tests will not be covered at all.
- true means all test packages are run and all coverage information is merged together. This means that package X/Y may create code coverage for package X/Z.
use_coveralls (bool): determines if the data should be sent to https://coveralls.io when run on CI.
global (settings): sets global coverage parameters. The whole coverage must fit these values. This gives a broad range that the code must maintain. This is used when use_global_inference is true.
per_dir_default" (settings): is the default coverage settings per package. It can be overriden by per_dir on a per directory basis. This gives a default range each package should adhere to.
per_dir (settings): defines a list of directories to use different coverage value. The directories must be against the root repository. The paths must be in POSIX format, e.g. with / as directory element separator. The root path is “.”. You can disable coverage for a specific directory by specifying null.

Items marked as settings are struct with the following options:

min_coverage is the minimum test coverage to be generated or the check is considered to fail. The value is in percent.
max_coverage is the maximum test coverage to be generated or the check is considered to fail. This is meant to create a band to detect when coverage increased enough so the values are updated. It is fine to use 100. and be done with it. The value is in percent. If 0, the value is not enforced.

Sample:

coverage:
- use_global_inference: false
  use_coveralls: true
  global:
    min_coverage: 50
    max_coverage: 90
  per_dir_default:
    min_coverage: 50
    max_coverage: 100
  per_dir:
    internal:
      min_coverage: 90
      max_coverage: 100
    third_party: null

custom

Any number of custom checks can be specified in any mode. A custom check can be defined by adding a custom check in one of the modes. Here's an example running sample-pre-commit-go-custom-check on the tree in mode continuous-integration:

Warning: custom is a work in progress and incomplete. Suggestions are appreciated.

modes:
  continous-integration:
    checks:
    - check_type: custom
      display_name: sample-pre-commit-go-custom-check
      description: runs sample-pre-commit-go-custom-check on this repository
      command:
      - sample-pre-commit-go-custom-check
      - check
      check_exit_code: true
      prerequisites:
      - help_command:
        - sample-pre-commit-go-custom-check
        - -help
        expected_exit_code: 2
        url: github.com/maruel/pre-commit-go/samples/sample-pre-commit-go-custom-check

errcheck

errcheck runs errcheck on all packages. It has the following options:

ignores (string): flag to pass to -ignore. See errcheck's help for more information.

Sample:

errcheck:
- ignores: Close

gofmt

gofmt runs gofmt in check mode with code simplification enabled. It is almost redundant with goimports except for -s which goimports doesn‘t implement and gofmt doesn’t require any external package. It has no configuration option. -s is always used.

gofmt:
- {}

goimports

goimports runs goimports in check mode. It has no configuration options.

Sample:

goimports:
- {}

golint

golint runs golint. It is a linting tool, not a check, so it triggers false positives by design. It has the following options:

blacklist (list of string): causes this check to ignore the messages generated by golint that contain one of the string listed here.

Sample:

golint:
- blacklist: []

govet

govet runs go tool vet. It is a linting tool, not a check, so it triggers false positives by design. It has the following options:

blacklist (list of string): causes this check to ignore the messages generated by govet that contain one of the string listed here.

Sample:

govet:
- blacklist:
  - ' composite literal uses unkeyed fields'

test

test runs all tests via go test and since Go 1.4 builds all packages that do not contain tests.

Use the specialized check coverage when -cover is desired. Use multiple test instances to test multiple times with different flags, like with different tags, with or without the race detector, etc. It has the following options:

extra_args (list of string): runs the test with additional arguments like -v, -short, -race, etc.

Sample:

test:
- extra_args:
  - -v
  - -short
  - -race
- extra_args:
  - -v