❗️

Go support is alpha stage

We are done implementing the initial core functionality for Pants's initial Go support ([tracked here](🔗)). However, there may be some edge cases we aren't yet handling. There are also some features that are not yet supported like Cgo files and vendoring, which we'd love your input on how to prioritize!

Please share feedback for what you need to use Pants with your Go project by either [opening a GitHub issue](🔗) or [joining our Slack](🔗)!

👍

Why use Pants with Go?

Go's builtin tooling is already excellent! Many projects may be fine only using Go's tooling, although Pants offers some unique benefits:

• A consistent interface for all languages/tools in your repository, such as being able to run `./pants fmt lint check test package`.

• Integration with Git, such as running `./pants --changed-since=HEAD test`.

• Caching, such as caching test results on a per-package basis.

• [Remote execution and remote caching](🔗).

• [Advanced project introspection](🔗), such as finding all code that transitively depends on a certain package.

📘

Example Go repository

Check out [github.com/pantsbuild/example-golang](🔗) to try out Pants's Go support.

🚧

Assumes you're using a single Go module

We do not yet support multiple first-party Go modules. If you are using multiple modules, we invite you to share your use case on https://github.com/pantsbuild/pants/issues/13114. (For example, if you are using a `replace` directive.)

## Initial setup

First, activate the Go backend and set the expected Go version in `pants.toml`:

You can also set `[golang].go_search_paths` to influence where Pants looks for Go, e.g. `["/usr/bin"]`. It defaults to your `PATH`.

Then run [`./pants tailor`](🔗) to generate BUILD files. This will add a `go_mod` target where you have your `go.mod` file, a `go_package` target for every directory with a `.go` file, and a `go_binary` target in every directory where you have `package main`.

Each `go_package` target allows you to set metadata for that directory, such as the `test_timeout` field. However, Pants uses sensible defaults so, usually, you can simply use what was generated by `tailor`.

The `go_mod` target generates a `go_third_party_package` target for each package belonging to the modules declared in your `go.mod`. You will rarely need to interact with these directly, thanks to dependency inference.

You can run `./pants list ::` to see all targets in your project, including generated `go_third_party_package` targets:

🚧

`go.mod` and `go.sum` need to be up-to-date

Pants does not yet update your `go.mod` and `go.sum` for you; it only reads these files when downloading modules. Run `go mod download all` and `go mod tidy` to make sure these files are correct.

### The `embed` directive and `resource` targets

To use the [`embed` directive](🔗), you must first teach Pants about the [files](🔗) with the `resource` / `resources` targets:

1. Add a `resource` or `resources` target with the embedded files in the `source` / `sources` field, respectively.

2. Add that target to the `dependencies` field of the relevant `go_package` target.

For example:

## Package and run binaries

To run a binary, use `./pants run path/to/main_pkg:` (note the colon). You can pass through arguments with `--`, like this:

You can also package your binaries (aka `go build`) by using `./pants package`. `package ::` will build all your project's binaries, whereas `package path/to/main_pkg:` will build only the binary in that directory.

By default, Pants names the binary with the scheme `path.to.directory/target_name`, e.g. `cmd.deploy/bin`. You can set the field `output_path` to use a different name:

## Compile code

To manually check that a package compiles, use `./pants check`:

(Instead, you can simply run `package`, `run`, and `test`. Pants will compile all the relevant packages.)

## Run tests

To run tests, use `./pants test`:

You can pass through arguments with `--`, e.g. `./pants test pkg/deploy: -- -v -run TestFoo`.

### Loose files in tests (`testdata`)

To open files in your tests, use [`file` / `files` targets](🔗) targets and add them as `dependencies` to your `go_package`.

Traditionally in Go, these files are located in the `testdata` directory. However, with Pants, you can place the files wherever you'd like. Pants sets the working directory to the path of the `go_package`, which allows you to open files regardless of where there are in your repository, such as with `os.Stat("../f.txt")`.

### Timeouts

Pants can cancel tests that take too long, which is useful to prevent tests from hanging indefinitely.

To add a timeout, set the `test_timeout` field to an integer value of seconds, like this:

## Gofmt

Gofmt is activated by default when you activate the Go backend. Simply run `./pants fmt` and `./pants lint`:

If you'd like to disable Gofmt, set this:

To only run Gofmt, use `--fmt-only` and `--lint-only`: