github.com/joshdk/godel@v0.0.0-20170529232908-862138a45aee/docs/Configuration.md

Configuration
=============
gödel projects are configured using YML files in the "godel/config" directory. The YML files in that directory specify
the declarative configuration for various different aspects of gödel projects.

Overview
--------

The following is a list of the supported configuration files:

| File | Tasks | Struct definitions |
| ---- | ----- | ------------------ |
| `check.yml` | `check`, `verify` | [apps/okgo/config/config.go] |
| `dist.yml`  | `artifacts`, `build`, `dist`, `products`, `publish`, `run` | [apps/distgo/config/config.go] |
| `exclude.yml` | All | [config/config.go] |
| `format.yml` | `format`, `verify` | [apps/gonform/config/config.go] |
| `imports.yml` | `imports`, `verify` | [vendor/github.com/palantir/checks/gocd/config/config.go] |
| `license.yml` | `license`, `verify` | [vendor/github.com/palantir/checks/golicense/config/config.go] |
| `test.yml` | `test`, `verify` | [apps/gunit/config/config.go] |

check.yml
---------
`check.yml` configures the `check` task. It controls which checks are run and allows the checks to be customized. The
configuration can be used to disable specific checks, specify command-line arguments that should be provided to a check,
or white-list/ignore failure output based on the message, path or name of the file.

The default behavior runs all checks with no custom arguments and no ignored output.

The configuration consists of a top-level map named `checks` where the key is the name of the check (`compiles`,
`deadcode`, `errcheck`, etc.) and the value is the configuration for that check.

Example configuration:

```yml
checks:
  errcheck:
    # specify custom command-line arguments provided to the check when run
    args:
     - "-ignore"
     - "github.com/cihub/seelog:(Info|Warn|Error|Critical)f?"
  golint:
    filters:
     # if "type" is unspecified, defaults to "message". Filters (ignores) output generated by the check if the message
     # matches the provided pattern (regexp).
     - value: "and that stutters"
     # "path" and "name" are also valid types.
     - type: path
       value: "github.com/org/project/file.go"
  outparamcheck:
    # if "skip" is set to true, the check is skipped entirely.
    skip: true
```

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/apps/okgo/config).

dist.yml
--------
`dist.yml` specifies the project structure and controls the behavior of the project and product-related tasks, which
are `artifacts`, `build`, `dist`, `products`, `publish` and `run`.

The configuration consists of a top-level map named `products`, where the key is the name of the product (this is the
name that will be used to specify the product to commands such as `build` and `dist`) and the value is the configuration
for the product. A product is a `main` package meant to be built and distributed.

The `build` configuration for a product specifies parameters related to building the executable, including things such
as the location of the `main` package, the directory in which the executables should be built, parameters that should be
provided to the `build` command and the OS/architecture combinations for which the executable(s) should be built.

The `dist` configuration for a product specifies parameters related to building the distribution artifact for a product.
A distribution artifact is typically a single file (such as a `tgz` or `RPM`) that is generated that contains the
executables built by the `build` task and other supporting files such as default configuration. The output artifacts of
the `dist` task are also the artifacts that are published by the `publish` task. Because creating a distribution can
often involve many customized steps (such as downloading external dependencies), the configuration supports specifying
a bash script that can be run as part of the distribution task to create the distribution for a product.

Example configuration:

```
products:
  distgo:
    build:
      output-dir: ./apps/distgo/build
      main-pkg: ./apps/distgo/main/distgo
      environment:
        CGO_ENABLED: "0"
      version-var: github.com/palantir/godel/cmd/godel.Version
    dist:
      output-dir: ./apps/distgo/dist
      dist-type:
        type: bin
        info:
          omit-init-sh: true
  example:
    build:
      main-pkg: ./example/main/example
      output-dir: example/build/bin
      os-archs:
        - os: linux
          arch: amd64
    dist:
      output-dir: example/build/distributions
      dist-type:
        type: sls
      script: |
               echo $(date +%Y-%m-%d.%H:%M:%S) >> "$DIST_DIR/timestamp.txt"
```

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/apps/distgo/config).

