Skip to content

Commit

Permalink
docs: Rework Gopkg.toml docs significantly
Browse files Browse the repository at this point in the history 
This was nominally to incorporate prune docs, but it became a broader
rewrite that was really needed, anyway.
  • Loading branch information
@sdboyer
sdboyer committed Jan 24, 2018
1 parent 64d7f61 commit 879f6ca
Show file tree
Hide file tree
Showing 4 changed files with 136 additions and 83 deletions.
2 changes: 1 addition & 1 deletion docs/Gopkg.lock.md
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

199 changes: 121 additions & 78 deletions docs/Gopkg.toml.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,32 @@ title: Gopkg.toml

The `Gopkg.toml` file is initially generated by `dep init`, and is primarily hand-edited. It contains several types of rule declarations that govern dep's behavior:

* [`constraints`](#constraint) and [`overrides`](#override) allow the user to specify which versions of dependencies are acceptable, and where they should be retrieved from.
* [`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively.
* [`metadata`](#metadata) is a user-defined map of key-value pairs that dep will preserve and ignore.
* [`prune`](#prune) settings govern what files and directories can be deemed unnecessary, and thus automatically removed from `vendor/`.
* _Dependency rules:_ [`constraints`](#constraint) and [`overrides`](#override) allow the user to specify which versions of dependencies are acceptable, and where they should be retrieved from.
* _Package graph rules:_ [`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively.
* [`metadata`](#metadata) are a user-defined maps of key-value pairs that dep will ignore. They provide a data sidecar for tools building on top of dep.
* [`prune`](#prune) settings determine what files and directories can be deemed unnecessary, and thus automatically removed from `vendor/`.

Note that because TOML does not adhere to a tree structure, the `required` and `ignored` fields must be declared before any `[[constraint]]` or `[[override]]`.

---
There is a full [example](#example) `Gopkg.toml` file at the bottom of this document. `dep init` will also, by default, generate a `Gopkg.toml` containing some example values, for guidance.

## Dependency rules: `[[constraint]]` and `[[override]]`

## `constraint`
Most of the rule declarations in a `Gopkg.toml` will be either `[[constraint]]` or `[[override]]` stanzas. Both of these types of stanzas allow exactly the same types of values, but dep interprets them differently. Each allows the following values:

A `constraint` provides rules for how a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency) may be incorporated into the dependency graph. dep respects these declarations from the current project's `Gopkg.toml`, as well as that of all dependencies.
* `name` - the import path corresponding to the [source root](glossary.md#source-root) of a dependency (generally: where the VCS root is)
* At most one [version rule](#version-rules)
* An optional [`source` rule](#source)
* [`metadata`](#metadata) that is specific to the `name`'d project

A full example (invalid, actually, as it has more than one version rule, for illustrative purposes) of either one of these stanzas looks like this:

```toml
[[constraint]]
# Required: the root import path of the project being constrained.
name = "github.com/user/project"
# Recommended: the version constraint to enforce for the project.
# Only one of "branch", "version" or "revision" can be specified.
# Note that only one of "branch", "version" or "revision" can be specified.
version = "1.0.0"
branch = "master"
revision = "abc123"
Expand All @@ -37,33 +44,86 @@ A `constraint` provides rules for how a [direct dependency](FAQ.md#what-is-a-dir
system2-data = "value that is used by another system"
```

### `[[constraint]]`

A `[[constraint]]` stanza defines rules for how a [direct dependency](glossary.md#direct-dependency) must be incorporated into the dependency graph. Dep respects these declarations from the current project's `Gopkg.toml`, as well as the `Gopkg.toml` files found in any dependencies.

**Use this for:** having a [direct dependency](FAQ.md#what-is-a-direct-or-transitive-dependency) use a specific branch, version range, revision, or alternate source (such as a fork).

## `override`
### `[[override]]`

An `override` has the same structure as a `constraint` declaration, but supersede all `constraint` declarations from all projects. Only `override` declarations from the current project's `Gopkg.toml` are applied.
An `[[override]]` stanza differs from a `[[constraint]]` in that it applies to all dependencies, [direct](glossary.md#direct-dependency) and [transitive](glossary.md#transitive-dependency), and supersedes all other `[[constraint]]` declarations for that project. However, only overrides from the current project's `Gopkg.toml` are incorporated.

```toml
[[override]]
# Required: the root import path of the project being constrained.
name = "github.com/user/project"
# Optional: specifying a version constraint override will cause all other constraints on this project to be ignored; only the overridden constraint needs to be satisfied. Again, only one of "branch", "version" or "revision" can be specified.
version = "1.0.0"
branch = "master"
revision = "abc123"
# Optional: specifying an alternate source location as an override will enforce that the alternate location is used for that project, regardless of what source location any dependent projects specify.
source = "https://github.com/myfork/package.git"
**Use this for:** Overrides are primarily intended as a way of eliminating disagreements between multiple irreconcilable `[[constraint]]` declarations on a single dependency. However, they will also be your primary recourse if you need to [constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version)

# Optional: metadata about the constraint or override that could be used by other independent systems
[metadata]
key1 = "value that convey data to other systems"
system1-data = "value that is used by a system"
system2-data = "value that is used by another system"
Overrides should be used cautiously and temporarily, when possible.

### `source`

A `source` rule can specify an alternate location from which the `name`'d project should be retrieved. It is primarily useful for temporarily specifying a fork for a repository.

`source` rules are generally brittle and should only be used when there is no other recourse. Using them to try to circumvent network reachability issues is typically an antipattern.

### Version rules

Version rules can be used in either `[[constraint]]` or `[[override]]` stanzas. There are three types of version rules - `version`, `branch`, and `revision`. At most one of the three types can be specified.

#### `version`

`version` is a property of `constraint`s and `override`s. It is used to specify version constraint of a specific dependency. It can be used to target an arbitrary VCS tag, or a semantic version, or a range of semantic versions.

Specifying semantic version ranges can be done using the following operators:

* `=`: equal
* `!=`: not equal
* `>`: greater than
* `<`: less than
* `>=`: greater than or equal to
* `<=`: less than or equal to
* `-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
* `~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
* `^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
* `[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0

You might, for example, include a rule that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "~2.1.0"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.

**Note**: When you specify a version *without an operator*, `dep` automatically uses the `^` operator by default. `dep ensure` will interpret the given version as the min-boundary of a range, for example:

* `1.2.3` becomes the range `>=1.2.3, <2.0.0`
* `0.2.3` becomes the range `>=0.2.3, <0.3.0`
* `0.0.3` becomes the range `>=0.0.3, <0.1.0`

`~` and `=` operators can be used with the versions. When a version is specified without any operator, `dep` automatically adds a caret operator, `^`. The caret operator pins the left-most non-zero digit in the version. For example:
```
^1.2.3 means 1.2.3 <= X < 2.0.0
^0.2.3 means 0.2.3 <= X < 0.3.0
^0.0.3 means 0.0.3 <= X < 0.1.0
```

To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
```toml
[[constraint]]
name = "github.com/pkg/errors"
version = "=0.8.0"
```

**Use this for:** all the same things as a [`constraint`](#constraint), but for [transitive dependencies](FAQ.md#what-is-a-direct-or-transitive-dependency). See [How do I constrain a transitive dependency's version?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version) for more details on how overrides differ from `constraint`s. _Overrides should be used cautiously, sparingly, and temporarily._
#### `branch`

## `required`
Using a `branch` constraint will cause dep to use the named branch (e.g., `branch = "master"`) for a particular dependency. The revision at the tip of the branch will be recorded into `Gopkg.lock`, and almost always remain the same until a change is requested, via `dep ensure -update`.

In general, you should prefer semantic versions to branches, when a project has made them available.

#### `revision`

A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern.

Usually, folks are inclined to pin to a revision because they feel it will somehow improve their project's reproducibility. That is not a good reason. `Gopkg.lock` provides reproducibility. Only use `revision` if you have a good reason to believe that _no_ other version of that dependency _could_ work.

## Package graph rules: `required` and `ignored`

As part of normal operation, dep analyzes import statements in Go code. These import statements connect packages together, ultimately forming a graph. The `required` and `ignored` rules manipulate that graph, in ways that are roughly dual to each other: `required` adds import paths to the graph, and `ignored` removes them.

### `required`

`required` lists a set of packages (not projects) that must be included in Gopkg.lock. This list is merged with the set of packages imported by the current project.
```toml
Expand All @@ -74,7 +134,7 @@ required = ["github.com/user/thing/cmd/thing"]

* Are needed by your project
* Aren't `import`ed by your project, [directly or transitively](FAQ.md#what-is-a-direct-or-transitive-dependency)
* You don't want put in your `GOPATH`, and/or you want to lock the version
* You don't want to put them in your `GOPATH`, and/or you want to lock the version

Please note that this only pulls in the sources of these dependencies. It does not install or compile them. So, if you need the tool to be installed you should still run the following (manually or from a `Makefile`) after each `dep ensure`:

Expand All @@ -92,18 +152,21 @@ export PATH=$GOBIN:$PATH

You might also try [virtualgo](https://github.com/GetStream/vg), which installs dependencies in the `required` list automatically in a project specific `GOBIN`.

## `ignored`

### `ignored`
`ignored` lists a set of packages (not projects) that are ignored when dep statically analyzes source code. Ignored packages can be in this project, or in a dependency.

```toml
ignored = ["github.com/user/project/badpkg"]
```

Use wildcard character (*) to define a package prefix to be ignored. Use this to ignore any package and their subpackages.
Use `*` to define a package prefix to be ignored. This will cause any lexical wildcard match to be ignored, including the literal string prior to the `*`.

```toml
ignored = ["github.com/user/project/badpkg*"]
```

**Use this for:** preventing a package and any of that package's unique dependencies from being installed.
**Use this for:** preventing a package, and any of that package's unique dependencies, from being incorporated in `Gopkg.lock`.

## `metadata`
`metadata` can exist at the root as well as under `constraint` and `override` declarations.
Expand All @@ -118,63 +181,35 @@ system1-data = "value that is used by a system"
system2-data = "value that is used by another system"
```

## `prune`

`prune` defines the global and per-project prune options for dependencies. The options determine which files are discarded when writing the `vendor/` tree.

## Version rules

Version rules can be used in either `[[constraint]]` or `[[override]]` stanzas. There are three types of version rules - `version`, `branch`, and `revision`. At most one of the three types can be specified.
The following are the current available options:
* `unused-packages` indicates that files from directories that do not appear in the package import graph should be pruned.
* `non-go` prunes files that are not used by Go.
* `go-tests` prunes Go test files.

### `version`

`version` is a property of `constraint`s and `override`s. It is used to specify version constraint of a specific dependency. It can be used to target an arbitrary VCS tag, or a semantic version, or a range of semantic versions.

Specifying semantic version ranges can be done using the following operators:

* `=`: equal
* `!=`: not equal
* `>`: greater than
* `<`: less than
* `>=`: greater than or equal to
* `<=`: less than or equal to
* `-`: literal range. Eg: 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5
* `~`: minor range. Eg: ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0
* `^`: major range. Eg: ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0
* `[xX*]`: wildcard. Eg: 1.2.x is equivalent to >= 1.2.0, < 1.3.0
Out of an abundance of caution, dep non-optionally preserves files that may have legal significance.

You might, for example, include a rule that specifies `version = "=2.0.0"` to pin a dependency to version 2.0.0, or constrain to minor releases with: `version = "~2.1.0"`. Refer to the [semver library](https://github.com/Masterminds/semver) documentation for more info.

**Note**: When you specify a version *without an operator*, `dep` automatically uses the `^` operator by default. `dep ensure` will interpret the given version as the min-boundary of a range, for example:

* `1.2.3` becomes the range `>=1.2.3, <2.0.0`
* `0.2.3` becomes the range `>=0.2.3, <0.3.0`
* `0.0.3` becomes the range `>=0.0.3, <0.1.0`

`~` and `=` operators can be used with the versions. When a version is specified without any operator, `dep` automatically adds a caret operator, `^`. The caret operator pins the left-most non-zero digit in the version. For example:
```
^1.2.3 means 1.2.3 <= X < 2.0.0
^0.2.3 means 0.2.3 <= X < 0.3.0
^0.0.3 means 0.0.3 <= X < 0.1.0
```

To pin a version of direct dependency in manifest, prefix the version with `=`. For example:
Pruning is disabled by default. It can be enabled by setting them to `true` at the root level.
```toml
[[constraint]]
name = "github.com/pkg/errors"
version = "=0.8.0"
[prune]
non-go = true
```

### `branch`

Using a `branch` constraint will cause dep to use the named branch (e.g., `branch = "master"`) for a particular dependency. The revision at the tip of the branch will be recorded into `Gopkg.lock`, and almost always remain the same until a change is requested, via `dep ensure -update`.

In general, you should prefer semantic versions to branches, when a project has made them available.
The same prune options can be defined per-project. An addtional `name` field is required and, as with should represent a project and not a package.

### `revision`

A `revision` is the underlying immutable identifier - like a git commit SHA1. While it is allowed to constrain to a `revision`, doing so is almost always an antipattern.

Usually, folks are inclined to pin to a revision because they feel it will somehow improve their project's reproducibility. That is not a good reason. `Gopkg.lock` provides reproducibility. Only use `revision` if you have a good reason to believe that _no_ other version of that dependency _could_ work.
```toml
[prune]
non-go = true

[[prune.project]]
name = "github.com/project/name"
go-tests = true
non-go = false
```
# Example

A sample `Gopkg.toml` with most elements present:
Expand All @@ -190,6 +225,14 @@ ignored = [
[metadata]
codename = "foo"

[prune]
non-go = true

[[prune.project]]
name = "github.com/project/name"
go-tests = true
non-go = false

[[constraint]]
name = "github.com/user/project"
version = "1.0.0"
Expand Down
12 changes: 9 additions & 3 deletions docs/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,11 @@ Deduction is the process of determining the subset of an import path that corres

### Direct Dependency

A project's direct dependencies are those that it imports from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`. If each letter in `A -> B -> C -> D` represents a project, then only `B` is `A`'s direct dependency.
A project's direct dependencies are those that it _imports_ from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`.

If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `B` is `A`'s direct dependency, whereas `C` and `D` are [transitive dependencies](#transitive-dependency) of `A`.

Dep only incorporates the `required` rules from the [current project's](#current-project) `Gopkg.toml`. Therefore, if `=>` represents `required` rather than a standard import, and `A -> B => C`, then `C` is a direct dependency of `B` _only_ when `B` is the current project. Because the `B`-to-`C` link does not exist when `A` is the current project, then `C` won't actually be in the graph at all.

### External Import

Expand Down Expand Up @@ -120,7 +124,7 @@ The remote entities that hold versioned code. Sources are specifically the entit

### Source Root

The portion of an import path that corresponds to the network location of a source. This is similar to [Project Root](#project-root), but refers strictly to the second definition, network-oriented.
The portion of an import path that corresponds to the network location of a source. This is similar to [Project Root](#project-root), but refers strictly to the second, network-oriented definition.

### Sync

Expand All @@ -130,4 +134,6 @@ This concept is explored in detail on [the ensure mechanics reference page](ensu

### Transitive Dependency

A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies. If each letter in `A -> B -> C -> D` represents a project, then `C` and `D` are `A`'s transitive dependencies.
A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies.

If each letter in `A -> B -> C -> D` represents a distinct project containing only a single package, and `->` indicates an import statement, then `C` and `D` are `A`'s transitive dependencies, whereas `B` is a [direct dependency](#transitive-dependency) of `A`.
Loading

0 comments on commit 879f6ca

Please sign in to comment.