exclude.yml
-----------
`exclude.yml` specifies the files and directories that should be excluded from gödel tasks. This configuration is used
by most of the gödel sub-tasks, so if there are files or directories that should always be excluded from tasks
(generated source, vendored files, etc.), they should be defined here.

### names
Regular expressions that match the names of the files or directories that should be excluded. Uses the
[Go regular expression syntax](https://golang.org/pkg/regexp/).

### paths
Relative file paths (which can contain [globs](https://golang.org/pkg/path/filepath/#Glob)) that match the names of the
files or directories that should be excluded.

### Example

The default file contains the following configuration:

```yml
names:
  - "\\..+"
  - "vendor"
paths:
  - "godel"
```

This configuration excludes all hidden files and directories (those that start with `.`) and all `vendor` directories in
the project and also excludes the `godel` directory located in the root of the project (which is where the configuration
is stored).

format.yml
----------
`format.yml` configures the `format` task. This configuration file can be used to customize the arguments that are
provided to the formatters.

The configuration consists of a top-level map named `formatters`, where the key is the name of the formatter (`gofmt` or
`ptimports`) and the value is the configuration for that formatter. The configuration for the formatter can be used to
customize the command-line flags provided to the formatters.

The default file contains the following configuration:

```yml
formatters:
  gofmt:
    args:
      - "-s"
```

This configuration runs `gofmt` with the `-s` flag to make it simplify the code for the files on which it is run.

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/apps/gonform/config).

imports.yml
-----------
`imports.yml` configures the `imports` task, which runs [`gocd`](https://github.com/palantir/checks/tree/master/gocd/config).
The `imports.yml` file specifies the directories that should be considered "root" directories that should be analyzed by
`gocd` -- directories that are specified as root directories will have a `gocd_imports.json` file produced and verified
for it.

Example configuration:

```yml
root-dirs:
  - pkg
```

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/vendor/github.com/palantir/checks/gocd/config).

license.yml
-----------
`license.yml` configures the `license` task, which runs [`golicense`](https://github.com/palantir/checks/tree/master/golicense).
The `license.yml` file specifies the license header that should be applied to all of the non-excluded `.go` files in the
project. If different files in the project should have different license headers, overrides can also be configured using
this file.

Example configuration:

```
header: |
  // Copyright 2016 Palantir Technologies, Inc.
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //     http://www.apache.org/licenses/LICENSE-2.0
  //
  // Unless required by applicable law or agreed to in writing, software
  // distributed under the License is distributed on an "AS IS" BASIS,
  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  // See the License for the specific language governing permissions and
  // limitations under the License.

custom-headers:
  - name: outparamcheck
    header: |
      // Copyright 2016 Palantir Technologies, Inc. All rights reserved.
      // Licensed under the MIT License. See LICENSE in the project root
      // for license information.

    paths:
      - outparamcheck
  - name: outparamcheck-custom
    header: |
      // Copyright 2013 Kamil Kisiel
      // Modifications copyright 2016 Palantir Technologies, Inc.
      // Licensed under the MIT License. See LICENSE in the project root
      // for license information.

    paths:
      - outparamcheck/exprs
      - outparamcheck/outparamcheck/error.go
      - outparamcheck/outparamcheck/outparamcheck.go
      - outparamcheck/outparamcheck/outparamcheck_test.go
```

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/vendor/github.com/palantir/checks/golicense/config).

test.yml
--------
`test.yml` configures the `test` task. It can be used to specify and define test "tags" that match certain files or
paths in the project. Tests that match a tag are only run when explicitly specified using the `--tags` flag for the
`test` task.

Example configuration:

```
tags:
  integration:
    names:
      - "^integration$"
```

For further documentation on individual fields and parameters, refer to the [config documentation](https://godoc.org/github.com/palantir/godel/apps/gunit/config).