├── .gitignore ├── docs ├── assets │ ├── in-sync.png │ ├── DigbyFlat.png │ ├── lock-back.png │ ├── DigbyShadows.png │ ├── StatusGraph.png │ ├── base-arrows.png │ ├── four-states.png │ ├── func-toggles.png │ ├── DigbyFlatScene2.png │ ├── DigbyScene2Flat.png │ ├── required-arrows.png │ ├── DigbyScene2Shadows.png │ ├── DigbyShadowsScene2.png │ └── annotated-func-arrows.png ├── introduction.zh.md ├── uninstalling.zh.md ├── deduction.zh.md ├── introduction.md ├── uninstalling.md ├── new-project.zh.md ├── env-vars.zh.md ├── installation.zh.md ├── deduction.md ├── installation.md ├── env-vars.md ├── new-project.md ├── the-solver.zh.md ├── Gopkg.lock.zh.md ├── migrating.zh.md ├── glossary.zh.md ├── daily-dep.zh.md ├── the-solver.md ├── Gopkg.lock.md ├── glossary.md ├── failure-modes.zh.md ├── Gopkg.toml.zh.md ├── daily-dep.md ├── ensure-mechanics.zh.md ├── migrating.md ├── Gopkg.toml.md ├── FAQ.zh.md ├── ensure-mechanics.md └── failure-modes.md ├── en.md └── readme.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | fork 4 | source 5 | website 6 | dep -------------------------------------------------------------------------------- /docs/assets/in-sync.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/in-sync.png -------------------------------------------------------------------------------- /docs/assets/DigbyFlat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyFlat.png -------------------------------------------------------------------------------- /docs/assets/lock-back.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/lock-back.png -------------------------------------------------------------------------------- /docs/assets/DigbyShadows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyShadows.png -------------------------------------------------------------------------------- /docs/assets/StatusGraph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/StatusGraph.png -------------------------------------------------------------------------------- /docs/assets/base-arrows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/base-arrows.png -------------------------------------------------------------------------------- /docs/assets/four-states.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/four-states.png -------------------------------------------------------------------------------- /docs/assets/func-toggles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/func-toggles.png -------------------------------------------------------------------------------- /docs/assets/DigbyFlatScene2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyFlatScene2.png -------------------------------------------------------------------------------- /docs/assets/DigbyScene2Flat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyScene2Flat.png -------------------------------------------------------------------------------- /docs/assets/required-arrows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/required-arrows.png -------------------------------------------------------------------------------- /docs/assets/DigbyScene2Shadows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyScene2Shadows.png -------------------------------------------------------------------------------- /docs/assets/DigbyShadowsScene2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/DigbyShadowsScene2.png -------------------------------------------------------------------------------- /docs/assets/annotated-func-arrows.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/dep-zh/master/docs/assets/annotated-func-arrows.png -------------------------------------------------------------------------------- /docs/introduction.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: introduction 3 | title: 入门 4 | --- 5 | 6 | 欢迎! 这是dep的文档,是Go语言的"官方实验"依赖管理工具.Dep是一种主要供开发人员使用的工具,用于支持实际编写和发送代码的工作.它是*不*适用于安装Go软件的最终用户 - 也正是`go get`所做的事情. 7 | 8 | 本网站有指南和参考文件.这些指南是如何用dep实际工作的实用解释,而参考资料提供了对特定主题的更深入的说明.特别值得注意的是[词汇表](glossary.zh.md)- 如果您不熟悉本文档中使用的术语,请务必在那里查看! 9 | 10 | [安装dep](installation.zh.md)后，如果您是第一次使用它,请查看[创建一个新项目](new-project.zh.md).或者,如果您有一个要转换为dep的现有Go项目,[迁移到Dep](migrating.zh.md)可能是你开始的地方. 11 | -------------------------------------------------------------------------------- /docs/uninstalling.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: uninstalling 3 | title: 卸载 Dep 4 | --- 5 | 6 | ## 卸载 7 | 8 | 要卸载`dep`本身,请遵循这些说明,具体取决于您的本来安装方式`dep`. 9 | 10 | ### 如果是curl通过执行`install.sh`脚本来安装`dep` 11 | 12 | 如果你使用`install.sh`安装了`dep`,只需删除已安装的二进制文件即可. 13 | 14 | 在Linux和MacOS上,`install.sh`脚本安装预编译的二进制文件`$GOPATH/bin/dep`.简单就是安全的`rm`已安装`$GOPATH/bin/dep`文件: 15 | 16 | ```sh 17 | $ rm $GOPATH/bin/dep 18 | ``` 19 | 20 | 在Windows上,`install.sh`脚本安装预编译的二进制文件`$GOPATH/bin/dep.exe`.只需删除此文件即可安全卸载`dep`. 21 | 22 | ### 在MacOS上,如果你使用Homebrew安装了`dep` 23 | 24 | 在MacOS上,如果你使用Homebrew安装了`dep`. 卸载`dep`也使用Homebrew: 25 | 26 | ```sh 27 | $ brew uninstall dep 28 | ``` 29 | 30 | ### 在Arch Linux上， 如果你运用`pacman`安装了`dep` 31 | 32 | 卸载`dep`像这样: 33 | 34 | ```sh 35 | $ pacman -R dep 36 | ``` 37 | -------------------------------------------------------------------------------- /docs/deduction.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: deduction 3 | title: 导入路径的推导 4 | --- 5 | 演绎是dep的算法,用于查看导入路径并确定路径中与源根对应的部分.该算法具有一个静态组件,通过该组件,一小组已知的、流行的主机(如GitHub和Bitbucket)可以推导出它们的根: 6 | 7 | - `github.com/golang/dep/gps`>`github.com/golang/dep` 8 | - `bitbucket.org/foo/bar/baz`>`bitbucket.org/foo/bar` 9 | 10 | 由静态演绎支持的主机集与[那些支持`go get`](https://golang.org/cmd/go/#hdr-Remote_import_paths): 11 | 12 | - 吉图布 13 | - 比特桶 14 | - 发射台 15 | - IBM DeVoPS服务 16 | 17 | 此外,DEP还处理[GopkGin](http://gopkg.in)直接使用静态演绎是因为,由于内部实现细节,它也是附加过滤器以适应gopkg的版本化语义的最简单方法.这是好的,如Gopkg.在规则中,映射规则本身是静态的. 18 | 19 | 如果静态逻辑无法识别给定导入路径的根,则算法继续到动态组件:dep对导入路径发出HTTP(S)请求,并且服务器期望发送回嵌入在HTML响应中的根导入路径.同样,这直接模拟了`go get`. 20 | 21 | 导入路径演绎适用于以下所有内容: 22 | 23 | - `import`所有发现的语句`.go`文件夹 24 | - 导入路径[`required`](Gopkg.toml.md#required)列入`Gopkg.toml` 25 | - `name`两者的性质[`[[constraint]]`](Gopkg.toml.md#constraint)和[`[[override]]`](Gopkg.toml.md#override)中的诗节`Gopkg.toml`. 这仅仅是为了验证目的,强制执行这些名称仅对应于项目/源根. 26 | -------------------------------------------------------------------------------- /docs/introduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: introduction 3 | title: Getting Started 4 | --- 5 | 6 | Welcome! This is documentation for dep, the "official experiment" dependency management tool for the Go language. Dep is a tool intended primarily for use by developers, to support the work of actually writing and shipping code. It is _not_ intended for end users who are installing Go software - that's what `go get` does. 7 | 8 | This site has both guides and reference documents. The guides are practical explanations of how to actually do things with dep, whereas the reference material provides deeper dives on specific topics. Of particular note is the [glossary](glossary.md) - if you're unfamiliar with terminology used in this documentation, make sure to check there! 9 | 10 | After [installing dep](installation.md), if you're using it for the first time, check out [Creating a New Project](new-project.md). Or, if you have an existing Go project that you want to convert to dep, [Migrating to Dep](migrating.md) is probably the place to start. 11 | -------------------------------------------------------------------------------- /docs/uninstalling.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Uninstalling Dep 3 | --- 4 | 5 | ## Uninstalling 6 | 7 | To uninstall `dep` itself, follow these instructions, depending on how you installed `dep` originally. 8 | 9 | ### If you installed `dep` by executing the `install.sh` script via curl 10 | 11 | If you installed `dep` using the `install.sh` script, it is safe to simply delete the installed binary file. 12 | 13 | On Linux and MacOS, the `install.sh` script installs a pre-compiled binary to `$GOPATH/bin/dep`. It is safe to simply `rm` the installed `$GOPATH/bin/dep` file: 14 | 15 | ```sh 16 | $ rm $GOPATH/bin/dep 17 | ``` 18 | 19 | On Windows, the `install.sh` script installs a pre-compiled binary to `$GOPATH/bin/dep.exe`. It is safe to simply delete this file to uninstall `dep`. 20 | 21 | ### If you installed `dep` using Homebrew on MacOS 22 | 23 | If you installed `dep` using Homebrew on MacOS, uninstall `dep` also using Homebrew: 24 | 25 | ```sh 26 | $ brew uninstall dep 27 | ``` 28 | 29 | ### If you installed `dep` using `pacman` on Arch Linux 30 | 31 | If you installed `dep` using `pacman` on Arch Linux, uninstall `dep` like so: 32 | 33 | ```sh 34 | $ pacman -R dep 35 | ``` 36 | -------------------------------------------------------------------------------- /docs/new-project.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: new-project 3 | title: 创建一个新项目 4 | --- 5 | 6 | 一旦你有[安装了 dep](installation.md), 我们需要为我们的项目选择一个根目录.这主要是关于导入正确的根路径,以及接下来的`$GOPATH/src`相应目录,定位最后你的项目的落脚点.有四种基本可能性: 7 | 8 | 1. 现在或最终可能与其他 项目/人员 共享或导入的项目.在这种情况下,选择与其预期网络位置的 VCS 根对应的导入路径,例如,`$GOPATH/src/github.com/golang/dep`. 9 | 2. 一个完全本地的项目 - 你无意推送到中央服务器(如 GitHub).在这种情况下,`$GOPATH/src`下面的任何子目录都可以. 10 | 3. 需要存在于大型存储库中的项目,例如公司 monorepo. 可能,但会变得更复杂.(不幸的是,还没有关于此的文档 - 即将推出!) 11 | 4. 将整个 GOPATH 视为一个单独的项目,这$GOPATH/src`是根.Dep[目前不支持此功能](https://github.com/golang/dep/issues/417)- 它需要一个非空的导入路径，来作为项目导入命名空间的根. 12 | 13 | 我们将假设第一种情况,因为它是最常见的情况.创建并移入目录: 14 | 15 | ```bash 16 | $ mkdir -p $GOPATH/src/github.com/me/example 17 | $ cd $GOPATH/src/github.com/me/example 18 | ``` 19 | 20 | 现在,我们将初始化项目: 21 | 22 | ```bash 23 | $ dep init 24 | $ ls 25 | Gopkg.toml Gopkg.lock vendor/ 26 | ``` 27 | 28 | 在像这样的新项目中,两文件和`vendor`目录实际为空. 29 | 30 | 这也是设置版本控制的好时机,例如[git](https://git-scm.com/).虽然 dep 不需要对项目进行版本控制,但它可以更容易地检查正常 dep 操作所做的更改.此外,它基本上是现代软件开发的第一最佳实践! 31 | 32 | 此时,我们的项目已初始化,我们已准备好开始编写代码.你可以打开一个`.go`在编辑器中存档,并开始乱砍.要么,**创建第一个之后`.go`文件**,你可以继续预先填充你的`vendor`，来包含一些您已经知道的项目目录: 33 | 34 | ```bash 35 | $ dep ensure -add github.com/foo/bar github.com/baz/quux 36 | ``` 37 | 38 | 现在你准备继续前进到[每日 Dep](daily-dep.zh.md)! 39 | -------------------------------------------------------------------------------- /docs/env-vars.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: env-vars 3 | title: 环境变量 4 | --- 5 | 6 | dep的行为可以通过一些环境变量修改: 7 | 8 | - [`DEPCACHEAGE`](#depcacheage) 9 | - [`DEPCACHEDIR`](#depcachedir) 10 | - [`DEPPROJECTROOT`](#depprojectroot) 11 | - [`DEPNOLOCK`](#depnolock) 12 | 13 | 环境变量传递给子命令,因此可用于影响vcs(例如`git`)行为. 14 | 15 | * * * 16 | 17 | ### `DEPCACHEAGE` 18 | 19 | 如果设置为了一个[持续时间](https://golang.org/pkg/time/#ParseDuration)(例如.`24h`),它将启用从源存储库缓存元数据: 20 | 21 | - 已发布版本的列表 22 | - 项目的`Gopkg.toml`文件内容,特定版本 23 | - 特定版本的项目包和导入树 24 | 25 | 必须设置持续时间以启用缓存.(在dep的未来版本中,它将默认启用).持续时间用作TTL,但仅用于可变信息,如版本列表.与不可变VCS修订版相关的信息(packages和imports; `Gopkg.toml`声明) 无限期地缓存. 26 | 27 | 缓存存在于`$DEPCACHEDIR/bolt-v1.db`,其中版本号是dep特定数据模式使用的内部相关联编号. 28 | 29 | 该文件可以安全删除; 数据库将根据需要自动重建. 30 | 31 | ### `DEPCACHEDIR` 32 | 33 | 允许用户指定自定义目录, 为dep原始VCS源代码库的[本地缓存](glossary。zh.md#local-cache).默认为`$GOPATH/pkg/dep`. 34 | 35 | ### `DEPPROJECTROOT` 36 | 37 | 如果设置,则此变量的值将被视为[当前的项目](glossary。zh.md#current-project)的[项目根](glossary。zh.md#project-root) ,取代基于GOPATH的推理. 38 | 39 | 主要用于, 如果您不使用标准`go`工具链作为编译器(例如,使用Bazel), , 而在GOPATH之外的操作就没有多大用处. 40 | 41 | ### `DEPNOLOCK` 42 | 43 | 默认情况下,dep创建一个`sm.lock`存档于`$DEPCACHEDIR/sm.lock`，为了防止多个dep进程同时与[本地缓存](glossary。zh.md#local-cache)之交互. 设置此变量将绕过该保护;不会创建任何文件.这对某些文件系统很有用; 特别是VirtualBox共享行为不好的情况. 44 | -------------------------------------------------------------------------------- /docs/installation.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: installation 3 | title: 安装 4 | --- 5 | 6 | 强烈建议您使用 dep 的已发布版本.虽然 tip 从未故意破坏,但其稳定性无法保证. 7 | 8 | ## 二进制安装 9 | 10 | 预编译的二进制文件可在[发布](https://github.com/golang/dep/releases)页.你可以使用`install.sh`脚本，为您的本地平台自动安装一个: 11 | 12 | ```sh 13 | $ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 14 | ``` 15 | 16 | ## MacOS 17 | 18 | 使用 Homebrew 安装，或升级到最新发布的版本: 19 | 20 | ```sh 21 | $ brew install dep 22 | $ brew upgrade dep 23 | ``` 24 | 25 | ## Arch Linux 26 | 27 | 安装`dep`包: 28 | 29 | ```sh 30 | pacman -S dep 31 | ``` 32 | 33 | ## 从源码安装 34 | 35 | 下面的代码片段从源代码安装最新版本的 dep, 并将版本设置为二进制文件，让`dep version`可以按预期工作. 36 | 37 | 请注意,建议不要将此方法用于一般情况. 我们不试图打破 tip,但我们也不保证其稳定性.同时,我们热爱愿意接受实验，并向我们提供快速反馈的用户! 38 | 39 | ```sh 40 | go get -d -u github.com/golang/dep 41 | cd $(go env GOPATH)/src/github.com/golang/dep 42 | DEP_LATEST=$(git describe --abbrev=0 --tags) 43 | git checkout $DEP_LATEST 44 | go install -ldflags="-X main.version=$DEP_LATEST" ./cmd/dep 45 | git checkout master 46 | ``` 47 | 48 | ## 开发 49 | 50 | 如果你想 hacking dep,你可以通过安装`go get`: 51 | 52 | ```sh 53 | go get -u github.com/golang/dep/cmd/dep 54 | ``` 55 | 56 | 请注意,dep 需要一个正常运行的 Go 工作空间和 GOPATH.如果您对 Go 工作区和 GOPATH 不熟悉,请查看[Go 语言文档](https://golang.org/doc/code.html#Organization)并设置您的本地工作区. Dep 的模型可以在没有 GOPATH 的情况下工作, 但我们还没有. 57 | 58 | ## 卸载 59 | 60 | 正在寻找一种卸载方式`dep`? 有一个单独的[卸载页面](uninstalling.zh.md)说明这个问题! 61 | -------------------------------------------------------------------------------- /docs/deduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Import Path Deduction 3 | --- 4 | 5 | Deduction is dep's algorithm for looking at an import path and determining the portion of the path that corresponds to the source root. The algorithm has a static component, by which a small set of known, popular hosts like GitHub and Bitbucket have their roots deduced: 6 | 7 | * `github.com/golang/dep/gps` -> `github.com/golang/dep` 8 | * `bitbucket.org/foo/bar/baz` -> `bitbucket.org/foo/bar` 9 | 10 | The set of hosts supported by static deduction are the same as [those supported by `go get`](https://golang.org/cmd/go/#hdr-Remote_import_paths): 11 | 12 | * GitHub 13 | * Bitbucket 14 | * Launchpad 15 | * IBM DevOps Services 16 | 17 | In addition, dep also handles [gopkg.in](http://gopkg.in) directly with static deduction because, owing to internal implementation details, it is the easiest way of also attaching filters to adapt the versioning semantics of gopkg.in import paths into dep's versioning model. This turns out fine, as gopkg.in's rules mapping rules are themselves entirely static. 18 | 19 | If the static logic cannot identify the root for a given import path, the algorithm continues to a dynamic component: dep makes an HTTP(S) request to the import path, and a server is expected to send back the root import path embedded within the HTML response. Again, this directly emulates the behavior of `go get`. 20 | 21 | Import path deduction is applied to all of the following: 22 | 23 | * `import` statements found in all `.go` files 24 | * Import paths in the [`required`](Gopkg.toml.md#required) list in `Gopkg.toml` 25 | * `name` properties in both [`[[constraint]]`](Gopkg.toml.md#constraint) and [`[[override]]`](Gopkg.toml.md#override) stanzas in `Gopkg.toml`. This is solely for validation purposes, enforcing that these names correspond only to project/source roots. 26 | -------------------------------------------------------------------------------- /docs/installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installation 3 | --- 4 | 5 | It is strongly recommended that you use a released version of dep. While tip is never purposefully broken, its stability is not guaranteed. 6 | 7 | ## Binary Installation 8 | 9 | Pre-compiled binaries are available on the [releases](https://github.com/golang/dep/releases) page. You can use the `install.sh` script to automatically install one for your local platform: 10 | 11 | ```sh 12 | $ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 13 | ``` 14 | 15 | ## MacOS 16 | 17 | Install or upgrade to the latest released version with Homebrew: 18 | 19 | ```sh 20 | $ brew install dep 21 | $ brew upgrade dep 22 | ``` 23 | 24 | ## Arch Linux 25 | 26 | Install the `dep` package: 27 | 28 | ```sh 29 | pacman -S dep 30 | ``` 31 | 32 | ## Install From Source 33 | 34 | The snippet below installs the latest release of dep from source and sets the 35 | version in the binary so that `dep version` works as expected. 36 | 37 | Note that this approach is not recommended for general use. We don't try to 38 | break tip, but we also don't guarantee its stability. At the same time, we love 39 | our users who are willing to be experimental and provide us with fast feedback! 40 | 41 | ```sh 42 | go get -d -u github.com/golang/dep 43 | cd $(go env GOPATH)/src/github.com/golang/dep 44 | DEP_LATEST=$(git describe --abbrev=0 --tags) 45 | git checkout $DEP_LATEST 46 | go install -ldflags="-X main.version=$DEP_LATEST" ./cmd/dep 47 | git checkout master 48 | ``` 49 | 50 | ## Development 51 | 52 | If you want to hack on dep, you can install via `go get`: 53 | 54 | ```sh 55 | go get -u github.com/golang/dep/cmd/dep 56 | ``` 57 | 58 | Note that dep requires a functioning Go workspace and GOPATH. If you're unfamiliar with Go workspaces and GOPATH, have a look at [the language documentation](https://golang.org/doc/code.html#Organization) and get your local workspace set up. Dep's model could lead to being able to work without GOPATH, but we're not there yet. 59 | 60 | ## Uninstalling 61 | 62 | Looking for a way to uninstall `dep`? There's a separate [doc page](uninstalling.md) for that! 63 | -------------------------------------------------------------------------------- /docs/env-vars.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: env-vars 3 | title: Environment Variables 4 | --- 5 | 6 | dep's behavior can be modified by some environment variables: 7 | 8 | * [`DEPCACHEAGE`](#depcacheage) 9 | * [`DEPCACHEDIR`](#depcachedir) 10 | * [`DEPPROJECTROOT`](#depprojectroot) 11 | * [`DEPNOLOCK`](#depnolock) 12 | 13 | Environment variables are passed through to subcommands, and therefore can be used to affect vcs (e.g. `git`) behavior. 14 | 15 | --- 16 | 17 | ### `depcacheage` 18 | 19 | If set to a [duration](https://golang.org/pkg/time/#ParseDuration) (e.g. `24h`), it will enable caching of metadata from source repositories: 20 | 21 | * Lists of published versions 22 | * The contents of a project's `Gopkg.toml` file, at a particular version 23 | * A project's tree of packages and imports, at a particular version 24 | 25 | A duration must be set to enable caching. (In future versions of dep, it will be on by default). The duration is used as a TTL, but only for mutable information, like version lists. Information associated with an immutable VCS revision (packages and imports; `Gopkg.toml` declarations) is cached indefinitely. 26 | 27 | The cache lives in `$DEPCACHEDIR/bolt-v1.db`, where the version number is an internal number associated with a particular data schema dep uses. 28 | 29 | The file can be removed safely; the database will be automatically rebuilt as needed. 30 | 31 | ### `DEPCACHEDIR` 32 | 33 | Allows the user to specify a custom directory for dep's [local cache](glossary.md#local-cache) of pristine VCS source repositories. Defaults to `$GOPATH/pkg/dep`. 34 | 35 | ### `DEPPROJECTROOT` 36 | 37 | If set, the value of this variable will be treated as the [project root](glossary.md#project-root) of the [current project](glossary.md#current-project), superseding GOPATH-based inference. 38 | 39 | This is primarily useful if you're not using the standard `go` toolchain as a compiler (for example, with Bazel), as there otherwise isn't much use to operating outside of GOPATH. 40 | 41 | ### `DEPNOLOCK` 42 | 43 | By default, dep creates an `sm.lock` file at `$DEPCACHEDIR/sm.lock` in order to prevent multiple dep processes from interacting with the [local cache](glossary.md#local-cache) simultaneously. Setting this variable will bypass that protection; no file will be created. This can be useful on certain filesystems; VirtualBox shares in particular are known to misbehave. 44 | -------------------------------------------------------------------------------- /docs/new-project.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Creating a New Project 3 | --- 4 | 5 | Once you have [dep installed](installation.md), we need to pick a root directory for our project. This is primarily about picking the right root import path, and corresponding directory beneath `$GOPATH/src`, at which to situate your project. There are four basic possibilities: 6 | 7 | 1. A project that is now or eventually may be shared with or imported by other projects/people. In this case, pick the import path corresponding to the VCS root of its intended network location, e.g., `$GOPATH/src/github.com/golang/dep`. 8 | 2. An entirely local project - one that you have no intention of pushing to a central server (like GitHub). In this case, any subdirectory beneath `$GOPATH/src` will do. 9 | 3. A project that needs to live within a large repository, such as a company monorepo. This may be possible, but gets more complicated. (Unfortunately, no docs on this yet - coming soon!) 10 | 4. Treat the entire GOPATH as a single project, where `$GOPATH/src` is the root. Dep [does not currently support this](https://github.com/golang/dep/issues/417) - it needs a non-empty import path to treat as the root of your project's import namespace. 11 | 12 | We'll assume the first case, as it's the most common. Create and move into the directory: 13 | 14 | ```bash 15 | $ mkdir -p $GOPATH/src/github.com/me/example 16 | $ cd $GOPATH/src/github.com/me/example 17 | ``` 18 | 19 | Now, we'll initialize the project: 20 | 21 | ```bash 22 | $ dep init 23 | $ ls 24 | Gopkg.toml Gopkg.lock vendor/ 25 | ``` 26 | 27 | In a new project like this one, both files and the `vendor` directory will be effectively empty. 28 | 29 | This would also be a good time to set up a version control, such as [git](https://git-scm.com/). While dep in no way requires version control for your project, it can make inspecting the changes made by normal dep operations easier. Plus, it's basically best practice #1 of modern software development! 30 | 31 | At this point, our project is initialized, and we're ready to start writing code. You can open up a `.go` file in an editor and start hacking away. Or, **after creating your first `.go` file**, you can go ahead and pre-populate your `vendor` directory with some projects that you already know that you'll need: 32 | 33 | ```bash 34 | $ dep ensure -add github.com/foo/bar github.com/baz/quux 35 | ``` 36 | 37 | Now you're ready to move on to [Daily Dep](daily-dep.md)! 38 | -------------------------------------------------------------------------------- /en.md: -------------------------------------------------------------------------------- 1 |

2 |

3 | Build Status 4 | Windows Build Status 5 | 6 |

7 | 8 | ## Dep 9 | 10 | `dep` is a dependency management tool for Go. It requires Go 1.9 or newer to compile. 11 | 12 | `dep` was the "official experiment". The Go toolchain, as of 1.11, has 13 | (experimentally) adopted an approach that sharply diverges from `dep`. As a 14 | result, we are continuing development of `dep`, but gearing work primarily 15 | towards the development of an alternative prototype for versioning behavior in 16 | the toolchain. 17 | 18 | For guides and reference materials about `dep`, see [the documentation](https://golang.github.io/dep). 19 | 20 | ## Installation 21 | 22 | It is strongly recommended that you use a released version. Release binaries are available on the [releases](https://github.com/golang/dep/releases) page. 23 | 24 | On MacOS you can install or upgrade to the latest released version with Homebrew: 25 | 26 | ```sh 27 | $ brew install dep 28 | $ brew upgrade dep 29 | ``` 30 | 31 | On other platforms you can use the `install.sh` script: 32 | 33 | ```sh 34 | $ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 35 | ``` 36 | 37 | It will install into your `$GOPATH/bin` directory by default or any other directory you specify using the `INSTALL_DIRECTORY` environment variable. 38 | 39 | If your platform is not supported, you'll need to build it manually or let the team know and we'll consider adding your platform 40 | to the release builds. 41 | 42 | If you're interested in hacking on `dep`, you can install via `go get`: 43 | 44 | ```sh 45 | go get -u github.com/golang/dep/cmd/dep 46 | ``` 47 | 48 | ## Feedback 49 | 50 | Feedback is greatly appreciated. 51 | At this stage, the maintainers are most interested in feedback centered on the user experience (UX) of the tool. 52 | Do you have workflows that the tool supports well, or doesn't support at all? 53 | Do any of the commands have surprising effects, output, or results? 54 | Let us know by filing an issue, describing what you did or wanted to do, what you expected to happen, and what actually happened. 55 | 56 | ## Contributing 57 | 58 | Contributions are greatly appreciated. 59 | The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers. 60 | The project follows the typical GitHub pull request model. 61 | See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. 62 | Before starting any work, please either comment on an existing issue, or file a new one. 63 | -------------------------------------------------------------------------------- /docs/the-solver.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: the-solver 3 | title: 求解器 4 | --- 5 | dep的核心是约束求解引擎 - a[CDCL](https://en.wikipedia.org/wiki/Conflict-Driven_Clause_Learning)风格的求解器(虽然在"CL"部分点亮),专门针对Go包管理领域量身定制.它生活在`github.com/golang/dep/gps`包,并且是确定有效的,可传递完整的依赖图(也就是说,的内容)的工作`Gopkg.lock`)执行. 6 | 7 | 这个页面最终将详细介绍求解器的机制,但与此同时,还有[旧版解算器的文档](https://github.com/sdboyer/gps/wiki/gps-for-Contributors)仍然足够准确,以提供其行为的粗略图片. 8 | 9 | ## 解决不变量 10 | 11 | 求解器在它返回的每个完整解决方案中保证某些不变量.稍后将详细探讨每个不变量,但它们可归纳如下: 12 | 13 | - 激活中指定的所有规则`[[constraint]]`除非被a取代,否则当前项目和依赖项目中的节将得到满足`[[override]]`当前项目中的节. 14 | - 对于指向给定项目的所有导入路径,所选项目的版本将在相应目录中包含"有效"Go包. 15 | - 如果[导入评论](https://golang.org/cmd/go/#hdr-Import_path_checking)由包指定,任何寻址该包的导入路径都将是注释中指定的形式. 16 | - 对于任何给定的导入路径,该导入路径的所有实例将使用完全相同的外壳. 17 | 18 | 求解器是一种迭代算法,通过可能的依赖图逐个项目地工作.为了选择一个项目,它必须首先证明,就其目前的知识而言,所有上述条件都得到满足.当解算器找不到解决方案时,根据项目版本无法满足上述标准之一来定义失败. 19 | 20 | ### `[[constraint]]`规则 21 | 22 | 如中描述的那样`Gopkg.toml`docs,每个[`[[constraint]]`](Gopkg.toml.md#constraint)节与一个项目相关联,每个节都可以包含这两个节[版本规则](Gopkg.toml.md#version-rules)和a[来源规则](Gopkg.toml.md#source).对于任何给定的项目`P`,所有依赖项`P`其约束规则被"激活"必须表达相互兼容的规则.这意味着: 23 | 24 | - 对于版本规则,所有激活的约束`P`必须[相交](https://en.wikipedia.org/wiki/Intersection_(set_theory)),并且必须至少有一个已发布的版本必须存在于相交空间中.交叉点因版本规则类型而异: 25 | - 对于`revision`和`branch`,它必须是字符串 - 文字匹配. 26 | - 对于`version`,如果字符串不是有效的语义版本,那么它必须是字符串 - 文字匹配. 27 | - 对于`version`作为有效的语义版本范围,交集是每个范围范围内的可能值的标准集合理论交集.没有范围的语义版本被视为单个元素集(例如,`version = "=v1.0.0"`)用于交叉目的. 28 | - 对于`source`规则,具有特定依赖关系的所有项目必须表达字符串相等`source`价值,或没有`source`价值.这允许一个依赖项指定备用`source`,如果他们没有意见,还有其他依赖关系.(注意:在将来的版本中可能会删除此播放行为.) 29 | 30 | 如果当前项目的`Gopkg.toml`有一个[`[[override]]`](Gopkg.toml.md#override)上`P`那么所有`[[constraint]]`声明(包括当前项目中的任何声明)被忽略,从而避免了冲突的可能性. 31 | 32 | #### 激活约束 33 | 34 | 只因为一个`[[constraint]]`上`P`出现在`D`的`Gopkg.toml`并不一定意味着约束`P`被认为是活跃的.一个包裹`P`必须由包中导入`D`- 而如果`D`不是当前项目,然后是其中一个包导入`P`也必须进口. 35 | 36 | 给出以下依赖图,其中`C`是目前的项目: 37 | 38 | ``` 39 | C -> D 40 | C -> P 41 | D/subpkg -> P 42 | ``` 43 | 44 | 即使`C`进口`D`因为`D/subpkg`无法通过`C`进口,任何`[[constraint]]`声明`D`的`Gopkg.toml`' 上`P`不会活跃. 45 | 46 | 进一步解释了这种行为背后的原因[在这个要点](https://gist.github.com/sdboyer/b0813bf2b9dba58a335a85092085472f). 47 | 48 | ### 包装有效期 49 | 50 | dep只对包中的代码进行表面验证,但它确实做了一些.要使包认为有效,必须满足以下三个条件: 51 | 52 | - 必须至少有一个`.go`文件. 53 | - 没有报告错误[`parser.ParseFile()`](https://golang.org/pkg/go/parser/#ParseFile)当被召唤时[`parser.ImportsOnly|parser.ParseComments`](https://golang.org/pkg/go/parser/#Mode)在包目录中的任何文件上. 54 | 55 | 56 | - 包裹不得包含任何物品[当地进口](https://golang.org/pkg/go/build/#IsLocalImport).注意:这不允许标准工具链编译器允许的东西,这通常意味着dep必须支持它.但是,在工具链中已经强烈建议不要使用本地导入,并且跳过它们可以避免dep[点点地狱](https://9p.io/sys/doc/lexnames.html). 57 | 58 | 如果上述任何内容不真实,则包中的代码将被视为格式错误,并且无法在解决方案中使用. 59 | 60 | 如果项目仅包含一些无效的包裹,则不会立即取消其资格;必须导入它们才能使不变量被破坏.因此,如果`P/invalid`是一个包含无效代码的子包,如果是,则仍然可以接受`C -> P`.但是,内部进口`P`也考虑了,所以这个进口链: 61 | 62 | ``` 63 | C -> P 64 | P -> invalid 65 | ``` 66 | 67 | 会导致错误,如`C`导入必然导致导入无效包的包. 68 | 69 | ### 导入评论 70 | 71 | 去1.4介绍[导入评论](https://golang.org/cmd/go/#hdr-Import_path_checking),允许包指定在寻址时必须使用的导入路径.例如,`import "github.com/golang/net/dict"`会指向一个有效的包,但因为[它使用导入注释](https://github.com/golang/net/blob/42fe2e1c20de1054d3d30f82cc9fb5b41e2e3767/dict/dict.go#L7)强制它必须导入为`golang.org/x/net/dict`,dep将拒绝任何试图通过其github地址直接导入它的项目. 72 | 73 | 由于大多数项目的导入注释使用时间一致,因此通常仅在添加新依赖项或尝试恢复旧项目时才会出现此问题. 74 | 75 | > 注意:dep目前不强制执行此规则,但是[它需要](https://github.com/golang/dep/issues/902). 76 | 77 | **修复:**通过修复违规导入路径来更改代码.如果违规导入路径不在当前项目中并且您没有直接控制依赖项,则必须自行分叉并修复它,然后使用`source`指向你的前叉. 78 | 79 | ### 导入路径套管 80 | 81 | 标准的Go工具链编译器[才不是](https://github.com/golang/go/issues/4773) [允许](https://github.com/golang/go/issues/20264)导入路径只有在同一版本中存在的情况下才会有所不同.例如,任何一个`github.com/sirupsen/logrus`要么`github.com/Sirupsen/logrus`很好(GitHub将用户名视为不区分大小写),但它们不能存在于同一个项目中. 82 | 83 | 解算器会跟踪已处理的每个导入路径的已接受案例变体.它看到的任何后续项目都会拒绝为已知导入路径引入仅包含案例的变体. 84 | 85 | **修复:**选择一个套管变体(全部小写通常是正确的答案),并在整个depgraph中强制执行它.因为它必须在所有依赖项中受到尊重,如果您不直接控制它们,这可能需要拉取请求并可能需要分析依赖项. 86 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # golang/dep [![translate-svg]][translate-list] 2 | 3 | 4 | 5 | [explain]: http://llever.com/explain.svg 6 | [source]: https://github.com/chinanf-boy/Source-Explain 7 | [translate-svg]: http://llever.com/translate.svg 8 | [translate-list]: https://github.com/chinanf-boy/chinese-translate-list 9 | 10 | 「 `dep`是 Go 的依赖管理工具.它需要 Go 1.9 或更新版本才能编译. 」 11 | 12 | [中文](./readme.md) | [english](https://github.com/golang/dep) 13 | 14 | --- 15 | 16 | ## 校对 🀄️ 17 | 18 | 19 | 20 | 21 | 22 | 翻译的原文 | 与日期 | 最新更新 | 更多 23 | ---|---|---|--- 24 | [commit] | ⏰ 2018-10-03 | ![last] | [中文翻译][translate-list] 25 | 26 | [last]: https://img.shields.io/github/last-commit/golang/dep.svg 27 | [commit]: https://github.com/golang/dep/tree/22125cfaa6ddc71e145b1535d4b7ee9744fefff2 28 | 29 | 30 | 31 | - [x] readme 32 | - **docs** 33 | - [x] [介绍](./docs/introduction.zh.md) 34 | - [x] [安装](./docs/installation.zh.md) 35 | - [x] [卸载](./docs/uninstalling.zh.md) 36 | - [x] [创建一个新项目](./docs/new-project.zh.md) 37 | - [x] [迁移到 Dep](./docs/migrating.zh.md) 38 | - [ ] [deduction 是 dep 的导入路径推导算法](./docs/deduction.zh.md) 39 | - [ ] [求解器](./docs/the-solver.zh.md) 40 | - [ ] [每日 Dep](./docs/daily-dep.zh.md) 41 | - [ ] [常见问题](docs/FAQ.zh.md) 42 | - [x] [dep 的 环境变量](docs/env-vars.zh.md) 43 | - [ ] [Gopkg.lock](docs/Gopkg.lock.zh.md) 44 | - [ ] [Gopkg.toml](docs/Gopkg.toml.zh.md) 45 | - [x] [Dep 的专门术语](docs/glossary.zh.md) 46 | - [ ] [保障机制](docs/ensure-mechanics.zh.md) 47 | - [ ] [故障模式](docs/failure-modes.zh.md) 48 | 49 | ### 贡献 50 | 51 | 欢迎 👏 勘误/校对/更新贡献 😊 [具体贡献请看](https://github.com/chinanf-boy/chinese-translate-list#贡献) 52 | 53 | ## 生活 54 | 55 | [If help, **buy** me coffee —— 营养跟不上了，给我来瓶营养快线吧! 💰](https://github.com/chinanf-boy/live-need-money) 56 | 57 | --- 58 | 59 |

60 |

61 | Build Status 62 | Windows Build Status 63 | 64 |

65 | 66 | ## Dep 67 | 68 | `dep`是 Go 的依赖管理工具.它需要 Go 1.9 或更新版本才能编译. 69 | 70 | `dep`是"官方实验".Go 工具链,从 1.11 开始,已经(通过实验)采用了一种与`dep`大相径庭的方法.结果是,我们正在继续开发`dep`，但是,考察与开发 dep 的工作主要作为之后开发工具链中，版本化行为的替代原型. 71 | 72 | 有关`dep`的指南和参考资料,查看[文件](https://golang.github.io/dep). 73 | 74 | ## 安装 75 | 76 | 强烈建议您使用已发布的版本.发布二进制文件可在[发布](https://github.com/golang/dep/releases)页. 77 | 78 | 在 MacOS 上,您可以使用 Homebrew 安装或升级到最新发布的版本: 79 | 80 | ```sh 81 | $ brew install dep 82 | $ brew upgrade dep 83 | ``` 84 | 85 | 在其他平台上,您可以使用`install.sh`脚本: 86 | 87 | ```sh 88 | $ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 89 | ``` 90 | 91 | 默认情况下，它将安装到您的`$GOPATH/bin`目录，或您使用指定`INSTALL_DIRECTORY`环境变量的任何其他目录. 92 | 93 | 如果您的平台不受支持,您需要手动构建它或让团队知道,我们会考虑将您的平台添加到发布版本中. 94 | 95 | 如果你对 hacking `dep`感兴趣,你可以通过安装`go get`: 96 | 97 | ```sh 98 | go get -u github.com/golang/dep/cmd/dep 99 | ``` 100 | 101 | ## 反馈 102 | 103 | 非常感谢您的反馈.在此阶段,维护者最感兴趣的是，以工具的用户体验(UX)为中心的反馈.您是否拥有该工具支持的工作流程,或者根本不支持? 任何命令都有令人惊讶的效果,输出或结果吗? 通过提交问题告诉我们,描述您做了什么或想做什么,您期望发生什么,以及实际发生了什么. 104 | 105 | ## 贡献 106 | 107 | 贡献非常感谢.维护人员积极管理 issue 列表,并尝试突出适合新手的问题.该项目遵循典型的 GitHub 拉取请求模型.看[CONTRIBUTING.md](CONTRIBUTING.zh.md)中的更多细节.在开始任何工作之前, 请先评论现有问题,或提交新问题. 108 | -------------------------------------------------------------------------------- /docs/Gopkg.lock.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: Gopkg.lock 3 | title: Gopkg.lock 4 | --- 5 | 这个`Gopkg.lock`文件是由`dep ensure`和`dep init`. 它的输出是[解函数](ensure-mechanics.md#functional-flow)一个项目的依赖图的传递完成的快照,表示为一系列`[[project]]`诗节.这意味着: 6 | 7 | - 一个项目需要编译的每个包 8 | - 加任何[`required`](Gopkg.toml.md#required)包装 9 | - 少任何[`ignored`](Gopkg.toml.md#ignored)包装 10 | 11 | `Gopkg.lock`还包含用于到达最终图的算法和输入的一些元数据.`[solve-meta]`. 12 | 13 | `Gopkg.lock`总是包含一个`revision`对于所有列出的依赖项,作为语义`revision`保证他们是不可改变的.因此,`Gopkg.lock`作为一个可重复的构建列表-只要上游仍然可用,所有依赖关系都可以被精确地再现. 14 | 15 | `Gopkg.lock`是自动生成的;手动编辑它通常是反模式.如果有一个目标你只能通过手工编辑来实现`Gopkg.lock`它至少是一个特征请求,很可能是一个bug. 16 | 17 | ## `[[projects]]` 18 | 19 | 依赖关系图被表示为一系列`[[projects]]`Stasas,每个表示单个依赖项目.一个给定的项目只能在列表中出现一次,并且关于它们表达的版本信息包括所有包含的包——不可能有多个来自不同版本的单个项目的包. 20 | 21 | 这些是可以在A中出现的所有属性.`[[projects]]`节,以及它们是否保证存在/必须存在于一节有效. 22 | 23 | | **Property** | **Always present?** | 24 | | ------------ | ------------------- | 25 | | `name` | Y | 26 | | `packages` | Y | 27 | | `source` | N | 28 | | `revision` | Y | 29 | | `version` | N | 30 | | `branch` | N | 31 | | `pruneopts` | Y | 32 | | `digest` | Y | 33 | 34 | ### `name` 35 | 36 | 节所应用的项目,如其所标识的[项目根](glossary.md#project-root). 37 | 38 | ### `source` 39 | 40 | 如果存在,则指示要从中检索项目的上游源.它具有相同的特性[`source`在里面`Gopkg.toml`](Gopkg.toml.md#source). 41 | 42 | ### `packages` 43 | 44 | DEP中的一个完整目录列表,DEP被确定为构建所必需的. 45 | 46 | 通常,这组包是通过至少一个但与下列所有机制一样多的、发现是包导入图中的参与者的: 47 | 48 | - 在当前项目中[`required`](Gopkg.toml.md#required)列表 49 | - 由当前项目或不同依赖项的包导入 50 | - 由来自该项目内的包导入,该包直接或传递地由来自不同项目的包导入 51 | 52 | ### `pruneopts` 53 | 54 | 一种紧凑编码的形式[指定的修剪选项`Gopkg.toml`](Gopkg.toml.md#prune). 每个字符代表三种可能的规则之一: 55 | 56 | | Character | Pruning Rule in `Gopkg.toml` | 57 | | --------- | ---------------------------- | 58 | | `N` | `non-go` | 59 | | `U` | `unused-packages` | 60 | | `T` | `go-tests` | 61 | 62 | 如果字符存在于`pruneopts`为该项目启用修剪规则.因此,`NUT`指示所有三个修剪规则都是活动的. 63 | 64 | ### `digest` 65 | 66 | 内容的哈希摘要`vendor/`对于这个项目,*之后*修剪规则已被应用.摘要通过冒号分隔的前缀来版本化;字符串是格式的.`:`. 对应于版本1的散列算法是Sh256,如在STDLIB包中实现的那样.`crypto/sha256`. 67 | 68 | 有一些调整将哈希区别于一个天真的文件系统树哈希实现: 69 | 70 | - 忽略了SysLink. 71 | - 行结束归一化到LF(使用类似于GIT的算法),以确保在平台上的摘要不变化. 72 | 73 | ### 版本信息:`revision`,`version`和`branch` 74 | 75 | 为了提供可重复的构建,绝对要求每个项目节包含一个`revision`,无论遇到什么样的约束`Gopkg.toml`文件夹.也有可能正好是其中之一`version`或`branch`将*另外*出席. 76 | 77 | 当另一个存在的时候,`revision`被理解为与此相对应的基础的、不可变的标识符.`version`或`branch` *当时的时候`Gopkg.lock`是书面的*. 78 | 79 | ## `[solve-meta]` 80 | 81 | 本节中包含的元数据告诉我们用于生成`Gopkg.lock`文件.这些是非常粗略的指示符,主要用于在锁可能已经无效时触发对锁的重新评估,以及当其成员正在使用具有潜在微妙不同效果的算法时警告团队. 82 | 83 | 关于"分析器"和"求解器"的更多细节如下,但是版本控制原理是相同的:导致至少一个输入集可接受解决方案集减少的算法更改通常需要版本凸起,而增加该集大小的更改则不需要.然而,这不是一个正式的定义;对于小的更改和bug修复,我们留有判断余地,每次发布最多会遇到一次. 84 | 85 | 通过只在解决方案集收缩(而不是扩展)上碰撞版本,它允许我们避免不断碰撞(这会使跨团队使用dep变得笨拙),同时仍然使得当求解器和版本号匹配时`Gopkg.lock`一个运行版本的DEP,文件中记录的内容可以通过运行版本的规则来接受. 86 | 87 | ### `input-imports` 88 | 89 | 当时出现的所有导入输入的排序列表.`Gopkg.lock`计算.此列表包括两个实际`import`来自项目的声明,以及任何`required`列出的导入路径`Gopkg.toml`,不包括任何`ignored`. 90 | 91 | ### `analyzer-name`和`analyzer-version` 92 | 93 | 分析器是负责解释内容的内部DEP组件.`Gopkg.toml`文件,以及元数据工具从任何工具DEP知道:`glide.yaml`,`vendor.json`等. 94 | 95 | 分析器之所以命名,是因为DEP需要识别它自己的引擎,GPS.`github.com/golang/dep/gps`gps对dep一无所知.当分析器逻辑中的某些东西开始以显著不同的方式处理它已经接受的数据,或者停止接受特定类型的数据时,分析器版本就会发生颠簸.它是*不*当添加对全新类型数据的支持时发生更改. 96 | 97 | 例如,如果dep的分析器停止支持滑动的自动转换,那么就不需要颠簸分析器版本,因为这样做会使*更多*可能的解决方案.添加支持从新工具转换,或更改解释`version`字段在`Gopkg.toml`因此,它只允许指定最小版本,将导致版本颠簸. 98 | 99 | ### `solver-name`和`solver-version` 100 | 101 | 解算器是后面的算法.[解函数](ensure-mechanics.md#functional-flow). 它选择最终出现的所有版本.`Gopkg.lock`通过找到满足所有规则的组合,包括来自`Gopkg.toml`(由分析器供给解算器). 102 | 103 | 之所以命名这个求解器,是因为它和分析器一样,是可插拔的;可以编写一个替代算法,应用不同的规则来实现相同的目标.一个DEP使用"GPS CDCL",命名为[最相似的SAT求解算法的一般类](https://en.wikipedia.org/wiki/Conflict-Driven_Clause_Learning),虽然该算法实际上是专用的、领域特定的.[SMT求解器](https://en.wikipedia.org/wiki/Satisfiability_modulo_theories). 104 | 105 | 版本颠簸的一般原理适用于求解器版本:如果求解器开始强制执行[转到1.4导入路径注释](https://golang.org/cmd/go/#hdr-Import_path_checking)这会导致一个颠簸,因为它只能缩小解集.如果以后要放松这个要求,它就不需要颠簸,因为它只能扩展解决方案集. 106 | -------------------------------------------------------------------------------- /docs/migrating.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: migrating 3 | title: 迁移到 Dep 4 | --- 5 | 6 | 理想情况下,将现有GO项目迁移到Dep是很简单的: 7 | 8 | ```bash 9 | $ cd $GOPATH/src/path/to/project/root 10 | $ dep init 11 | ``` 12 | 13 | 对许多项目来说,这就会起作用.`dep init`将对你的依赖项使用哪些版本进行有意义的猜测,生成理智`Gopkg.toml`,`Gopkg.lock`和`vendor/`，如果你的测试通过，并构建成功,那么你可能已经完成了.(如果是的话,祝贺你! 那你的下一步应该去[每日Dep](daily-dep.zh.md)看看) 14 | 15 | 但一些项目的迁移过程仍会出现困难问题.如果您是第一次尝试dep,这可能会特别令人沮丧,因为您试图同时学习，如何使用dep,和用dep*应*对项目如何管理, 好消息是`dep init`通常就是难度最大的那座山峰; 一旦你跨过它,事情就变得容易多了. 16 | 17 | 本指南的目的是提供足够的信息,让你对`dep init`发生的事情进行推理.这样,你至少可以理解你遇到的是什么样的问题,你可以采取什么步骤来解决这些问题.为此,我们将首先概述一下`dep init`做了啥. 18 | 19 | > 注:第一次运行`dep init`可能需要相当长的时间,因为Dep正在把你所有的依赖者的新克隆创造到一个特殊的位置,`$GOPATH/pkg/dep/sources/`. 这对于Dep的正常操作是必要的,并且在很大程度上仅是一次性成本. 20 | 21 | ## `dep init`力学 22 | 23 | 迁移现有项目时,首要目标是`dep init`尽可能自动化创建一个`Gopkg.toml`.这必然是一个启发性的目标, 因为Dep对于你之前所做的一切可能没有1:1的对应关系.因此,重要的是，期待`dep init`能尽力而为, 进行着自动化迁移. 24 | 25 | `dep init`行为取决于现有代码库中的内容和传递给它的命令参数.然,它总是分两个阶段进行: 26 | 27 | 1. *推理阶段:*从各种来源推理规则和提示,说明使用哪些版本的依赖项. 28 | 2. *求解阶段:*在Dep的模型下设计一个可以接受的解决方案,同时尽可能多地结合上面的推理结论. 29 | 30 | ### 推理阶段 31 | 32 | `dep init`的推理阶段其行为各不相同.默认情况下,`dep init`将查看您的代码库中[其他可以理解的GO包管理工具](https://github.com/golang/dep/tree/master/internal/importers)的元数据文件，以及尝试自动将这些文件中的数据迁移到,dep具有意义的概念中.根据工具和dep找到的特定值,可以将来自工具的元数据视为: 33 | 34 | - 一个提示{**hint**}: dep在求解阶段会尽力遵守的信息,但是如果它找不到遵循提示的解决方案,就会丢弃这些信息. 35 | - 一个规则{**rule**}: 在求解阶段必须遵守的信息,最终将作为一个`[[constraint]]`出现在`Gopkg.toml`文件. 如果求解阶段不能找到满足规则的解决方案,那么它会失败，且带有一个消息. 36 | 37 | 有三种情况可以导致Dep不做任何基于工具的推理: 38 | 39 | - 您的项目不使用包管理工具 40 | - Dep还不支持你使用的工具 41 | - 你告诉它不要,通过`dep init -skip-tools` 42 | 43 | 在基于工具的推理完成之后,Dep通常会进入求解阶段.但是,如果用户传递`-gopath`标记,Dep将首先尝试通过检查当前项目中包含的GOPATH，来填充从工具元数据中提取的推理中的任何漏洞. 仅仅填充从GOPATH收集到的提示,它们永远不会取代工具元数据的推理. 但如果你想把GOPATH完全负责,就需要通过这两个标志:`dep init -skip-tools -gopath`. 44 | 45 | 一旦Dep编译了它的推理集合,它就开始求解. 46 | 47 | ### 求解阶段 48 | 49 | 一旦推理阶段完成,Dep已装配的规则和提示将被传递给[求解器](the-solver.zh.md)，让求解器设计传出完整的depgraph,最终将被记录为`Gopkg.lock`. `dep ensure`也是相同的求解过程. 并且成功完成它, 意味着dep已经找到遵守所有推理规则的依赖版本的组合,以及尽可能多的推理提示. 如果解决成功,那么辛苦的工作就完成了; 剩下的大部分是写出`Gopkg.toml`,`Gopkg.lock`和`vendor/`. 50 | 51 | 求解器返回一个解决方案,该解决方案本身就是[存储在一个`Gopkg.lock`中的数据](https://godoc.org/github.com/golang/dep#Lock)的[一个画像](https://godoc.org/github.com/golang/dep/gps#Solution), 是整个依赖图的传递完整、可再现的快照. 从一个解决方案写出`Gopkg.lock`，只不过是一个复制和编码{**copy-and-encode**}操作,和写`vendor/`时，将指定的解决方案中列出的每一个项目，放到指定的修订中.这与`dep ensure`的行为完全一样. 52 | 53 | `Gopkg.toml`有点不同. 不能保证为你项目的所有(甚至任何)依赖推理出规则,但我们仍然希望填充`Gopkg.toml`带有些许理智的值. 因此,对于未推理规则的任何依赖项,dep检查解决方案，以查看最终选择了什么版本,并基于此创建约束: 54 | 55 | - 如果一个分支,像`master`，在解决方案中被选中。`branch: "master"`将出现在`Gopkg.toml`. 56 | - 如果选择了符合语义版本的版本,像`v1.2.0`,然后将指定为最小版本:`version: "v1.2.0"`. 57 | - 如果只选择原始修订版,则`Gopkg.toml`没有任何内容. 而Dep确实约束了`Gopkg.toml`中的`revision: "…"`，因为使用它们被认为是反模式, 所以dep不会自动创建它们,以避免隐含地鼓励使用它们. 58 | 59 | ## 处理失败 60 | 61 | 首先,确保你`dep init`带`-v`.这将提供更多的信息. 62 | 63 | `dep init`，通常来说与Dep一样,它既有硬模式又有软故障模式.硬故障导致进程挂起或完全中止,且没有任何东西写入磁盘. 软故障可能包括或不包括警告,但最终写入`Gopkg.toml`,`Gopkg.lock`和`vendor/`-只是都不是你想要的而已。在我们深入研究这些内容之前,让我们来设置一些上下文. 64 | 65 | 虽然dep贡献者已经投入了巨大的努力来创建到dep的自动迁移路径,但是这些路径仅是尽力而为并且不精确. 从其他工具或GOPATH转换为完全保真并不总对的. dep是一个自以为是的工具,具有相应的自以为是的模型,并且该模型有时确实与其他工具有根本的不同.有时这些模型不匹配导致硬故障,有时是软的,总是充满不确定性. 66 | 67 | 因为这些都是深层次的假设,他们的症状可以是多样的和令人惊讶的.记住这些假设可以帮你节省一些时间. 68 | 69 | - 1. Dep不允许嵌套`vendor/`目录;它在项目的根目录下，将所有依赖项平铺到`vendor/`目录的最顶层. 这是Dep模型的基础,不能被禁用. 70 | - 2. Dep整体控制`vendor`, 并且将吹走任何偏离其上游源Dep选择的手动更改或添加. 71 | - 3. Dep要求来自给定项目/仓库的所有包都在同一版本. 72 | - 4. dep通常不关心GOPATH上的内容; 它只处理源自远程网络位置的项目.(提示推理是唯一的例外;一旦解决阶段开始,GOPATH——以及您对代码所做的任何自定义更改——将被忽略.) 73 | - 5. Dep通常倾向于语义版本标记的发布到分支(当没有给出任何附加规则)时.这是从`go get`还有其他一些工具的"默认分支"模型的重大转变.它可以导致Dep做出惊吓的选择，只因无法推理一个规则的依赖. 74 | - 6. Dep假定所有生成的代码都存在,并且已经提交给源. 75 | 76 | 迄今为止,很少有项目能够找到一种合理的方法来适应这些要求. 如果你不能想出如何使你的项目适合,请提交一个问题-虽然dep必然不能适应每一个现有的方法,它的目标是定义规则,所有的Go项目可以合理地适应. 77 | 78 | ### 硬故障 79 | 80 | 所有的硬故障模式在参考文献中被广泛地覆盖.[失效模式](failure-modes.zh.md). 81 | 82 | 因为求解器及其所有可能的故障都是相同的.`dep init`以及`dep ensure`有一个单独的部分来理解和处理它们:[解决故障处理](failure-modes.zh.md#solving-failures). `dep init`这可能更棘手，然而, 其实许多补救措施需要调整`Gopkg.toml`. 83 | 84 | 不幸的是,当`dep init`失败时, 它不会写出部分`Gopkg.toml`.这是一个已知的、关键的问题,[我们有一个开放的问题(需要帮助!)](https://github.com/golang/dep/issues/909). 85 | 86 | 同时,如果您遇到的特定错误确实需要`Gopkg.toml`调整一下, 不幸的是, 你需要手动完成`dep init`操作: 创建一个空[`Gopkg.toml`](Gopkg.toml.md), 并用手工填充规则. 在重排之前,确保你已经`dep init`具有推理参数的各种组合(`-skip-tools`和`-gopath`), 看看他们能不能给你点东西. 87 | 88 | ### 软故障 89 | 90 | 软故障就是`dep init`似乎干净地退出的这种情况,但随后`go build`或`go test`失败.Dep的软故障通常比细微错误大得多,例如,当您尝试构建时,类型错误发生爆炸,因为选择了一些依赖的错误版本. 91 | 92 | 如果你遇到这样的问题,`dep status`是您的第一个诊断步骤;它将报告为您的所有依赖项选择了哪些版本.很显然,依赖关系仅仅是从build或test错误消息中产生的问题.如果没有,比较`dep status`列出与前一个工具记录的版本,找出差异. 93 | 94 | 一旦确定了有问题的依赖关系,下一步就是对它们, 在`Gopkg.toml`进行适当的控制.. 95 | 96 | 对于下面的每一项, 都假设在提出建议的改变之后,您应该运行`dep ensure`.如果失败,请教[解决故障处理](<>). 97 | 98 | - 如果`[[constraint]]`错了被推理为你的直接依赖之一,改变它.然后,向Dep提交一个问题(请!)-而`dep init`可以选择省略约束,错误地转换可以认为是一个bug. 99 | - 如果您的传递依赖项位于错误的版本中,则把`[[override]]`定义逼到你需要的版本. 100 | - 如果您需要的版本是特定的Git提交,那么最好在那个项目的`Gopkg.lock`, 手动更改`revision`期望的散列,然后放弃`version`或`branch`字段(如果有的话). 101 | - 如果你的一个直接依赖是错误的版本， 并且`Gopkg.toml`已没有`[[constraint]]`关于它, 那,定义一个合适的. 102 | - 与传递依赖关系一样,如果需要的版本是特定的Git提交,则最好对`Gopkg.lock`手动操作. 103 | 104 | 希望这些信息足以帮助您通过项目迁移到dep.如果没有,请随时提交问题,或者加入我们[#vendor on the Gopher's slack](https://gophers.slack.com/messages/C0M5YP9LN)寻求帮助! 105 | -------------------------------------------------------------------------------- /docs/glossary.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: glossary 3 | title: 术语 4 | --- 5 | 6 | Dep使用一些专门术语.在这里学习! 7 | 8 | 9 | 10 | * [Atom](#atom) 11 | * [Cache lock](#cache-lock) 12 | * [Constraint](#constraint) 13 | * [Current Project](#current-project) 14 | * [Deducible](#deducible) 15 | * [Deduction](#deduction) 16 | * [Direct Dependency](#direct-dependency) 17 | * [External Import](#external-import) 18 | * [GPS](#gps) 19 | * [Local cache](#local-cache) 20 | * [Lock](#lock) 21 | * [Manifest](#manifest) 22 | * [Metadata Service](#metadata-service) 23 | * [Override](#override) 24 | * [Project](#project) 25 | * [Project Root](#project-root) 26 | * [Solver](#solver) 27 | * [Source](#source) 28 | * [Source Root](#source-root) 29 | * [Sync](#sync) 30 | * [Transitive Dependency](#transitive-dependency) 31 | * [Vendor Verification](#vendor-verification) 32 | 33 | 34 | 35 | * * * 36 | 37 | ### Atom 38 | 39 | > 原子 40 | 41 | 原子是特定版本的源.在实践中,这意味着一个[项目根](#project-root)的二元组和版本,例如`github.com/foo/bar@master`. 原子主要是内部的. [求解器](#solver)这个词在别处很少使用. 42 | 43 | ### Cache lock 44 | 45 | > 缓存锁定 46 | 47 | 也就是"缓存锁定文件".一个名为`sm.lock`的文件, 用于确保同时只有一个Dep过程运行在[本地缓存](#local-cache), Dep当前对多个进程进行访问本地缓存的设计是不安全的. 48 | 49 | ### Constraint 50 | 51 | > 约束 52 | 53 | 约束既有狭义又有较松散的含义.狭义指的是`Gopkg.toml`中[`[[constraint]]`](Gopkg.toml.zh.md#constraint)字段. 然而,在某些上下文中,这个词可以更宽泛地用来指应用规则，和要求依赖管理的想法. 54 | 55 | ### Current Project 56 | 57 | > 当前项目 58 | 59 | Dep正在运作的项目 - 写进项目的`Gopkg.lock`, 并填充它的`vendor`目录. 60 | 61 | 也称为"根项目". 62 | 63 | ### Deducible 64 | 65 | > 可推断的 66 | 67 | 简单说明, 对于给定的导入路径,导入路径的[推导](#deduction)方式，是否成功返回. 也经常使用"Undeducible-不可推断",来引用推导失败的导入路径. 68 | 69 | ### Deduction 70 | 71 | > 推导 72 | 73 | 推导是查实, 与源主目录的对应导入路径的子集的过程. 某些模式是先验已知的(静态的); 其他模式必须通过网络请求(动态)来发现. 参见参考文献[导入路径推导](deduction.zh.md)具体情况. 74 | 75 | ### Direct Dependency 76 | 77 | > 直接依赖 78 | 79 | 一个项目的直接依赖是*imports*其一个或多个包,或包含在`Gopkg.toml`的[`required`](Gopkg.toml.zh.md#required)中. 80 | 81 | 如果`A -> B -> C -> D`每个字母都在表示仅包含单个包的不同项目,以及`->`是导入语句,那`B`是`A`是直接依赖,而`C`和`D`是`A`的[传递依赖](#transitive-dependency). 82 | 83 | [当前项目](#current-project) 的 `Gopkg.toml`，Dep只包含了`required`规则. 因此,`=>`就代表`required`, 而不是一个标准的进口, `A -> B => C`，说`C`是`B`的直接依赖 *只在*`B`是当前项目的情况下. 因为`A`是当前项目时, `B`-到-`C`的链接不存在, 那`C`实际上不会出现在图表中. 84 | 85 | ### External Import 86 | 87 | > 外部进口 88 | 89 | 一个`import`语句,指向项目中的包,而不是它的源包.例如,包`github.com/foo/bar`的一个`import`如果它指向任何*其他*东西,将被认为是外部输入. 除非指向stdlib或`github.com/foo/bar/*`. 90 | 91 | ### GPS 92 | 93 | > Go packaging solver 94 | 95 | "Go包装解决方案"的缩写,它是[Dep中的库风格包的子树](https://godoc.org/github.com/golang/dep/gps)， 是Dep建立的发动机. 最常被称为"GPS". 96 | 97 | ### Local cache 98 | 99 | > 本地缓存 100 | 101 | Dep维护自己的、原始的上游的源集合(一般是,Git存储库克隆).这是与`$GOPATH/src`分开的.这样就没有维护`$GOPATH`磁盘状态的义务.因为Dep经常需要改变磁盘状态才能完成它的工作. 102 | 103 | 默认情况下,本地缓存位于`$GOPATH/pkg/dep`. 如果你有多个`$GOPATH`路径,Dep将使用进程的工作目录的逻辑父对象.或者,可以通过[`DEPCACHEDIR`环境变量](env-vars.zh.md#depcachedir)设置. 104 | 105 | ### Lock 106 | 107 | > 锁 108 | 109 | 一个通用术语,用于许多语言包管理器,Dep保持的`Gopkg.lock`文件的信息类型. 110 | 111 | ### Manifest 112 | 113 | > 主内容 114 | 115 | 一个通用术语,用于许多语言包管理器,Dep保持的`Gopkg.toml`文件的信息类型. 116 | 117 | ### Metadata Service 118 | 119 | > 元数据服务 120 | 121 | 在HTTP服务,当它接收到包含`go-get=1`查询字符串的HTTP请求时,将请求的路径部分解释为导入路径,并通过在HTML中嵌入数据来进行响应.``指示底层源根的类型和URL的标记.这是动态的服务器端组件.[推导](#deduction). 122 | 123 | 元数据服务的行为定义在[远程导入路径：Go命令官方文档](https://golang.org/cmd/go/#hdr-Remote_import_paths). 124 | 125 | 各种表示为"HTTP元数据服务","`go-get`HTTP元数据服务","`go-get`服务等. 126 | 127 | ### Override 128 | 129 | > 重写 130 | 131 | 重写是`Gopkg.toml`的[`[[override]]`](Gopkg.toml.md#override). 132 | 133 | ### Project 134 | 135 | > 项目 136 | 137 | 一个项目是一个Go包的树.不能嵌套项目.见[项目根](#project-root)有关如何确定树的根的更多信息. 138 | 139 | ### Project Root 140 | 141 | > 项目根 142 | 143 | 项目的根导入路径.项目根定义为: 144 | 145 | - 对于当前项目,`Gopkg.toml`文件定义项目根目录的位置 146 | - 对于依赖关系,网络[来源](#source)(VCS存储库)的根被视为项目根. 147 | 148 | 这些通常是同一个,但并不总是如此.当使用Dep内部的monorepo,个重`Gopkg.toml`文件可能存在于离散项目的子路径中, 将每个导入路径指定为项目根目录. 当直接在这些项目上工作时,这很好.但是,如果存储库中没有哪个项目试图导入monorepo, dep会将monorepo视为一个大型项目,那这根目录就成为了**Project Root**;它将忽略任何和所有子目录中的`Gopkg.toml`文件. 149 | 150 | 这也可以称为"导入根"或"根导入路径". 151 | 152 | ### Solver 153 | 154 | > 求解器 155 | 156 | "求解器"是对特定于域的SAT求解器的借鉴. [gps](#gps). 更多细节可看其[参考页](the-solver.zh.md). 157 | 158 | ### Source 159 | 160 | > 来源 161 | 162 | 保存版本代码的远程实体. 来源是包含代码的实体,而不是代码本身的任何特定版本. 163 | 164 | "来源"被用来代替"VCS",因为Go包管理工具将很快学会使用，除VCS系统之外的系统. 165 | 166 | ### Source Root 167 | 168 | > 源根 169 | 170 | 导入路径的一部分,对应于来源的网络位置.这类似于[项目根](#project-root),但严格地引用第二个,面向网络的定义. 171 | 172 | ### Sync 173 | 174 | > 同步 175 | 176 | Dep是被设计成, 围绕四个状态，定义良好的关系来的: 177 | 178 | 1. `.go`文件的`import`语句 179 | 2. `Gopkg.toml` 180 | 3. `Gopkg.lock` 181 | 4. `vendor`目录 182 | 183 | 如果该关系的任何方面未实现(例如,有一个`import`没有反映在`Gopkg.lock`,或者`vendor`一个缺少的项目, 那Dep就认为该项目"不同步". 184 | 185 | 这一概念在[保障机制](ensure-mechanics.zh.md#staying-in-sync). 186 | 187 | ### Transitive Dependency 188 | 189 | > 传递依赖 190 | 191 | 项目的传递依赖项是指它不导入自身,而是通过其依赖项之一，导入的依赖项. 192 | 193 | 如果`A -> B -> C -> D`每个字母都表示仅包含单个包的不同项目,以及`->`是导入语句,那`C`和`D`是`A`的传递依赖关系,而`B`是`A`的一个[直接依赖](#transitive-dependency). 194 | 195 | ### Vendor Verification 196 | 197 | > 供应商验证 198 | 199 | Dep保证，`vendor/`是准确地的包含期待的代码, 它通过对每个项目的内容进行哈希，并存储[Gopkg.lock 摘要](Gopkg.lock.zh.md#digest)结果. 这个摘要是在应用修剪规则*之后*计算出来的. 200 | 201 | 摘要用于确定, `vendor/`的内容是否需要在`dep ensure`运行期间重生成,还有`dep check`也使用它来确定`Gopkg.lock`和`vendor/`是否在[同步](#sync). 这个[`noverify`](Gopkg.toml.zh.md#noverify)列在`Gopkg.toml`，可以用来绕过大多数这些验证行为. 202 | -------------------------------------------------------------------------------- /docs/daily-dep.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: daily-dep 3 | title: 每日 Dep 4 | --- 5 | 本指南介绍了dep的日常使用.但是,如果你还没有设置Go项目,那么就可以了[创建一个新项目](new-project.md)第一. 6 | 7 | Dep是您在正常Go开发过程中经常使用的工具.定期,但简单地说 - 依赖管理永远不是我们想要花费时间或精力的地方!为了与Go的最小化旋钮的理念保持一致,dep具有稀疏的界面;只有两个命令可能会定期运行: 8 | 9 | - `dep ensure`是主要的workhorse命令,并且是唯一一个更改磁盘状态的命令. 10 | - `dep status`报告您的项目状态,以及Go软件项目的可见范围. 11 | 12 | 本指南主要以中心为中心`dep ensure`,因为这是您运行以对项目进行更改的命令.该[模型和机制](ensure-mechanics.md)参考文档详细说明了如何在引擎盖下工作,如果您遇到困惑,则值得一读`dep ensure`行为(或只是好奇!). 13 | 14 | ## 基本 15 | 16 | 让我们从单词开始吧! 17 | 18 | Dep的主要命令是`dep ensure`.动词是"确保"暗示该动作不仅仅是一些单独的,离散的动作(比如添加一个依赖),而是强制执行某种更广泛的保证.如果我们想表达的话`dep ensure`保证作为一个句子,它将是这样的: 19 | 20 | > 嘿dep,请确保[我的项目](glossary.md#current-project)是[同步中](glossary.md#sync)那个[`Gopkg.lock`](Gopkg.lock.md)满足我项目中的所有导入以及中的所有规则[ `Gopkg.toml`](Gopkg.toml.md), 然后`vendor/`包含什么`Gopkg.lock`说它应该." 21 | 22 | 正如叙述所示,`dep ensure`是一个整体运作.而不是提供一系列连续运行的命令,逐步实现某些最终状态,每次运行`dep ensure`根据项目的当前状态提供安全,完整且可重现的依赖关系集.你可能会想象一下`dep ensure`有点像青蛙,从一个百合垫跳到下一个. 23 | 24 | ## 运用`dep ensure` 25 | 26 | 你有四次跑步`dep ensure`: 27 | 28 | - 添加新依赖项 29 | - 更新现有依赖项 30 | - 要在项目中第一次导入包后删除,要么删除项目中包的最后一次导入 31 | - 赶上改变规则`Gopkg.toml` 32 | 33 | 如果您不确定进口是否有变化或`Gopkg.toml`规则,运行`dep check`.它会告诉你项目中的不同步.如果有任何不同步,请运行`dep ensure`将它带回来. 34 | 35 | 让我们探讨这些时刻.要发挥作用,你需要`cd`进入一个已经建立的项目`dep init`.如果您还没有这样做,请查看指南[新项目](new-project.md)和[迁移](migrating.md). 36 | 37 | ### 添加新的依赖项 38 | 39 | 假设我们想引入新的依赖关系`github.com/pkg/errors`.这可以通过一个命令完成: 40 | 41 | ```bash 42 | $ dep ensure -add github.com/pkg/errors 43 | ``` 44 | 45 | > 很像git,`dep status`和`dep ensure`也可以从项目根目录的任何子目录运行(由a的存在决定`Gopkg.toml`文件). 46 | 47 | 这应该成功,导致更新`Gopkg.lock`和`vendor/`目录,以及为.注入最佳猜测版本约束`github.com/pkg/errors`进入我们的`Gopkg.toml`.但是,它也会报告一个警告: 48 | 49 | ```bash 50 | "github.com/pkg/errors" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/. 51 | If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/. 52 | ``` 53 | 54 | 正如警告所示,你应该介绍一个`import "github.com/pkg/errors"`在你的代码中,越快越好.如果你不这样做,以后再做`dep ensure`run会将新添加的依赖项解释为未使用,并自动将其删除`Gopkg.lock`和`vendor/`.这也意味着如果要一次添加多个依赖项,则需要在单个命令中执行此操作,而不是一个接一个地执行: 55 | 56 | ```bash 57 | $ dep ensure -add github.com/pkg/errors github.com/foo/bar 58 | ``` 59 | 60 | Dep以这种方式工作,因为它将通过对项目代码的静态分析发现的import语句视为必须存在哪些依赖项的规范指示符.这个选择确实增加了一些痛苦,但它减少了摩擦并在其他地方自动清理.权衡! 61 | 62 | 当然,鉴于这种模式,你没有*不得不*使用`dep ensure -add`添加新的依赖项 - 您也可以添加适当的依赖项`import`代码中的语句,然后运行`dep ensure`.但是,这种方法并不总能很好地发挥作用[`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports),也不会附加一个`[[constraint]]`成`Gopkg.toml`.尽管如此,它有时也很有用,通常用于快速迭代和袖口试验. 63 | 64 | 该[确保机械部分`-add`](ensure-mechanics.md#add)有一个更彻底的探索,包括一些方法`dep ensure -add`的行为会根据项目的状态而略有不同. 65 | 66 | ### 更新依赖项 67 | 68 | 理想情况下,将依赖项目更新为较新版本是一个命令: 69 | 70 | ```bash 71 | $ dep ensure -update github.com/foo/bar 72 | ``` 73 | 74 | 这也可以在没有参数的情况下尝试更新所有依赖项(尽管通常不推荐): 75 | 76 | ```bash 77 | $ dep ensure -update 78 | ``` 79 | 80 | `dep ensure -update`搜索与.一起使用的版本`branch`,`version`, 要么`revision`约束中的约束`Gopkg.toml`.这些约束类型具有不同的语义,其中一些允许`dep ensure -update`有效地找到一个"更新"的版本,而其他人将需要手动更新`Gopkg.toml`.该[确保机制](ensure-mechanics.md#update-and-constraint-types)指南更详细地解释了这一点,但如果你想知道什么效果`dep ensure -update`可能有一个特定的项目,`LATEST`在`dep status`输出会告诉你. 81 | 82 | ### 添加和删​​除`import`声明 83 | 84 | 如中所述[有关添加依赖项的部分](#adding-a-new-dependency),dep依赖于`import`代码中的语句,用于确定项目实际需要的依赖项.因此,当您添加或删除import语句时,dep通常需要关心它. 85 | 86 | 只有在发生以下情况之一时才会出现问题`dep ensure`必须使项目恢复同步: 87 | 88 | 1. 你已经添加了第一个`import`一个包,但已经`import`该项目的其他包. 89 | 2. 你已经删除了最后一个`import`一个包,但仍然`import`该项目的其他包. 90 | 3. 你已经添加了第一个`import`特定项目中的任何包.(注意:这是[替代添加方法](#adding-a-new-dependency)) 91 | 4. 你已经删除了最后一个`import`来自特定项目的包. 92 | 93 | 简而言之,dep涉及整个项目中的一组唯一导入路径,并且仅在进行添加或删除该集合的导入路径的更改时才会关注.`dep check`将快速报告任何此类问题,这些问题将通过运行解决`dep ensure`. 94 | 95 | ### 规则变化`Gopkg.toml` 96 | 97 | `Gopkg.toml`文件包含五种基本类型的规则.该[`Gopkg.toml`文档](Gopkg.toml.md)详细解释它们,但这里是一个概述: 98 | 99 | - `required`,大多相当于`import`的陈述`.go`文件,除了可以列出一个`main`包这里 100 | - `ignored`,导致dep到黑洞的导入路径(以及它唯一引入的任何导入) 101 | - `[[constraint]]`,表示版本约束的节和基于每个项目依赖性的一些其他规则 102 | - `[[override]]`,stanzas相同`[[constraint]]`除了只有当前项目可以表达它们并取代它们`[[constraint]]`在当前项目和依赖项中 103 | - `[prune]`,全局和每个项目规则,用于管理应从中删除的文件类型`vendor/` 104 | 105 | 对这些规则中的任何一个的更改可能需要进行更改`Gopkg.lock`和`vendor/`;一次成功`dep ensure`run会立即合并所有这些更改,使您的项目重新同步. 106 | 107 | ## 可视化依赖关系 108 | 109 | 通过管道输出来生成依赖树的可视化表示`dep status -dot`至[graphviz的](http://www.graphviz.org/). 110 | 111 | ### Linux的 112 | 113 | ``` 114 | $ sudo apt-get install graphviz 115 | $ dep status -dot | dot -T png | display 116 | ``` 117 | 118 | ### 苹果系统 119 | 120 | ``` 121 | $ brew install graphviz 122 | $ dep status -dot | dot -T png | open -f -a /Applications/Preview.app 123 | ``` 124 | 125 | ### 视窗 126 | 127 | ``` 128 | > choco install graphviz.portable 129 | > dep status -dot | dot -T png -o status.png; start status.png 130 | ``` 131 | 132 | ![status graph](assets/StatusGraph.png) 133 | 134 | ## 关键要点 135 | 136 | 以下是本指南的主要内容: 137 | 138 | - `dep check`将快速报告您的项目的任何方式[同步](glossary.md#sync). 139 | - `dep ensure -update`是更新依赖项的首选方法,但对于不发布semver版本的项目效率较低. 140 | - `dep ensure -add`通常是引入新依赖项的最简单方法,但您也可以添加新的依赖项`import`语句然后运行`dep ensure`. 141 | - 如果您曾进行过手动更改`Gopkg.toml`,最好跑`dep ensure`确保一切都同步. 142 | - `dep ensure`跑步几乎从来都不是错误的;如果您不确定发生了什么,运行它将使您恢复安全("最近的百合花"),或者无法提供信息. 143 | 144 | 此外,还有其他一些杂项花絮: 145 | 146 | - 与Go工具链一样,请避免在自己的项目中使用符号链接.dep容忍了一点,但像Go工具链本身一样,通常不会非常支持符号链接. 147 | - 切勿直接编辑任何内容`vendor/`;dep将无条件地覆盖此类更改.如果您需要修改依赖项,请将其分叉并正确执行. 148 | -------------------------------------------------------------------------------- /docs/the-solver.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: The Solver 3 | --- 4 | 5 | At the heart of dep is a constraint solving engine - a [CDCL](https://en.wikipedia.org/wiki/Conflict-Driven_Clause_Learning)-style solver (albeit light on the "CL" part), tailored specifically to the domain of Go package management. It lives in the `github.com/golang/dep/gps` package, and is where the work of determining a valid, transitively complete dependency graph (aka, the contents of `Gopkg.lock`) is performed. 6 | 7 | This page will eventually detail the solver's mechanics, but in the meantime, there are [docs for an older version of the solver](https://github.com/sdboyer/gps/wiki/gps-for-Contributors) that are still accurate enough to provide a rough picture of its behavior. 8 | 9 | ## Solving invariants 10 | 11 | The solver guarantees certain invariants in every complete solution it returns. Each invariant is explored in detail later, but they can be summarized as follows: 12 | 13 | * All rules specified in activated `[[constraint]]` stanzas in both the current project and dependency projects will be satisfied, unless superseded by a `[[override]]` stanza in the current project. 14 | * For all import paths pointing into a given project, the version of the project selected will contain "valid" Go packages in the corresponding directory. 15 | * If an [import comment](https://golang.org/cmd/go/#hdr-Import_path_checking) is specified by a package, any import paths addressing that package will be of the form specified in the comment. 16 | * For any given import path, all instances of that import path will use the exact same casing. 17 | 18 | The solver is an iterative algorithm, working its way project-by-project through possible dependency graphs. In order to select a project, it must first prove that, to the best of its current knowledge, all of the above conditions are met. When the solver cannot find a solution, failure is defined in terms of a project's version's inability to meet one of the above criteria. 19 | 20 | ### `[[constraint]]` rules 21 | 22 | As described in the `Gopkg.toml` docs, each [`[[constraint]]`](Gopkg.toml.md#constraint) stanza is associated with a single project, and each stanza can contain both [a version rule](Gopkg.toml.md#version-rules) and a [source rule](Gopkg.toml.md#source). For any given project `P`, all dependers on `P` whose constraint rules are "activated" must express mutually compatible rules. That means: 23 | 24 | * For version rules, all activated constraints on `P` must [intersect](), and and there must be at least one published version must exist in the intersecting space. Intersection varies depending on version rule type: 25 | * For `revision` and `branch`, it must be a string-literal match. 26 | * For `version`, if the string is not a valid semantic version, then it must be a string-literal match. 27 | * For `version` that are valid semantic version ranges, intersection is standard set-theoretic intersection of the possible values in each range range. Semantic versions without ranges are treated as a single element set (e.g., `version = "=v1.0.0"`) for intersection purposes. 28 | * For `source` rules, all projects with a particular dependency must either express a string-equal `source` value, or have no `source` value at all. This allows one dependency to specify an alternate `source`, and other dependencies to play along if they have no opinion. (NB: this play-along behavior may be removed in a future version.) 29 | 30 | If the current project's `Gopkg.toml` has an [`[[override]]`](Gopkg.toml.md#override) on `P`, then all `[[constraint]]` declarations (including any in the current project) are ignored, obviating the possibility of conflict. 31 | 32 | #### Activated constraints 33 | 34 | Just because a `[[constraint]]` on `P` appears in `D`'s `Gopkg.toml` doesn't necessarily mean the constraint on `P` is considered active. A package in `P` must be imported by a package in `D` - and, if `D` is not the current project, then one of its packages importing `P` must also be imported. 35 | 36 | Given the following dependency graph, where `C` is the current project: 37 | 38 | ``` 39 | C -> D 40 | C -> P 41 | D/subpkg -> P 42 | ``` 43 | 44 | Even though `C` imports `D`, because `D/subpkg` is not reachable through `C`'s imports, any `[[constraint]]` declared in `D`'s `Gopkg.toml`' on `P` will not be active. 45 | 46 | The reasoning behind this behavior is explained further [in this gist](https://gist.github.com/sdboyer/b0813bf2b9dba58a335a85092085472f). 47 | 48 | ### Package validity 49 | 50 | dep does only superficial validation of code in packages, but it does do some. For a package to be considered valid, three things must be true: 51 | 52 | * There must be at least one `.go` file. 53 | * No errors are reported from [`parser.ParseFile()`](https://golang.org/pkg/go/parser/#ParseFile) when called with [`parser.ImportsOnly|parser.ParseComments`](https://golang.org/pkg/go/parser/#Mode) on any file in the package directory. 54 | 55 | - The package must not contain any [local imports](https://golang.org/pkg/go/build/#IsLocalImport). Note: this disallows something the standard toolchain compiler does allow, which is normally means dep must support it. However, local imports are already strongly discouraged in the toolchain, and skipping them allows dep to avoid [dot-dot hell](https://9p.io/sys/doc/lexnames.html). 56 | 57 | If any of the above are untrue, the code in a package is considered malformed, and cannot be used in a solution. 58 | 59 | It is not immediately disqualifying for a project to merely contain some invalid packages; they must be imported for the invariant to be broken. So, if `P/invalid` is a subpackage with invalid code in it, then it is still acceptable if `C -> P`. However, internal imports within `P` are also considered, so this import chain: 60 | 61 | ``` 62 | C -> P 63 | P -> invalid 64 | ``` 65 | 66 | will result in an error, as `C` imports a package that will necessarily result in the import of an invalid package. 67 | 68 | ### Import comments 69 | 70 | Go 1.4 introduced [import comments](https://golang.org/cmd/go/#hdr-Import_path_checking), which allow a package to specify the import path that must be used when addressing it. For example, `import "github.com/golang/net/dict"` would point to a valid package, but because [it uses an import comment](https://github.com/golang/net/blob/42fe2e1c20de1054d3d30f82cc9fb5b41e2e3767/dict/dict.go#L7) to enforce that it must be imported as `golang.org/x/net/dict`, dep would reject any project attempting to import it directly through its github address. 71 | 72 | Because most projects are consistent about their import comment use over time, this issue typically only occurs when adding a new dependency or attempting to revive an older project. 73 | 74 | > Note: dep does not currently enforce this rule, but [it needs to](https://github.com/golang/dep/issues/902). 75 | 76 | **Remediation:** change the code by fixing the offending import paths. If the offending import paths are not in the current project and you don't directly control the dependency, you'll have to fork and fix it yourself, then use `source` to point to your fork. 77 | 78 | ### Import path casing 79 | 80 | The standard Go toolchain compiler [does not](https://github.com/golang/go/issues/4773) [allow](https://github.com/golang/go/issues/20264) import paths that vary only in case to exist in the same build. For example, either of `github.com/sirupsen/logrus` or `github.com/Sirupsen/logrus` are fine (GitHub treats usernames as case-insensitive) individually, but they cannot exist in the same project. 81 | 82 | The solver keeps track of the accepted case variant for each import path it's processed. Any subsequent projects it sees that introduces a case-only variation for a known import path will be rejected. 83 | 84 | **Remediation:** Pick a casing variation (all lowercase is usually the right answer), and enforce it universally across the depgraph. As it has to be respected in all dependencies, as well, this may necessitate pull requests and possibly forking of dependencies, if you don't control them directly. 85 | -------------------------------------------------------------------------------- /docs/Gopkg.lock.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gopkg.lock 3 | --- 4 | 5 | The `Gopkg.lock` file is generated by `dep ensure` and `dep init`. It is the output of [the solving function](ensure-mechanics.md#functional-flow): a transitively complete snapshot of a project's dependency graph, expressed as a series of `[[project]]` stanzas. That means: 6 | 7 | * Every package a project needs to compile 8 | * Plus any [`required`](Gopkg.toml.md#required) packages 9 | * Less any [`ignored`](Gopkg.toml.md#ignored) packages 10 | 11 | `Gopkg.lock` also contains some metadata about the algorithm and inputs used to arrive at the final graph, under `[solve-meta]`. 12 | 13 | `Gopkg.lock` always includes a `revision` for all listed dependencies, as the semantics of `revision` guarantee them to be immutable. Thus, the `Gopkg.lock` acts as a reproducible build list - as long as the upstream remains available, all dependencies can be precisely reproduced. 14 | 15 | `Gopkg.lock` is autogenerated; editing it manually is generally an antipattern. If there is a goal you can only achieve by hand-editing `Gopkg.lock`, it is at least a feature request, and likely a bug. 16 | 17 | ## `[[projects]]` 18 | 19 | The dependency graph is expressed as a series of `[[projects]]` stanzas, each representing a single dependency project. A given project can only appear once in the list, and the version information expressed about them encompasses all contained packages - it is not possible to have multiple packages from a single project at different versions. 20 | 21 | These are all the properties that can appear in a `[[projects]]` stanza, and whether or not they are guaranteed to be present/must be present for a stanza to be valid. 22 | 23 | | **Property** | **Always present?** | 24 | | ------------ | ------------------- | 25 | | `name` | Y | 26 | | `packages` | Y | 27 | | `source` | N | 28 | | `revision` | Y | 29 | | `version` | N | 30 | | `branch` | N | 31 | | `pruneopts` | Y | 32 | | `digest` | Y | 33 | 34 | ### `name` 35 | 36 | The project to which the stanza applies, as identified by its [project root](glossary.md#project-root). 37 | 38 | ### `source` 39 | 40 | If present, it indicates the upstream source from which the project should be retrieved. It has the same properties as [`source` in `Gopkg.toml`](Gopkg.toml.md#source). 41 | 42 | ### `packages` 43 | 44 | A complete list of directories from within the source that dep determined to be necessary for the build. 45 | 46 | In general, this is the set of packages that were found to be participants in the package import graph, through at least one but as many as all of the following mechanisms: 47 | 48 | * Being in the current project's [`required`](Gopkg.toml.md#required) list 49 | * Being imported by a package from either the current project or a different dependency 50 | * Being imported by a package from within this project that, directly or transitively, is imported by a package from a different project 51 | 52 | ### `pruneopts` 53 | 54 | A compactly-encoded form of the [prune options designated in `Gopkg.toml`](Gopkg.toml.md#prune) . Each character represents one of the three possible rules: 55 | 56 | | Character | Pruning Rule in `Gopkg.toml` | 57 | | --------- | ---------------------------- | 58 | | `N` | `non-go` | 59 | | `U` | `unused-packages` | 60 | | `T` | `go-tests` | 61 | 62 | If the character is present in `pruneopts`, the pruning rule is enabled for that project. Thus, `NUT` indicates that all three pruning rules are active. 63 | 64 | ### `digest` 65 | 66 | The hash digest of the contents of `vendor/` for this project, _after_ pruning rules have been applied. The digest is versioned, by way of a colon-delimited prefix; the string is of the form `:` . The hashing algorithm corresponding to version 1 is SHA256, as implemented in the stdlib package `crypto/sha256`. 67 | 68 | There are some tweaks that differentiate the hasher apart from a naive filesystem tree hashing implementation: 69 | 70 | * Symlinks are ignored. 71 | * Line endings are normalized to LF (using an algorithm similar to git's) in order to ensure digests do not vary across platforms. 72 | 73 | ### Version information: `revision`, `version`, and `branch` 74 | 75 | In order to provide reproducible builds, it is an absolute requirement that every project stanza contain a `revision`, no matter what kinds of constraints were encountered in `Gopkg.toml` files. It is further possible that exactly one of either `version` or `branch` will _additionally_ be present. 76 | 77 | When one of the other two are present, the `revision` is understood to be the underlying, immutable identifier that corresponded to that `version` or `branch` _at the time when the `Gopkg.lock` was written_. 78 | 79 | ## `[solve-meta]` 80 | 81 | Metadata contained in this section tells us about the algorithm that was used to generate the `Gopkg.lock` file. These are very coarse indicators, primarily used to trigger a re-evaluation of the lock when it might have become invalid, as well as warn a team when its members are using algorithms with potentially subtly different effects. 82 | 83 | More details on "analyzer" and "solver" follow, but the versioning principle is the same: algorithmic changes that result in a decrease to the set of acceptable solutions for at least one input set generally require a version bump, while changes that increase the size of that set do not. However, this is not a formal definition; we leave room for judgment calls on small changes and bug fixes, and we bump at most once per release. 84 | 85 | By bumping versions only on solution set contractions, but not expansions, it allows us to avoid having to bump constantly (which could make using dep across teams awkward), while still making it likely that when the solver and version numbers match between `Gopkg.lock` and a running version of dep, what's recorded in the file is acceptable by the running version's rules. 86 | 87 | ### `input-imports` 88 | 89 | A sorted list of all the import inputs that were present at the time the `Gopkg.lock` was computed. This list includes both actual `import` statements from the project, as well as any `required` import paths listed in `Gopkg.toml`, excluding any that were `ignored`. 90 | 91 | ### `analyzer-name` and `analyzer-version` 92 | 93 | The analyzer is an internal dep component responsible for interpreting the contents of `Gopkg.toml` files, as well as metadata files from any tools dep knows about: `glide.yaml`, `vendor.json`, etc. 94 | 95 | The analyzer is named because the dep needs to identify itself to its engine, gps (`github.com/golang/dep/gps`); gps knows nothing about dep. The analyzer version is bumped when something in the analyzer's logic begins treating data that it already accepted in a significantly different way, or stops accepting a particular class of data. It is _not_ changed when support for entirely new types of data are added. 96 | 97 | For example, if dep's analyzer stopped supporting automated conversions from glide, then that would not require bumping the analyzer version, as doing so makes _more_ solutions possible. Adding support for converting from a new tool, or changing the interpretation of `version` fields in `Gopkg.toml` so that it was only allowed to specify minimum versions, would entail a version bump. 98 | 99 | ### `solver-name` and `solver-version` 100 | 101 | The solver is the algorithm behind [the solving function](ensure-mechanics.md#functional-flow). It selects all the versions that ultimately appear in `Gopkg.lock` by finding a combination that satisfies all the rules, including those from `Gopkg.toml` (fed to the solver by the analyzer). 102 | 103 | The solver is named because, like the analyzer, it is pluggable; an alternative algorithm could be written that applies different rules to achieve the same goal. The one dep uses, "gps-cdcl", is named after [the general class of SAT solving algorithm it most resembles](https://en.wikipedia.org/wiki/Conflict-Driven_Clause_Learning), though the algorithm is actually a specialized, domain-specific [SMT solver](https://en.wikipedia.org/wiki/Satisfiability_modulo_theories). 104 | 105 | The same general principles of version-bumping apply to the solver version: if the solver starts enforcing [Go 1.4 import path comments](https://golang.org/cmd/go/#hdr-Import_path_checking), that entails a bump, because it can only narrow the solution set. If it were to later relax that requirement, it would not require a bump, as that can only expand the solution set. -------------------------------------------------------------------------------- /docs/glossary.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: glossary 3 | title: Glossary 4 | --- 5 | 6 | dep uses some specialized terminology. Learn about it here! 7 | 8 | * [Atom](#atom) 9 | * [Cache lock](#cache-lock) 10 | * [Constraint](#constraint) 11 | * [Current Project](#current-project) 12 | * [Deducible](#deducible) 13 | * [Deduction](#deduction) 14 | * [Direct Dependency](#direct-dependency) 15 | * [External Import](#external-import) 16 | * [GPS](#gps) 17 | * [Local cache](#local-cache) 18 | * [Lock](#lock) 19 | * [Manifest](#manifest) 20 | * [Metadata Service](#metadata-service) 21 | * [Override](#override) 22 | * [Project](#project) 23 | * [Project Root](#project-root) 24 | * [Solver](#solver) 25 | * [Source](#source) 26 | * [Source Root](#source-root) 27 | * [Sync](#sync) 28 | * [Transitive Dependency](#transitive-dependency) 29 | * [Vendor Verification](#vendor-verification) 30 | 31 | --- 32 | 33 | ### Atom 34 | 35 | Atoms are a source at a particular version. In practice, this means a two-tuple of [project root](#project-root) and version, e.g. `github.com/foo/bar@master`. Atoms are primarily internal to the [solver](#solver), and the term is rarely used elsewhere. 36 | 37 | ### Cache lock 38 | 39 | Also "cache lock file." A file, named `sm.lock`, used to ensure only a single dep process operates on the [local cache](#local-cache) at a time, as it is unsafe in dep's current design for multiple processes to access the local cache. 40 | 41 | ### Constraint 42 | 43 | Constraints have both a narrow and a looser meaning. The narrow sense refers to a [`[[constraint]]`](Gopkg.toml.md#constraint) stanza in `Gopkg.toml`. However, in some contexts, the word may be used more loosely to refer to the idea of applying rules and requirements to dependency management in general. 44 | 45 | ### Current Project 46 | 47 | The project on which dep is operating - writing its `Gopkg.lock` and populating its `vendor` directory. 48 | 49 | Also called the "root project." 50 | 51 | ### Deducible 52 | 53 | A shorthand way of referring to whether or not import path [deduction](#deduction) will return successfully for a given import path. "Undeducible" is also often used, to refer to an import path for which deduction fails. 54 | 55 | ### Deduction 56 | 57 | Deduction is the process of determining the subset of an import path that corresponds to a source root. Some patterns are known a priori (static); others must be discovered via network requests (dynamic). See the reference on [import path deduction](deduction.md) for specifics. 58 | 59 | ### Direct Dependency 60 | 61 | 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`. 62 | 63 | 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`. 64 | 65 | 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. 66 | 67 | ### External Import 68 | 69 | An `import` statement that points to a package in a project other than the one in which it originates. For example, an `import` in package `github.com/foo/bar` will be considered an external import if it points to anything _other_ than stdlib or `github.com/foo/bar/*`. 70 | 71 | ### GPS 72 | 73 | Acronym for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps." 74 | 75 | ### Local cache 76 | 77 | dep maintains its own, pristine set of upstream sources (so, generally, git repository clones). This is kept separate from `$GOPATH/src` so that there is no obligation to maintain disk state within `$GOPATH`, as dep frequently needs to change disk state in order to do its work. 78 | 79 | By default, the local cache lives at `$GOPATH/pkg/dep`. If you have multiple `$GOPATH` entries, dep will use whichever is the logical parent of the process' working directory. Alternatively, the location can be forced via the [`DEPCACHEDIR` environment variable](env-vars.md#depcachedir). 80 | 81 | ### Lock 82 | 83 | A generic term, used across many language package managers, for the kind of information dep keeps in a `Gopkg.lock` file. 84 | 85 | ### Manifest 86 | 87 | A generic term, used across many language package managers, for the kind of information dep keeps in a `Gopkg.toml` file. 88 | 89 | ### Metadata Service 90 | 91 | An HTTP service that, when it receives an HTTP request containing a `go-get=1` in the query string, treats interprets the path portion of the request as an import path, and responds by embedding data in HTML `` tags that indicate the type and URL of of the underlying source root. This is the server-side component of dynamic [deduction](#deduction). 92 | 93 | The behavior of metadata services is defined in the [Go documentation on remote import paths](https://golang.org/cmd/go/#hdr-Remote_import_paths). 94 | 95 | Variously referenced as "HTTP metadata service", "`go-get` HTTP metadata service", "`go-get` service", etc. 96 | 97 | ### Override 98 | 99 | An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`. 100 | 101 | ### Project 102 | 103 | A project is a tree of Go packages. Projects cannot be nested. See [Project Root](#project-root) for more information about how the root of the tree is determined. 104 | 105 | ### Project Root 106 | 107 | The root import path for a project. A project root is defined as: 108 | 109 | * For the current project, the location of the `Gopkg.toml` file defines the project root 110 | * For dependencies, the root of the network [source](#source) (VCS repository) is treated as the project root 111 | 112 | These are generally one and the same, though not always. When using dep inside a monorepo, multiple `Gopkg.toml` files may exist at subpaths for discrete projects, designating each of those import paths as Project Roots. This works fine when working directly on those projects. If, however, any project not in the repository seeks to import the monorepo, dep will treat the monorepo as one big Project, with the root directory being the Project Root; it will disregard any and all `Gopkg.toml` files in subdirectories. 113 | 114 | This may also be referred to as the "import root" or "root import path." 115 | 116 | ### Solver 117 | 118 | "The solver" is a reference to the domain-specific SAT solver contained in [gps](#gps). More detail can be found on its [reference page](the-solver.md). 119 | 120 | ### Source 121 | 122 | The remote entities that hold versioned code. Sources are specifically the entity containing the code, not any particular version of the code itself. 123 | 124 | "Source" is used in lieu of "VCS" because Go package management tools will soon learn to use more than just VCS systems. 125 | 126 | ### Source Root 127 | 128 | 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. 129 | 130 | ### Sync 131 | 132 | Dep is designed around a well-defined relationship between four states: 133 | 134 | 1. `import` statements in `.go` files 135 | 2. `Gopkg.toml` 136 | 3. `Gopkg.lock` 137 | 4. The `vendor` directory 138 | 139 | If any aspect of the relationship is unfulfilled (e.g., there is an `import` not reflected in `Gopkg.lock`, or a project that's missing from `vendor`), then dep considers the project to be "out of sync." 140 | 141 | This concept is explored in detail in [ensure mechanics](ensure-mechanics.md#staying-in-sync). 142 | 143 | ### Transitive Dependency 144 | 145 | A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies. 146 | 147 | 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`. 148 | 149 | ### Vendor Verification 150 | 151 | Dep guarantees that `vendor/` contains exactly the expected code by hashing the contents of each project and storing the resulting [digest in Gopkg.lock](Gopkg.lock.md#digest). This digest is computed _after_ pruning rules are applied. 152 | 153 | The digest is used to determine if the contents of `vendor/` need to be regenerated during a `dep ensure` run, and `dep check` uses it to determine whether `Gopkg.lock` and `vendor/` are in [sync](#sync). The [`noverify`](Gopkg.toml.md#noverify) list in `Gopkg.toml` can be used to bypass most of these verification behaviors. -------------------------------------------------------------------------------- /docs/failure-modes.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: failure-modes 3 | title: 故障模式 4 | --- 5 | 6 | 与所有复杂的面向网络的软件一样,DEP具有已知的故障模式.这些通常分为两类:I/O和逻辑.I/O错误源于对与网络或本地磁盘交互的系统调用的意外响应.当DEP在包管理问题域内遇到问题时,会发生逻辑故障. 7 | 8 | ## 输入输出错误 9 | 10 | dep从网络读取,并读写到磁盘,因此会受到此类活动可能出现的所有典型错误的影响. 11 | 12 | 完整的磁盘、失败的磁盘、缺乏权限、网络分区、防火墙等.然而,有三类I/O错误值得特别处理: 13 | 14 | - 网络故障 15 | - 局部缓存状态不好 16 | - `vendor`写入错误 17 | 18 | 一般来说,这些问题不是我们可以在dep中合理编程的.因此,它们不能被认为是需要我们修复的bug.幸运的是,这些问题大多有直接的补救措施. 19 | 20 | ### 网络故障 21 | 22 | > **修复TL;DR:**大多数网络问题都是短暂的,即使它们可能持续几分钟,并且可以通过重新运行相同的命令来解决.在尝试更具侵入性的解决方案之前,请先尝试一下. 23 | 24 | DEP在几个不同的点与网络对话.这些依赖于源(VCS)类型和本地磁盘状态有所不同,但这一操作列表通常具有启发性: 25 | 26 | - 当DEP不能[静态演绎](deduction.md#static-deduction)导入路径的源根,它发出一个`go-get`HTTP元数据请求到从导入路径构建的URL. 27 | - 检索源的可用版本列表(思考)`git ls-remote`必然需要网络活动. 28 | - 最初下载(按GIT术语)`git clone`)到本地高速缓存的上游源也必然需要网络活动. 29 | - 更新本地缓存(以GIT术语)`git fetch`)来自上游来源的最新变化. 30 | - 写下代码树`vendor`通常是从本地缓存完成的,但在某些情况下,可以从远程源上飞取TARBARE. 31 | 32 | 实际上,您可能会观察到的网络故障偏向列表中的早期项目,仅仅是因为这些操作往往先发生:通常看不到更新失败与版本列表失败一样多,因为它们通常具有相同的根本原因(源主机是DOW).N,网络分区等),但版本列表请求首先发生在大多数路径上. 33 | 34 | #### 持久性网络故障 35 | 36 | 虽然大多数网络故障是短暂的,但有三个定义良好的情况下,它们更持久: 37 | 38 | - **源驻留的网络从用户的位置是永久不可到达的:**在实践中,这通常意味着两件事之一:你忘记登录到你公司的VPN,或者你落后了.[gfw the](https://en.wikipedia.org/wiki/Great_Firewall).在后者的房屋,setting the*事实上*HTTP代理服务器环境变量,标准[`http.ProxyFromEnvironment()`](https://golang.org/pkg/net/http/#ProxyFromEnvironment)respects将原因dep' S`go-get`HTTP请求的元数据,作为阱和bzr Hg,As Git子命令,utilize to the代理. 39 | 40 | - 确切的说因为是修复is also the same when the custom`go-get`元数据服务的HTTP similarly unreachable is for a源.the messages会失败,不管一个人多,看起来像[更广泛的演绎](#deduction-failures). 41 | 42 | - **permanently has been the source:moved消去.**这些是[左垫](https://www.theregister.co.uk/2016/03/23/npm_left_pad_chaos/)虽然没有说明,that[在GitHub redirects交通renames automatically](https://help.github.com/articles/renaming-a-repository/)减轻重命名问题.但是,如果移除上游源,dep将无法继续进行,直到为导入路径建立了新的上游源.为此目的: 43 | 44 | - 如果在本地缓存或GOPATH中仍然有源存储库的副本,请考虑将其上载到新位置(例如,分叉)并使用[`source`](Gopkg.toml.md#source)规则指向叉. 45 | - 如果本地没有一个完整的存储库,则提取当前的代码.`vendor`将目录导入新的存储库并将其推送到A.(注意:这可能有许可证的含义). 46 | - 如果您在本地没有代码的实例,那么可以做的就很少——代码已经不见了,您将需要重构项目. 47 | 48 | dep的未来版本将能够在创建新的上游/分叉源之前更好地处理一个过渡时期,或者仅仅生活在一个给定代码树只存在于项目中的世界中`vendor`目录. 49 | 50 | - **用户缺少与源交互的必要凭据:**见[配置凭证常见问题解答](FAQ.md#how-do-i-get-dep-to-authenticate-to-a-git-repo). 51 | 52 | 准确的错误文本将根据运行中的操作、源dep尝试与哪种类型的源dep通信以及实际网络问题发生而有所不同.错误文本可能并不总是立即明确您要处理的这些内容的组合,但是对于持久性问题,它至少应该减少搜索空间. 53 | 54 | #### 吊挂 55 | 56 | > **修复TL;DR:**挂起几乎总是网络拥塞,或者纯粹的网络数据量来获取.等待,或取消并重试`-v`试图获得更多的上下文. 57 | 58 | 几乎任何DEP命令运行的情况下`-v`挂机超过十分钟,最终将是一个错误.然而,对于明显的dep挂起最常见的解释实际上是正常的行为:因为dep的操作要求它保留自己的上游源拷贝,隐藏在[本地缓存](glossary.md#local-cache)对于项目,特别是大型项目,DEP的第一次运行可能需要很长的时间来填充缓存. 59 | 60 | 唯一已知的dep可能无限期挂起的情况是,如果它调用的一个底层VCS二进制文件提示输入某种内容.通常这意味着凭据(虽然不总是-确保接受远程主机的SSH密钥到您已知的主机!)而DEP的正常假设是通过环境机制提供必要的凭证.[配置文件或守护程序](FAQ.md#how-do-i-get-dep-to-authenticate-to-a-git-repo)这个假设对于DEP的并发网络活动是必要的.如果您的用例绝对不能支持使用任何这样的环境缓存机制,[请在这个问题上斟酌一下.](https://github.com/golang/dep/issues/1476). 61 | 62 | 遗憾的是,直到DEP[提高其正在进行的I/O操作的可观测性](<>)它不能准确地向用户报告在任何给定的时刻实际正在进行的操作.这使得很难与其他挂起区分——凭证提示、防火墙导致的长网络超时、面临分组丢失时TCP的迟缓等等. 63 | 64 | ### 局部缓存状态不好 65 | 66 | > **修复TL;DR:**删除本地缓存DIR:`rm -rf $GOPATH/pkg/dep/sources`. 67 | 68 | 有可能的部分[本地缓存](glossary.md#local-cache)由DEP维持,进入一个糟糕的状态.这主要发生在DEP过程被强制终止时(例如CTRL- C).例如,这可以终止`git`命令绕过,在磁盘上留下坏的状态.根据DEP的定义,A[脏工作拷贝](<>)是坏状态. 69 | 70 | 由于本地缓存状态不佳而引起的错误消息通常不包括完整路径,因此可能不会立即发现问题源于本地缓存.如果不包括完整路径,那么最好的提示就是这些错误看起来像本地VCS错误,但它们不在您自己的项目的文件上. 71 | 72 | 然而,在大多数情况下,**DEP从坏的本地缓存状态问题中自动发现和恢复**反弹到一个好的状态,因为它引导每个命令执行.如果您确实遇到一个看起来是本地缓存问题,dep不会自动从中恢复,那么修复通常是抛出缓存,`rm -rf $GOPATH/pkg/dep/sources`DEP将在下一次运行中自动重新填充它.但是,如果你有时间,请保存本地缓存DIR并作为bug报告它! 73 | 74 | 没有已知的情况下,在正常操作过程中,DEP可以不可修复地破坏它自己的本地缓存.任何这样的情况都会被认为是DEP中的一个关键错误,你应该报告它!如果你认为你遇到过这样的情况,它应该具有以下特点: 75 | 76 | - 您所看到的错误消息与下载源中的某种磁盘状态错误一致.`$GOPATH/pkg/dep/sources` 77 | - 您可以在`$GOPATH/pkg/dep/sources`由上述误差提出 78 | - 删除本地缓存DIR并运行相同的命令后,同样的错误会再次出现,**没有**过早终止项目(例如通过CTRL—C) 79 | 80 | ### `vendor`写入错误 81 | 82 | DEP在试图写出错误时可能会遇到错误.`vendor`目录本身(任何这样的错误都会导致完全回滚;不会对磁盘造成任何更改).为了找出问题所在,知道这是人口流动的趋势.`vendor`: 83 | 84 | 1. 在系统临时目录中分配一个新的临时目录. 85 | 2. 重命名现有`vendor`目录到`vendor.orig`. 如果可能的话,在当前项目的根目录中执行此操作;如果没有,将其重命名并移动到Tundir. 86 | 3. 创建新的`vendor`在Tundir中的目录,同时将其填充到所有被命名为`Gopkg.lock`. 87 | 4. 移动新的`vendor`在当前项目的根目录中放入目录. 88 | 5. 删除旧的`vendor`目录. 89 | 90 | 注:此流程将变得更具针对性[供应商验证](<>)允许DEP识别和瞄准当前项目中的子集`vendor`这需要改变. 91 | 92 | 这一类已知的问题包括: 93 | 94 | - 临时目录中的空间不足会导致错误,引发回滚.但是,因为回滚过程清理了到目前为止编写的文件,所以临时分区在dep退出之后实际上不会满,这可能会产生误导. 95 | - 试图[重新]移动原件`vendor`如果目录中的任何文件在某些编辑器/某些OS(特别是Windows)上"打开",则目录可能出现权限错误.[这是个问题](<>). 96 | 97 | ## 逻辑故障 98 | 99 | 逻辑故障包含DEP的逻辑问题解决域内可能发生的一切. 100 | 101 | 这些失败中的一些可能和形式错误一样简单,也很容易解决.不幸的是,其他人可能需要分叉和修改上游项目——尽管这种情况非常罕见. 102 | 103 | ### 演绎失败 104 | 105 | 导入路径演绎,详见[演绎参考](deduction.md)具有静态和动态两个阶段.当这两个阶段都不能确定给定导入路径的源根时,它被认为是演绎失败.演绎失败都包含这个关键错误文本: 106 | 107 | ```bash 108 | ...unable to deduce repository and source type for ""... 109 | ``` 110 | 111 | *注:有[对于小的子集,更多的错误消息](#malformed-import-paths)其中进口路径似乎是可推断的,但不知何故是畸形的.* 112 | 113 | 当在给定的导入路径上发生演绎失败时,最接近的原因将是以下五种情形之一(从最有可能到最不可能): 114 | 115 | - 进口路径永远不可推论. 116 | - **动态演绎失败:** 117 | - 导入路径一次是动态推断的,元数据的服务是上升的,但它是不可到达的. 118 | - 导入路径一度是动态推断的,但是它的元数据服务被降低了. 119 | - **静态规则更改:** 120 | - 运行版本的dep不能静态地推导导入路径,但是更新版本的dep添加了可以静态地推导导入路径的规则. 121 | - 导入路径曾经是静态推断的,但是DEP的运行版本已经停止了对它的支持. 122 | 123 | 在所有这些情况下,你最后的追索将是增加一个[`source`](Gopkg.toml.md#source)指令来解决问题.然而,这些指令是易碎的,只应在其他选项用完时使用;[这个问题解决了.](https://github.com/golang/dep/issues/860)甚至`source`可能无法帮助. 124 | 125 | #### 不可推断的路径 126 | 127 | > **修复TL;DR:**你打错了,把它修好.如果不是,你可能需要一个`source`但不要吝啬. 128 | 129 | 推断失败的最有可能的原因是轻微的用户错误.具体地说,用户是*现在的*用户(你),并且错误是在当前(你的)项目中有一个错误的导入路径.问题可能在你的身上`Gopkg.toml`或者一个导入,但是错误消息应该直接指出问题,并且解决方案通常是显而易见的,例如,"gihtub". 130 | 131 | 来自当前项目的输入的验证是在dep中快速且预先进行的,因此这些错误将倾向于立即出现.在这种快速验证和项目通常无法编译的事实之间,或者至少不是这样.`go get`由于这些错误,他们很容易被提前抓到.这就是为什么真正难以置信的路径在攻击自己的项目时主要表现为临时事故——您必须修复它们才能继续前进. 132 | 133 | 然而,这种不可信性是直接和困难的阻碍,导致这是向dep迁移的症结所在. 134 | 135 | - 其他几个GO依赖性管理工具允许指定任意的VCS/源URL,并且[但是支持通过`source`DEP仍悬而未决](https://github.com/golang/dep/issues/860). 136 | - GITHUB企业只有实现`go-get`HTTP元数据正确地存储库的根包.在实践中,这使得所有导入路径指向不可推断的,并且`source`没有前面提到的改进也不能帮助. 137 | 138 | 如果问题导入路径在当前项目中,但是问题不是明显的打字错误,那么您可能遇到动态故障,或者可能需要检查[演绎参考](deduction.md)了解什么是可推断的进口路径. 139 | 140 | #### 动态推理失败 141 | 142 | 大多数动态演绎失败要么是短暂的网络问题,要么是服务可用性问题,并且会通过重新运行前面的命令而消失.总是先试试看. 143 | 144 | 如果这个问题仍然存在,并且你肯定进口路径应该是可推断的,网络问题是检查的第一个罪魁祸首.当元数据服务不可到达时,典型的原因(VPN、防火墙)和补救是相同的.[当源本身不可到达时](#persistent-network-failures). 145 | 146 | 下一种可能性是永久消失的元数据服务.尽管网络错误仍然相当常见,但是很少遇到指向已失效的公共元数据服务的导入路径.考虑一下:一个导入路径可以让整个项目变得不可取和/或不可编译,并且这两个状态都不是流行项目可以长期使用的状态.因此,由于大多数(公共Go生态系统)依赖关系都依赖于更流行的项目,所以只要您还依赖于更流行的项目,就不大可能遇到这种情况. 147 | 148 | 当然,已经失效*私有的*元数据服务可能更为常见,因为它们受到完全不同的激励. 149 | 150 | 如果您认为您遇到了一个已失效的元数据服务,请尝试直接探测导入路径的域部分,以查看是否存在HTTP服务器.如果不是,你只能强迫`source`-假设您知道应该使用什么源URL.如果没有,你可能需要重构你的代码(如果问题在你的项目),选择一个不同的版本的问题依赖性下降的问题,或完全依赖;有时,你不得不摆脱死代码. 151 | 152 | #### 静态规则变化 153 | 154 | > **修复TL;DR:**确保你有最新版本的DeP. 155 | 156 | 静态规则更改不太可能是推理失败的原因. 157 | 158 | 似是而非,DEP将在未来添加新的静态演绎规则.这是可能的,如果你有一个旧版本的DEP,和你合作或将使用新版本的DEP有代码,那么他们的代码可能会利用新的导入路径模式,你的部门不知道.但是,很少有静态的规则可能会增加了DEP在其一生中,获取他们的问题就是更新一次. 159 | 160 | 最后的场景——DEP停止支持静态演绎模式包括清晰、完整,但根本不应该发生的.即使一个托管服务由静态规则今天被关闭,DEP将保留现有的静态规则;如果托管代码被转移到别处,然后DEP会尝试自动完成映射.如果没有这样的映射的话,那么DEP仍然承认基本的主机模式,但可以依靠使用畸形的导入路径错误的下一个话题——翔实拒绝从主机新的进口. 161 | 162 | #### 畸形进口路径 163 | 164 | 在很大程度上,静态("它是我们知道的少数主机之一吗?")和动态("只要做元数据服务告诉我们做什么")扣除是单次检查.然而,这两种情况都可以执行一些次要的验证: 165 | 166 | - In static deduction, the rules are necessarily specific to each host, but most enforce allowable characters and schemes in URLs that are known to be required by the underlying host. 167 | - In dynamic deduction, responses from the metadata service are minimally validated to ensure that the source type and scheme are all supported, and that the URL contains valid characters. 168 | 169 | ### 解决故障 170 | 171 | 什么时候?`dep ensure`或`dep init`用一个错误消息退出,看起来像这样: 172 | 173 | ```bash 174 | $ dep init 175 | init failed: unable to solve the dependency graph: Solving failure: No versions of github.com/foo/bar met constraints: 176 | v1.0.1: Could not introduce github.com/foo/bar@v1.13.1, as its subpackage github.com/foo/bar/foo is missing. (Package is required by (root).) 177 | v1.0.0: Could not introduce github.com/foo/bar@v1.13.0, as... 178 | v0.1.0: (another error) 179 | master: (another error) 180 | ``` 181 | 182 | *注意:其他三种硬故障类型有时可以报告为以下列表中各个版本的错误.这主要是因为DEP需要一个[错误处理的彻底重构](https://github.com/golang/dep/issues/288).* 183 | 184 | 这意味着求解器无法为满足由求解器执行的所有规则的所有依赖项找到版本组合.值得注意的是,因为DEP提供了一个很大的原因列表,说明每个版本失败的原因.*并不意味着*你必须解决每一个问题!这只是DEP告诉你为什么它最终不能在解决方案中使用这些版本中的每一个. 185 | 186 | 这些规则,以及未能满足它们的具体补救措施,在章节中详细描述.[求解不变量](the-solver.md#solving-invariants). 本节是关于解决一般故障发生时所采取的步骤.但是,为了设置上下文,这里有一个总结: 187 | 188 | - **`[[constraint]]`冲突:**当依赖图中的项目在什么方面不一致时[版本](Gopkg.toml.md#version-rules)可以接受的项目,或在哪里[来源](Gopkg.toml.md#source)它来自. 189 | - 修复通常会改变`[[constraint]]`或添加`[[override]]`但是真正的冲突可能需要分叉和黑客代码. 190 | - **包有效性失效:**当一个进口的包裹显然不能建造的时候. 191 | - 除了"停止导入"之外,这里通常没有太多的补救措施,因为它指示了某个版本的损坏. 192 | - **导入注释失败:**当用于处理包的导入路径与[导入评论](https://golang.org/cmd/go/#hdr-Import_path_checking)包用来指定它应该如何导入. 193 | - 补救是使用指定的导入路径,而不是使用任何一个. 194 | - **仅发生导入变更失败:**当两个相等的情况下,除了案例导入存在于同一个构建中. 195 | - 补救是选择一个案例变体在整个项目中使用,然后手动更新depgraph中的所有项目以使用新外壳. 196 | 197 | 让我们把解决失败的过程分解成一系列步骤: 198 | 199 | 1. 首先,查看失败版本列表,查找适合您的依赖关系的版本(或者看起来可以修复的故障),然后尝试解决这个问题.通常,您会看到在整个版本列表中重复出现单个故障,这非常清楚需要解决什么问题. 200 | 2. 采取针对失败的补救措施. 201 | 3. 重新运行运行失败的相同命令.有三种可能的结果: 202 | 1. 成功! 203 | 2. 您的修复无效,同样的故障再次发生.要么重新检查你的修复(步骤2),要么寻找新的故障修复(步骤1). 204 | 3. 你的解决办法是有效的,但出现了一些新的失败.返回具有新故障列表的步骤1. 205 | -------------------------------------------------------------------------------- /docs/Gopkg.toml.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: 3 | title: Gopkg.toml 4 | --- 5 | 这个`Gopkg.toml`文件最初是由`dep init`主要是手工编辑的.它包含管理DEP行为的几种规则声明: 6 | 7 | - *依赖规则:* [`constraints`](#constraint)和[`overrides`](#override)允许用户指定依赖关系的哪些版本是可接受的,以及它们应该从哪里检索. 8 | - *包装图规则:* [`required`](#required)和[`ignored`](#ignored)允许用户通过导入或排除导入路径来操作导入图. 9 | - [`metadata`](#metadata)是DEP将忽略的键值对的用户定义映射.他们提供了一个数据集的工具建设的顶部. 10 | - [`prune`](#prune)设置确定什么文件和目录可以被视为不必要的,从而自动从`vendor/`. 11 | - [`noverify`](#noverify)是项目根目录[供应商验证](glossary.md#vendor-verification)跳过. 12 | 13 | 请注意,因为ToML不遵守树结构,所以`required`和`ignored`字段必须在任何之前声明`[[constraint]]`或`[[override]]`. 14 | 15 | 有一个完整的[例子](#example) `Gopkg.toml`文件的底部文件.`dep init`默认情况下,也会生成`Gopkg.toml`包含一些示例值,用于指导. 16 | 17 | ## 依赖规则:`[[constraint]]`和`[[override]]` 18 | 19 | A中的大多数规则声明`Gopkg.toml`要么是`[[constraint]]`或`[[override]]`诗节.这两种类型的Stasas允许完全相同类型的值,但DEP解释它们不同.每个值允许以下值: 20 | 21 | - `name`-对应于[源根](glossary.md#source-root)依赖关系(一般情况下:VCS根是在哪里) 22 | - 至多[版本规则](#version-rules) 23 | - 可选的[`source`规则](#source) 24 | - [`metadata`](#metadata)这是特定于`name`D项目 25 | 26 | 这些节中的任何一个的完整示例(实际上无效,因为它有多个版本规则,出于说明的目的)如下所示: 27 | 28 | ```toml 29 | [[constraint]] 30 | # Required: the root import path of the project being constrained. 31 | name = "github.com/user/project" 32 | # Recommended: the version constraint to enforce for the project. 33 | # Note that only one of "branch", "version" or "revision" can be specified. 34 | version = "1.0.0" 35 | branch = "master" 36 | revision = "abc123" 37 | 38 | # Optional: an alternate location (URL or import path) for the project's source. 39 | source = "https://github.com/myfork/package.git" 40 | 41 | # Optional: metadata about the constraint or override that could be used by other independent systems 42 | [metadata] 43 | key1 = "value that convey data to other systems" 44 | system1-data = "value that is used by a system" 45 | system2-data = "value that is used by another system" 46 | ``` 47 | 48 | ### `[[constraint]]` 49 | 50 | 一`[[constraint]]`StAZA定义了一个规则的规则[直接依赖](glossary.md#direct-dependency)必须合并到依赖图中.DEP尊重来自当前项目的这些声明.`Gopkg.toml`以及`Gopkg.toml`在任何依赖项中找到的文件. 51 | 52 | **使用:**有一个[直接依赖](FAQ.md#what-is-a-direct-or-transitive-dependency)使用特定的分支、版本范围、修订或备用源(如叉子). 53 | 54 | ### `[[override]]` 55 | 56 | 安`[[override]]`节与A不同`[[constraint]]`因为它适用于所有的依赖关系,[直接的](glossary.md#direct-dependency)和[传递的](glossary.md#transitive-dependency)并取代所有其他`[[constraint]]`该项目的声明.但是,仅覆盖当前项目的`Gopkg.toml`并入. 57 | 58 | **使用:**重写主要目的是消除多种不可调和的分歧.`[[constraint]]`对单个依赖项的声明.然而,如果你需要的话,它们也将是你的主要来源.[约束传递依赖的版本?](FAQ.md#how-do-i-constrain-a-transitive-dependencys-version) 59 | 60 | 在可能的情况下,应谨慎使用并临时使用. 61 | 62 | ### `source` 63 | 64 | 一`source`规则可以指定另一个位置,从该位置`name`应该检索D项目.它主要用于临时指定存储库的叉. 65 | 66 | `source`规则通常是脆弱的,只有在没有其他追索权时才可以使用.使用它们来规避网络可达性问题通常是一种反模式. 67 | 68 | ### 版本规则 69 | 70 | 可以使用版本规则`[[constraint]]`或`[[override]]`诗节.版本规则有三种类型:`version`,`branch`和`revision`. 最多可以指定三种类型中的一种. 71 | 72 | #### `version` 73 | 74 | `version`是一种属性`constraint`S和`override`它用于指定特定依赖项的版本约束.它可以用于目标任意的VCS标签,或语义版本,或语义版本的范围. 75 | 76 | 使用以下运算符可以指定语义版本范围: 77 | 78 | - `=`平等的 79 | - `!=`不平等 80 | - `>`大于 81 | - `<`:小于 82 | - `>=`大于或等于 83 | - `<=`小于或等于 84 | - `-`文字范围.例如,1.2 -1.4.5相当于>=1.2,\<1.4.5 85 | - `~`小范围.例如,~1.2.3相当于>=1.2.3,\<1.3.0. 86 | - `^`主要范围.例如,^ 1.2.3相当于>=1.2.3,\<2.0.0. 87 | - `[xX*]`通配符.例如,1.2.x相当于>=1.2.0,\<1.3.0. 88 | 89 | 例如,您可以包括指定的规则.`version = "=2.0.0"`将依赖项绑定到版本2.0.0,或约束为次要版本:`version = "~2.1.0"`. 参考[档案图书馆](https://github.com/Masterminds/semver)更多信息的文档. 90 | 91 | **注释**当您指定版本时*没有操作员*,`dep`自动使用`^`默认情况下的操作符.`dep ensure`将解释给定的版本作为范围的最小边界,例如: 92 | 93 | - `1.2.3`成为靶场`>=1.2.3, <2.0.0` 94 | - `0.2.3`成为靶场`>=0.2.3, <0.3.0` 95 | - `0.0.3`成为靶场`>=0.0.3, <0.1.0` 96 | 97 | `~`和`=`运算符可以与版本一起使用.在没有任何操作符的情况下指定版本时,`dep`自动添加插入符号运算符,`^`. 插入符号操作符将版本中最左边的非零数字插入.例如: 98 | 99 | ``` 100 | ^1.2.3 means 1.2.3 <= X < 2.0.0 101 | ^0.2.3 means 0.2.3 <= X < 0.3.0 102 | ^0.0.3 means 0.0.3 <= X < 0.1.0 103 | ``` 104 | 105 | 要在清单中插入直接依赖的版本,请用`=`. 例如: 106 | 107 | ```toml 108 | [[constraint]] 109 | name = "github.com/pkg/errors" 110 | version = "=0.8.0" 111 | ``` 112 | 113 | #### `branch` 114 | 115 | 使用A`branch`约束将导致DEP使用指定的分支(例如,`branch = "master"`)用于特定的依赖关系.在树枝顶端的修改将被记录到`Gopkg.lock`并且几乎总是保持不变,直到请求更改为止.`dep ensure -update`. 116 | 117 | 通常,当项目使其可用时,您应该更喜欢语义版本到分支. 118 | 119 | #### `revision` 120 | 121 | 一`revision`是基本不变的标识符,就像Git提交的Sa1.虽然它被允许限制为`revision`这样做几乎总是一种反模式. 122 | 123 | 通常情况下,人们倾向于修改,因为他们觉得它会在某种程度上提高他们的项目的可重复性.这不是一个很好的理由.`Gopkg.lock`提供再现性.只使用`revision`如果你有充分的理由相信*不*该依赖的其他版本*能够*工作. 124 | 125 | ## 包装图规则:`required`和`ignored` 126 | 127 | 作为正常操作的一部分,DEP分析GO代码中的导入语句.这些导入语句将包连接在一起,最终形成图表.这个`required`和`ignored`规则以大致相互对偶的方式操纵该图:`required`向图中添加导入路径,以及`ignored`移除它们. 128 | 129 | ### `required` 130 | 131 | `required`列出必须包含在Gopkg.lock中的一组包(不是项目).此列表与当前项目导入的包集合并. 132 | 133 | ```toml 134 | required = ["github.com/user/thing/cmd/thing"] 135 | ``` 136 | 137 | **使用:**LTENS、发电机和其他开发工具 138 | 139 | - 你的项目需要 140 | - 不是`import`通过你的项目,[直接或传递](FAQ.md#what-is-a-direct-or-transitive-dependency) 141 | - 你不想把它们放进你的手中`GOPATH`和/或您想锁定版本 142 | 143 | 请注意,这只会牵扯这些依赖项的来源.它不安装或编译它们.因此,如果您需要安装该工具,您还应该运行以下操作(手动或从`Makefile`)之后`dep ensure`: 144 | 145 | ```bash 146 | cd vendor/pkg/to/install 147 | go install . 148 | ``` 149 | 150 | 如果这是唯一的安装这些可执行文件的项目,这只会可靠地工作.如果您希望根据正在工作的项目运行同一可执行文件的不同版本,那么这还不够.在那种情况下,你必须使用不同的方法.`GOBIN`对于每个项目,在运行上面的命令之前,执行这样的操作: 151 | 152 | ```bash 153 | export GOBIN=$PWD/bin 154 | export PATH=$GOBIN:$PATH 155 | ``` 156 | 157 | 你也可以试试[虚拟现实](https://github.com/GetStream/vg)在其中安装依赖项`required`在特定项目中自动列出`GOBIN`. 158 | 159 | ### `ignored` 160 | 161 | `ignored`列出DEP静态分析源代码时忽略的一组包(非项目).忽略的包可以在这个项目中,或者在依赖项中. 162 | 163 | ```toml 164 | ignored = ["github.com/user/project/badpkg"] 165 | ``` 166 | 167 | 使用`*`定义要忽略的包前缀.这将导致任何词汇通配符匹配被忽略,包括在`*`. 168 | 169 | ```toml 170 | ignored = ["github.com/user/project/badpkg*"] 171 | ``` 172 | 173 | **使用:**防止包和任何包的唯一依赖性被纳入`Gopkg.lock`. 174 | 175 | ## `metadata` 176 | 177 | `metadata`可以存在于根部,也可以存在于`constraint`和`override`声明. 178 | 179 | `metadata`声明被DEP忽略,并用于其他独立系统的使用. 180 | 181 | 根`metadata`声明定义项目本身的信息,而`metadata`A下的声明`[[constraint]]`或`[[override]]`定义有关该规则的元数据,用于`name`D项目. 182 | 183 | ```toml 184 | [metadata] 185 | key1 = "value that convey data to other systems" 186 | system1-data = "value that is used by a system" 187 | system2-data = "value that is used by another system" 188 | ``` 189 | 190 | ## `prune` 191 | 192 | `prune`定义依赖项的全局和每个项目修剪选项.选项在写入时确定哪些文件被丢弃.`vendor/`树. 193 | 194 | 以下是当前可用的选项: 195 | 196 | - `unused-packages`指示从包导入图中不出现的目录中的文件应该被修剪. 197 | - `non-go`GUE文件不被GO使用. 198 | - `go-tests`修剪去测试文件. 199 | 200 | 出于足够的谨慎,DEP无需保留可能具有法律意义的文件. 201 | 202 | 默认情况下,修剪选项被禁用.然而,生成一个`Gopkg.toml`通过`dep init`将添加行使能`go-tests`和`unused-packages`在根级修剪选项. 203 | 204 | ```toml 205 | [prune] 206 | go-tests = true 207 | unused-packages = true 208 | ``` 209 | 210 | 每个项目可以定义相同的修剪选项.额外的`name`字段是必需的,如`[[constraint]]`和`[[override]]`应该是[源根](glossary.md#source-root),不只是任何导入路径. 211 | 212 | ```toml 213 | [prune] 214 | non-go = true 215 | 216 | [[prune.project]] 217 | name = "github.com/project/name" 218 | go-tests = true 219 | non-go = false 220 | ``` 221 | 222 | 几乎所有的项目都会很好,没有设置任何项目特定的规则,并且可以在全球范围内启用以下修剪规则: 223 | 224 | ```toml 225 | [prune] 226 | unused-packages = true 227 | go-tests = true 228 | ``` 229 | 230 | 通常安全设置.`non-go = true`也一样.然而,由于dep仅对Go文件所扮演的角色有一个清晰的模型,并且非Go文件必然落在该模型之外,因此不可能有可比较的一般安全定义. 231 | 232 | ## `noverify` 233 | 234 | 这个`noverify`字段是路径的列表,通常是[项目根](glossary.md#project-root)排除[供应商验证](glossary.md#vendor-verification). 235 | 236 | DEP使用每个项目散列摘要,修剪后计算并记录在[格洛克船闸](Gopkg.lock.md#digest),确定内容是否`vendor/`果不其然.如果记录的摘要和相应树的哈希`vendor/`不同的是,该项目被认为是不同步的: 237 | 238 | - `dep ensure`会再生它 239 | - `dep check`将抱怨散列失配并退出1 240 | 241 | 强烈建议你离开.`vendor/`未修改的,无论DEP把它放在什么状态.然而,这并不总是可行的.如果你除了修改别无选择`vendor/`对于特定项目,然后将该项目的项目根添加到`noverify`. 这将产生以下影响: 242 | 243 | - `dep ensure`将忽略项目的哈希错配,并仅在其中重新生成`vendor/`如果绝对必要(修剪选项更改,包列表更改,版本更改) 244 | - `dep check`将继续报告散列错配(尽管有注释)`noverify`对于该项目,将不再退出1. 245 | 246 | `noverify`也可用于保存某些多余的路径,否则会被删除;例如,添加`WORKSPACE`到`noverify`列表将允许您保存`vendor/WORKSPACE`这可以帮助一些基于BZEL的工作流. 247 | 248 | ## 范围 249 | 250 | `dep`评价 251 | 252 | - `[[override]]` 253 | - `required` 254 | - `ignored` 255 | 256 | 仅在根项目中,即项目在哪里`dep`跑.例如,如果你有一个项目:`github.com/urname/goproject`和`github.com/foo/bar`是项目的依赖项,那么DEP将评估`Gopkg.toml`这些项目的文件如下: 257 | 258 | | github.com/urname/goproject | github.com/foo/bar | 259 | | --------------------------- | ------------------ | 260 | | \[[constraint]] ✔ | \[[constraint]] ✔ | 261 | | \[[override]] ✔ | \[[override]] ✖ | 262 | | required ✔ | required ✖ | 263 | | ignored ✔ | ignored ✖ | 264 | 265 | 评价:未评估 266 | 267 | # 例子 268 | 269 | 样本`Gopkg.toml`大多数元素存在: 270 | 271 | ```toml 272 | required = ["github.com/user/thing/cmd/thing"] 273 | 274 | ignored = [ 275 | "github.com/user/project/pkgX", 276 | "bitbucket.org/user/project/pkgA/pkgY" 277 | ] 278 | 279 | noverify = ["github.com/something/odd"] 280 | 281 | [metadata] 282 | codename = "foo" 283 | 284 | [prune] 285 | non-go = true 286 | 287 | [[prune.project]] 288 | name = "github.com/project/name" 289 | go-tests = true 290 | non-go = false 291 | 292 | [[constraint]] 293 | name = "github.com/user/project" 294 | version = "1.0.0" 295 | 296 | [metadata] 297 | property1 = "value1" 298 | property2 = 10 299 | 300 | [[constraint]] 301 | name = "github.com/user/project2" 302 | branch = "dev" 303 | source = "github.com/myfork/project2" 304 | 305 | [[override]] 306 | name = "github.com/x/y" 307 | version = "2.4.0" 308 | 309 | [metadata] 310 | propertyX = "valueX" 311 | ``` 312 | -------------------------------------------------------------------------------- /docs/daily-dep.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Daily Dep 3 | --- 4 | 5 | This guide is an introduction to the day-to-day use of dep. If you haven't set up a Go project at all yet, though, run through [Creating a New Project](new-project.md) first. 6 | 7 | Dep is a tool you'll use regularly in the course of normal Go development. Regularly, but briefly - dependency management is never the place we want to be spending our time or energy! In keeping with Go's philosophy of minimizing knobs, dep has a sparse interface; there are only two commands you're likely to run regularly: 8 | 9 | * `dep ensure` is the primary workhorse command, and is the only command that changes disk state. 10 | * `dep status` reports on the state of your project, and the visible universe of Go software projects. 11 | 12 | This guide primarily centers on `dep ensure`, as that's the command you run to effect changes on your project. The [Models and Mechanisms](ensure-mechanics.md) reference document details how the things work under the hood, and is worth reading if you're encountering a confusing `dep ensure` behavior (or just curious!). 13 | 14 | ## Basics 15 | 16 | Let's start with words! 17 | 18 | Dep's main command is `dep ensure`. The verb is "ensure" to imply that the action is not just some single, discrete action (like adding a dependency), but enforcing some kind of broader guarantee. If we wanted to express the `dep ensure` guarantee as a sentence, it would go something like this: 19 | 20 | > Hey dep, please make sure that [my project](glossary.md#current-project) is [in sync](glossary.md#sync): that [`Gopkg.lock`](Gopkg.lock.md) satisfies all the imports in my project, and all the rules in[ `Gopkg.toml`](Gopkg.toml.md), and that `vendor/` contains exactly what `Gopkg.lock` says it should." 21 | 22 | As the narrative indicates, `dep ensure` is a holistic operation. Rather than offering a series of commands to run in succession that incrementally achieve some final state, each run of `dep ensure` delivers a safe, complete, and reproducible set of dependencies with respect to the current state of your project. You might imagine repeated runs of `dep ensure` as being a bit like a frog, hopping from one lily pad to the next. 23 | 24 | ## Using `dep ensure` 25 | 26 | There are four times when you'll run `dep ensure`: 27 | 28 | * To add a new dependency 29 | * To update an existing dependency 30 | * To catch up after importing a package for the first time in your project, or removing the last import of a package in your project 31 | * To catch up to a change to a rule in `Gopkg.toml` 32 | 33 | If you're not sure if there have been changes to imports or `Gopkg.toml` rules, run `dep check`. It will tell you what is out of sync in your project. If anything is out of sync, running `dep ensure` will bring it back into line. 34 | 35 | Let's explore each of these moments. To play along, you'll need to `cd` into a project that's already been set up by `dep init`. If you haven't done that yet, check out the guides for [new projects](new-project.md) and [migrations](migrating.md). 36 | 37 | ### Adding a new dependency 38 | 39 | Let's say that we want to introduce a new dependency on `github.com/pkg/errors`. This can be accomplished with one command: 40 | 41 | ```bash 42 | $ dep ensure -add github.com/pkg/errors 43 | ``` 44 | 45 | > Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root (which is determined by the presence of a `Gopkg.toml` file). 46 | 47 | This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` directory, as well as injecting a best-guess version constraint for `github.com/pkg/errors` into our `Gopkg.toml`. But, it will also report a warning: 48 | 49 | ```bash 50 | "github.com/pkg/errors" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/. 51 | If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/. 52 | ``` 53 | 54 | As the warning suggests, you should introduce an `import "github.com/pkg/errors"` in your code, the sooner the better. If you don't, a later `dep ensure` run will interpret your newly-added dependency as unused, and automatically remove it from `Gopkg.lock` and `vendor/`. This also means that if you want to add multiple dependencies at once, you'll need to do it in a single command, rather than one after the other: 55 | 56 | ```bash 57 | $ dep ensure -add github.com/pkg/errors github.com/foo/bar 58 | ``` 59 | 60 | Dep works this way because it considers the import statements it discovers through static analysis of your project's code to be the canonical indicator of what dependencies must be present. That choice does add some pain at this moment, but it reduces friction and automates cleanup elsewhere. Tradeoffs! 61 | 62 | Of course, given this model, you don't _have to_ use `dep ensure -add` to add new dependencies - you can also just add an appropriate `import` statement in your code, then run `dep ensure`. However, this approach doesn't always play nicely with [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports), and also won't append a `[[constraint]]` into `Gopkg.toml`. Still, it can be useful at times, often for rapid iteration and off-the-cuff experimenting. 63 | 64 | The [ensure mechanics section on `-add`](ensure-mechanics.md#add) has a more thorough exploration, including some ways that `dep ensure -add`'s behavior subtly varies depending on the state of your project. 65 | 66 | ### Updating dependencies 67 | 68 | Ideally, updating a dependency project to a newer version is a single command: 69 | 70 | ```bash 71 | $ dep ensure -update github.com/foo/bar 72 | ``` 73 | 74 | This also works without arguments to try to update all dependencies (though it's generally not recommended): 75 | 76 | ```bash 77 | $ dep ensure -update 78 | ``` 79 | 80 | `dep ensure -update` searches for versions that work with the `branch`, `version`, or `revision` constraint defined in `Gopkg.toml`. These constraint types have different semantics, some of which allow `dep ensure -update` to effectively find a "newer" version, while others will necessitate hand-updating the `Gopkg.toml`. The [ensure mechanics](ensure-mechanics.md#update-and-constraint-types) guide explains this in greater detail, but if you want to know what effect a `dep ensure -update` is likely to have for a particular project, the `LATEST` field in `dep status` output will tell you. 81 | 82 | ### Adding and removing `import` statements 83 | 84 | As noted in [the section on adding dependencies](#adding-a-new-dependency), dep relies on the `import` statements in your code to figure out which dependencies your project actually needs. Thus, when you add or remove import statements, dep often needs to care about it. 85 | 86 | Only if one of the following has occurred will a `dep ensure` be necessary to bring the project back in sync: 87 | 88 | 1. You've added the first `import` of a package, but already `import` other packages from that project. 89 | 2. You've removed the last `import` of a package, but still `import` other packages from that project. 90 | 3. You've added the first `import` of any package within a particular project. (Note: this is the [alternate adding approach](#adding-a-new-dependency)) 91 | 4. You've removed the last `import` of a package from within a particular project. 92 | 93 | In short, dep is concerned with the set of unique import paths across your entire project, and only cares when you make a change that adds or removes an import path from that set. `dep check` will quickly report any such issues, which will be resolved by running `dep ensure`. 94 | 95 | ### Rule changes in `Gopkg.toml` 96 | 97 | `Gopkg.toml` files contain five basic types of rules. The [`Gopkg.toml` docs](Gopkg.toml.md) explain them in detail, but here's an overview: 98 | 99 | * `required`, which are mostly equivalent to `import` statements in `.go` files, except that it's OK to list a `main` package here 100 | * `ignored`, which causes dep to black hole an import path (and any imports it uniquely introduces) 101 | * `[[constraint]]`, stanzas that express version constraints and some other rules on a per-project dependency basis 102 | * `[[override]]`, stanzas identical to `[[constraint]]` except that only the current project can express them and they supersede `[[constraint]]` in both the current project and dependencies 103 | * `[prune]`, global and per-project rules that govern what kinds of files should be removed from `vendor/` 104 | 105 | Changes to any one of these rules will likely necessitate changes in `Gopkg.lock` and `vendor/`; a single successful `dep ensure` run will incorporate all such changes at once, bringing your project back in sync. 106 | 107 | ## Visualizing dependencies 108 | 109 | Generate a visual representation of the dependency tree by piping the output of `dep status -dot` to [graphviz](http://www.graphviz.org/). 110 | 111 | ### Linux 112 | 113 | ``` 114 | $ sudo apt-get install graphviz 115 | $ dep status -dot | dot -T png | display 116 | ``` 117 | 118 | ### macOS 119 | 120 | ``` 121 | $ brew install graphviz 122 | $ dep status -dot | dot -T png | open -f -a /Applications/Preview.app 123 | ``` 124 | 125 | ### Windows 126 | 127 | ``` 128 | > choco install graphviz.portable 129 | > dep status -dot | dot -T png -o status.png; start status.png 130 | ``` 131 | 132 | ![status graph](assets/StatusGraph.png) 133 | 134 | ## Key Takeaways 135 | 136 | Here are the key takeaways from this guide: 137 | 138 | * `dep check` will quickly report any ways in which your project is out of [sync](glossary.md#sync). 139 | * `dep ensure -update` is the preferred way to update dependencies, though it's less effective for projects that don't publish semver releases. 140 | * `dep ensure -add` is usually the easiest way to introduce new dependencies, though you can also just add new `import` statements then run `dep ensure`. 141 | * If you ever make a manual change in `Gopkg.toml`, it's best to run `dep ensure` to make sure everything's in sync. 142 | * `dep ensure` is almost never the wrong thing to run; if you're not sure what's going on, running it will bring you back to safety ("the nearest lilypad"), or fail informatively. 143 | 144 | Also, a couple other miscellaneous tidbits: 145 | 146 | * As in the Go toolchain generally, avoid symlinks within your own project. dep tolerates a bit of this, but like the Go toolchain itself, is generally not terribly supportive of symlinks. 147 | * Never directly edit anything in `vendor/`; dep will unconditionally overwrite such changes. If you need to modify a dependency, fork it and do it properly. 148 | -------------------------------------------------------------------------------- /docs/ensure-mechanics.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: ensure-mechanics 3 | title: 模型 和 机制 4 | --- 5 | 6 | Dep具有许多分离的元件和运动部件,所有这些部件围绕中心模型旋转.该文件解释了模型,然后在该模型的背景下探讨Dep的主要机制. 7 | 8 | ## 状态与流程 9 | 10 | Dep的核心思想是"四状态系统"——对磁盘与包管理器交流的状态进行分类和组织的模型. 这个连贯的、通用的模型，首次表述在[这篇(长)文章](https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527)。 虽然四种状态模型中的许多原理是，从现有的包管理器中派生出来的. 11 | 12 | 简言之,这四种状态是: 13 | 14 | 1. [当前项目](glossary.zh.md#current-project)的源代码. 15 | 2. 一个[主内容-manifest](glossary.zh.md#manifest)-描述当前项目的依赖要求的文件.在Dep中,就是[`Gopkg.toml`](Gopkg.toml.zh.md)文件. 16 | 3. 一个[锁-lock](glossary.zh.md#lock)-一个包含传递完整的、可再现的依赖图的描述文件.在Dep中,就是[`Gopkg.lock`](Gopkg.lock.zh.md)文件. 17 | 4. 源代码本身的依赖性.在Dep的当前设计中,就是`vendor/`目录. 18 | 19 | 我们可以直观地表示这四个状态如下: 20 | 21 | ![dep's four states](assets/four-states.png) 22 | 23 | ### 功能流程 24 | 25 | 把Dep认为是一种系统，有助于你理解,它在这些状态关系之间施加单向的、功能性的流动过程.这些函数将上述状态作为输入和输出, 若将它们从左向右移动.总体,有两个功能: 26 | 27 | - 一个是*求解-solving 函数*，将当前项目中的导入集合和规则，作为`Gopkg.toml`的输入, 并返回一个传递完整的、不可变的依赖图的输出——`Gopkg.lock`中的信息. 28 | - 一个是*vendoring 函数*，将`Gopkg.lock`中获取的信息作为其输入,并确保源文件的磁盘安排,例如编译器应使用**lock**中的指定版本. 29 | 30 | 我们可以直观地表示这两个函数: 31 | 32 | ![dep's two main functions](assets/annotated-func-arrows.png) 33 | 34 | 这是`dep ensure`-典型的流程,被使用在当`Gopkg.toml`存在时.当一个项目还没有`Gopkg.toml`,`dep init`可以生成一个. 必要的流程保持不变,但改变了输入:不是读取现有的`Gopkg.toml`文件, `dep init`构造，推理出的数据。数据来自用户的GOPATH,和/或者[来自另一个工具的元数据文件](<>). 换言之,`dep init`自动将项目从其他组织依赖的方法迁移到Dep方式. 35 | 36 | 此图也直接反映了代码. **求解函数**实际上被分解成一个构造和一个方法——我们首先新建一个[`Solver`](https://godoc.org/github.com/golang/dep/gps#Solver)类型,然后调用它的`Solve()`方法. 构造函数的输入是一个[`SolveParameters`](https://godoc.org/github.com/golang/dep/gps#SolveParameters)封装结构, 看起来应该很熟悉: 37 | 38 | ```go 39 | type SolveParameters struct { 40 | RootPackageTree pkgtree.PackageTree // Parsed project src; contains lists of imports 41 | Manifest gps.RootManifest // Gopkg.toml 42 | ... 43 | } 44 | ``` 45 | 46 | **vendoring 函数**是[`gps.WriteDepTree()`](https://godoc.org/github.com/golang/dep/gps#WriteDepTree). 虽然需要少量的参数,但相关的参数也就[`gps.Lock`](https://godoc.org/github.com/golang/dep/gps#Lock)-表示在一个`Gopkg.lock`中保存数据的抽象接口. 47 | 48 | 四状态系统和这些功能流程是所有Dep行为建立的基础. 如果你想了解Dep的机制, 请把这个模型放在你的思维的最前沿. 49 | 50 | ### 保持同步 51 | 52 | dep的设计目标之一, 是它的两个"功能",它们所做的工作,以及它们在各自的输出中引起的变化，都是最小/少的. 因此,这两个函数窥视在之前存在的输出结果, 以了解实际需要做什么工作: 53 | 54 | - **求解-Solving 函数**，检查现有的`Gopkg.lock`, 以确定其所有输入是否满足.如果是,则可以完全绕过求解函数. 如果不是,则求解函数继续进行,但会尝试`Gopkg.lock`尽可能变化很少的'路'. 55 | - **vendoring函数**，已经哈希处理了每个离散项目，放在`vendor/`. 并看看`Gopkg.lock`指示的和磁盘上的代码. 只有哈希错配的项目才被重写. 56 | 57 | 具体地说,Dep定义了一些必须满足的多个不变量: 58 | 59 | | 同步 不变 | 处理 when 不同步 | 函数 | 60 | | -------------- | ------------------------ | ---- | 61 | | `Gopkg.toml`所有的 [`required`](Gopkg.toml.zh.md#required) 声明必须存在于`Gopkg.lock`的[`input-imports`](Gopkg.lock.zh.md#input-imports)列表中 . | 对变化的项目，重新-求解, 更新 `Gopkg.lock` 和 `vendor/` | Solving | 62 | | 在当前项目的 非-[`ignored`]((Gopkg.toml.zh.md#ignored)), 非-隐藏 包的 所有 `import` 声明 必须存在于`Gopkg.lock`的[`input-imports`](Gopkg.lock.zh.md#input-imports)列表中. | 对变化的项目，重新-求解, 更新 `Gopkg.lock` 和 `vendor/` | Solving | 63 | | [`Gopkg.lock`的 所有 versions](Gopkg.lock.zh.md#version-information-revision-version-and-branch) 必须接受和遵循 `Gopkg.toml` 的 `[[constraint]]` 或 `[[override]]` 声明模式 . | 对变化的项目，重新-求解, 更新 `Gopkg.lock` 和 `vendor/` | Solving | 64 | | `Gopkg.lock`中 每个 `[[project]]` 的 [`pruneopts`](Gopkg.lock.zh.md#pruneopts) 必须等于 `Gopkg.toml`中的声明. | 更新 `Gopkg.lock` 和 `vendor/` | Vendoring\* | 65 | | `Gopkg.lock`中 每个`[[project]]` 的 [`digest`](Gopkg.lock.zh.md#digest) 必须等于 来自`vendor/`当前哈希内容的值 | 重生成`vendor/`的这个项目, 和 若有需要，更新 `Gopkg.lock`中的新digest | Vendoring | 66 | 67 | (\*)`pruneopts`有点奇怪,因为`Gopkg.toml`和`Gopkg.lock`之间不同步, 但这并不能触发**Solving**. 68 | 69 | 70 | 71 | 如果向前查看显示同步不变量已经满足,那么相应的函数不需要做任何工作;如果不满足,则dep采取解析步骤.无论哪种方式,什么时候`dep ensure`完成后,我们可以确信,我们处于"已知良好状态",所有的不变量保持不变. 72 | 73 | `dep check`将计算所有上述关系,如果任何不变量不成立,它将打印对去同步和出口1的描述.此行为可以在每个项目基础上禁用,使用[`noverify`Gopkg.toml田野](Gopkg.toml.zh.md#noverify). 74 | 75 | ## `dep ensure`标志与行为变异 76 | 77 | 每一个`dep ensure`各种标志会影响解决和发布功能的行为,甚至影响它们是否运行.一些标志也会暂时导致项目不同步.在Dep的基本模型的背景下思考这些效应是理解正在发生的事情的最快路径. 78 | 79 | ### `-no-vendor`和`-vendor-only` 80 | 81 | 这两个标志是互斥的,并决定哪一个`dep ensure`这两个函数实际上是被执行的.经过`-no-vendor`只会导致求解函数的运行,导致创建一个新的`Gopkg.lock`;`-vendor-only`将跳过只解决版本管理功能,导致`vendor/`被重新填充`Gopkg.lock`. 82 | 83 | ![Flags to run only one or the other of dep's functions](assets/func-toggles.png) 84 | 85 | 经过`-no-vendor`有助于使解决功能无条件地运行,绕过通常进行的预检查.`Gopkg.lock`看看它是否已经满足所有输入. 86 | 87 | ### `-add` 88 | 89 | 通用的目的`dep ensure -add`是为了便于将新的依赖项引入到DepGRAM中.反之`-update`限于[源根](glossary.zh.md#source-root),例如`github.com/foo/bar`)`-add`可以以任何包导入路径作为参数(例如`github.com/foo/bar`或`github.com/foo/bar/baz`) 90 | 91 | 从概念上讲,有两种可能的东西`-add`可能是介绍.任何`dep ensure -add`运行将至少其中之一: 92 | 93 | 1. 运行求解函数以生成新的`Gopkg.lock`用新的依赖(IES) 94 | 2. 将版本约束附加到`Gopkg.toml` 95 | 96 | 这意味着两个前提条件.`dep ensure -add`其中至少有一个必须满足: 97 | 98 | 1. 命名导入路径当前不在项目的导入语句中,或者在`Gopkg.toml`的`required`列表 99 | 2. 没有`[[constraint]]`中节`Gopkg.toml`对于与命名导入路径相对应的项目根 100 | 101 | 还可以显式指定版本约束: 102 | 103 | ```bash 104 | $ dep ensure -add github.com/foo/bar@v1.0.0 105 | ``` 106 | 107 | 当参数中不包含版本约束时,求解函数将选择工作的最新版本(通常,最新的semver版本,如果没有semver版本,则选择默认的分支).如果求解成功,那么参数指定的版本,或者如果没有,那么由求解器选择的版本将被附加到`Gopkg.toml`. 108 | 109 | 由输入和当前项目状态的各种差异引起的行为变化最好用矩阵表示: 110 | 111 | | Argument to `dep ensure -add` | Has `[[constraint]]` stanza in `Gopkg.toml` | In imports or `required` | Result | 112 | | ----------------------------- | ------------------------------------------- | ------------------------ | ------ | 113 | | `github.com/foo/bar` | N | N | Added temporarily to `Gopkg.lock` & `vendor/`; inferred version constraint appended to `Gopkg.toml` | 114 | | `github.com/foo/bar@v1.0.0` | N | N | Added temporarily to `Gopkg.lock` & `vendor/`; specified version constraint appended to `Gopkg.toml` | 115 | | `github.com/foo/bar` | Y | N | Added temporarily to `Gopkg.lock` & `vendor/` | 116 | | `github.com/foo/bar@v1.0.0` | Y | - | **Immediate error**: constraint already present in `Gopkg.toml` | 117 | | `github.com/foo/bar` | N | Y | Infer version constraint from `Gopkg.lock` and add to `Gopkg.toml` | 118 | | `github.com/foo/bar` | Y | Y | **Immediate error:** nothing to do | 119 | 120 | 对于任何路径`dep ensure -add`需要运行求解函数以便生成更新`Gopkg.lock`将来自CLI参数的相关信息应用于内存的表示.`Gopkg.toml`: 121 | 122 | ![Model modifications made by -add](assets/required-arrows.png) 123 | 124 | 需要添加的导入路径参数通过`required`列表,如果指定了明确版本要求,则等于`[[constraint]]`创建. 125 | 126 | 虽然这些规则最终会被坚持,如果解决成功,它们至少是短暂的,直到解决成功.从求解者的角度来看,短暂的规则与源于磁盘的规则是难以区分的.因此,对求解器,`dep ensure -add foo@v1.0.0`与修改相同`Gopkg.toml`通过添加`"foo"`到`required`列表,加上`[[constraint]]`节与`version = "v1.0.0"`然后运行`dep ensure`. 127 | 128 | 然而,因为这些修改是短暂的,是成功的.`dep ensure -add`可能实际上推动项目不同步.约束修改通常没有,但是如果`required`列表被修改,然后该项目将不同步.用户被警告: 129 | 130 | ```bash 131 | $ dep ensure -add github.com/foo/bar 132 | "github.com/foo/bar" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/. 133 | If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/. 134 | ``` 135 | 136 | ### `-update` 137 | 138 | 行为`dep ensure -update`与解决者自身的行为密切相关.关于这一点的完整细节是[求解参考材料](the-solver.zh.md),但为了理解的目的`-update`我们可以简化一点. 139 | 140 | 第一,巩固讨论中的含义.[功能优化](#staying-in-sync)求解函数实际上考虑了预先存在的问题.`Gopkg.lock`运行时: 141 | 142 | ![Pre-existing lock feeds back into solving function](assets/lock-back.png) 143 | 144 | 注射`Gopkg.lock`进入解决者是必要的.如果我们希望解决方案默认保存先前选定的版本,那么求解器必须了解现有的.`Gopkg.lock`从某处.否则,它就不知道该保存什么了! 145 | 146 | 这样,锁是另一个编码到属性的属性.[先前讨论](<>) `SolveParameters`结构.这加上另外两个属性,是最显著的.`-update`: 147 | 148 | ```go 149 | type SolveParameters struct { 150 | ... 151 | Lock gps.Lock // Gopkg.lock 152 | ToChange []gps.ProjectRoot // args to -update 153 | ChangeAll bool // true if no -update args passed 154 | ... 155 | } 156 | ``` 157 | 158 | 通常,当求解器遇到一个项目名称时,它有一个条目`Gopkg.lock`它把这个版本拉出来,放到这个项目的可能版本队列的头上.当特定的依赖性传递给`dep ensure -update`然而,它被添加到`ToChange`当解决方案遇到一个列出的项目时`ToChange`它只是跳过锁中的版本. 159 | 160 | "跳过从锁中拉出版本"意味着`dep ensure -update github.com/foo/bar`等同于移除`[[project]]`诗节`github.com/foo/bar`从你`Gopkg.lock`然后运行`dep ensure`. 然而,确实不推荐使用这种方法,而且将来可能会引入一些细微的改变,使等效性复杂化. 161 | 162 | 如果`-update`没有参数传递,则`ChangeAll`设置为`true`导致解算器忽略`Gopkg.lock`对于所有新遇到的项目名称.这相当于将所有依赖项显式传递为参数.`dep ensure -update`以及`rm Gopkg.lock && dep ensure`. 然而,这两种方法都不被推荐,未来的变化可能带来微妙的差异. 163 | 164 | 当版本提示从`Gopkg.lock`不是放在版本队列的最前面,这意味着dep将探索特定依赖项的可能版本集.这种探索是按照A来进行的.[固定排序顺序](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade),首先尝试更新版本,导致更新. 165 | 166 | 比如说有一个项目,`github.com/foo/bar`,以下版本: 167 | 168 | ```bash 169 | v1.2.0, v1.1.1, v1.1.0, v1.0.0, master 170 | ``` 171 | 172 | 如果我们依赖那个项目`^1.1.0`并拥有`v1.1.0`在我们`Gopkg.lock`这意味着有三个版本与我们的约束相匹配,其中两个版本比当前选择的版本要更新.(还有一个较旧的版本,`v1.0.0`和A`master`分支,但这些是不允许的`^1.1.0`约束)一个普通的`dep ensure`运行将复制和推`v1.1.0`排在队伍前面的其他人: 173 | 174 | ```bash 175 | [v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master] 176 | ``` 177 | 178 | 和`v1.1.0`将再次被选中,除非出现一些其他条件迫使解算器丢弃它.跑步时`dep ensure -update github.com/foo/bar`然而,锁定的版本没有准备好: 179 | 180 | ```bash 181 | [v1.2.0, v1.1.1, v1.1.0, v1.0.0, master] 182 | ``` 183 | 184 | 所以,除了一些其他的冲突,`v1.2.0`被选择,导致期望的更新. 185 | 186 | #### `-update`约束类型 187 | 188 | 继续我们的例子,重要的是要注意更新`-update`顺便说一下,解决者从来没有明确地针对更新的版本.它只是跳过从锁中添加一个提示,然后在队列中选择满足约束的第一个版本.因此,`-update`只对某些类型的约束有效. 189 | 190 | 它确实适用于分支约束,我们可以通过包括基础修订来观察.如果用户已受到限制`branch = "master"`和`Gopkg.lock`点在一个拓扑旧版本(例如,`aabbccd`)比规范源的顶端`master`分支(如:`bbccdde`)`dep ensure`最终将构建一个看起来像这样的队列: 191 | 192 | ```bash 193 | [master@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master@bbccdde] 194 | ``` 195 | 196 | 用`-update`头部的暗示将被省略;`branch = "master"`将导致求解器拒绝所有语义版本,并最终解决.`master@bbccdde`. 197 | 198 | 版本队列中的所有版本都跟踪底层修订,这意味着如果,例如,一些上游项目强制推送git标记,那么情况也是如此: 199 | 200 | ```bash 201 | [v1.1.0@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0@bbccdde, v1.0.0, master] 202 | ``` 203 | 204 | 因此,即使上游标记在项目的一个依赖项中被强制推送,dep将保留原始修订,直到您显式地允许它通过`dep ensure -update`. 205 | 206 | 这里的关键是`-update`的行为受指定的约束类型的约束: 207 | 208 | | `Gopkg.toml` version constraint type | Constraint example | `dep ensure -update` behavior | 209 | | ------------------------------------ | ------------------ | ----------------------------- | 210 | | `version` (semver range) | `"^1.0.0"` | Tries to get the latest version allowed by the range | 211 | | `branch` | `"master"` | Tries to move to the current tip of the named branch | 212 | | `version` (non-range semver) | `"=1.0.0"` | Change can only occur if the upstream release was moved (e.g. `git push --force `) | 213 | | `version` (non-semver) | `"foo"` | Change can only occur if the upstream release was moved | 214 | | `revision` | `aabbccd...` | No change is possible | 215 | | (none) | (none) | The first version that works, according to [the sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade) | 216 | -------------------------------------------------------------------------------- /docs/migrating.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Migrating to Dep 3 | --- 4 | 5 | Ideally, migrating an existing Go project to dep is straightforward: 6 | 7 | ```bash 8 | $ cd $GOPATH/src/path/to/project/root 9 | $ dep init 10 | ``` 11 | 12 | For many projects, this will just work. `dep init` will make educated guesses about what versions to use for your dependencies, generate sane `Gopkg.toml`, `Gopkg.lock`, and `vendor/`, and if your tests pass and builds work, then you're probably done. (If so, congratulations! You should check out [Daily Dep](daily-dep.md) next.) 13 | 14 | The migration process is still difficult for some projects. If you're trying dep for the first time, this can be particularly frustrating, as you're trying to simultaneously learn how to use dep, and how your project _should_ be managed in dep. The good news is, `dep init` is usually the big difficulty hump; once you're over it, things get much easier. 15 | 16 | The goal of this guide is to provide enough information for you to reason about what's happening during `dep init`, so that you can at least understand what class of problems you're encountering, and what steps you might take to address them. To that end, we'll start with an overview of what `dep init` is doing. 17 | 18 | > Note: the first run of `dep init` can take quite a long time, as dep is creating fresh clones of all your dependencies into a special location, `$GOPATH/pkg/dep/sources/`. This is necessary for dep's normal operations, and is largely a one-time cost. 19 | 20 | ## `dep init` mechanics 21 | 22 | When migrating existing projects, the primary goal of `dep init` is to automate as much of the work of creating a `Gopkg.toml` as possible. This is necessarily a heuristic goal, as dep may not have a 1:1 correspondence for everything you may have done before. As such, it's important to only expect that `dep init`'s automated migrations are operating on a best-effort basis. 23 | 24 | The behavior of `dep init` varies depending on what's in your existing codebase, and the flags that are passed to it. However, it always proceeds in two phases: 25 | 26 | 1. _Inference phase:_ Infer, from various sources, rules and hints about which versions of dependencies to use. 27 | 2. _Solving phase:_ Work out a solution that is acceptable under dep's model, while incorporating the above inferences as much as possible. 28 | 29 | ### The Inference Phase 30 | 31 | The inference phase is where `dep init`'s behavior varies. By default, `dep init` will look in your codebase for metadata files from [other Go package management tools that it understands](https://github.com/golang/dep/tree/master/internal/importers), and attempt to automatically migrate the data in these files into concepts that make sense in a dep. Depending on the tool and the particular values dep finds, metadata from the tool may be treated as either: 32 | 33 | * A hint: information that dep will try to honor in the solving phase, but will discard if it cannot find a solution that respects the hint. 34 | * A rule: information that must obeyed in the solving phase, and will ultimately appear in `Gopkg.toml` as a `[[constraint]]`. If the solving phase cannot find a solution that satisfies the rules, it will fail with an informative message. 35 | 36 | There are three circumstances that can lead dep not to make any tool-based inferences: 37 | 38 | * Your project doesn't use a package management tool 39 | * dep doesn't yet support the tool you use yet 40 | * You tell it not to, by running `dep init -skip-tools` 41 | 42 | After tool-based inference is complete, dep will normally proceed to the solving phase. However, if the user passes the `-gopath` flag, dep will first try to fill in any holes in the inferences drawn from tool metadata by checking the current project's containing GOPATH. Only hints are gleaned from GOPATH, and they will never supersede inferences from tool metadata. If you want to put GOPATH fully in charge, pass both flags: `dep init -skip-tools -gopath`. 43 | 44 | Once dep has compiled its set of inferences, it proceeds to solving. 45 | 46 | ### The Solving Phase 47 | 48 | Once the inference phase is completed, the set of rules and hints dep has assembled will be passed to its [solver](the-solver.md) to work out a transitively complete depgraph, which will ultimately be recorded as the `Gopkg.lock`. This is the same solving process used by `dep ensure`, and completing it successfully means that dep has found a combination of dependency versions that respects all inferred rules, and as many inferred hints as possible. If solving succeeds, then the hard work is done; most of what remains is writing out `Gopkg.toml`, `Gopkg.lock`, and `vendor/`. 49 | 50 | The solver returns a solution, which itself is just [a representation](https://godoc.org/github.com/golang/dep/gps#Solution) of [the data stored in a `Gopkg.lock`](https://godoc.org/github.com/golang/dep#Lock): a transitively-complete, reproducible snapshot of the entire dependency graph. Writing out the `Gopkg.lock` from a solution is little more than a copy-and-encode operation, and writing `vendor/` is a matter of placing each project listed in the solution into its appropriate place, at the designated revision. This is exactly the same as `dep ensure`'s behavior. 51 | 52 | `Gopkg.toml` is a little different. There's no guarantee that rules were inferred for all (or even any) of your project's dependencies, but we still want to populate `Gopkg.toml` with sane values. So, for any dependency for which a rule was not inferred, dep inspects the solution to see what version was ultimately selected, and creates a constraint based on that: 53 | 54 | * If a branch, like `master`, was picked in the solution, then `branch: "master"` will appear in `Gopkg.toml`. 55 | * If a semantic version-compliant version was selected, like `v1.2.0`, then that will be specified as a minimum version: `version: "v1.2.0"`. 56 | * If only a raw revision was selected, nothing will be put in `Gopkg.toml`. While dep does allow `revision: "…"` constraints in `Gopkg.toml`, use of them is considered an antipattern, so dep does not create them automatically in order to avoid implicitly encouraging their use. 57 | 58 | ## Dealing with failures 59 | 60 | First and foremost, make sure that you're running `dep init` with the `-v` flag. That will provide a lot more information. 61 | 62 | `dep init`, like dep in general, has both hard and soft failure modes. Hard failures result in the process hanging or aborting entirely, without anything being written to disk. Soft failures may or may not include warnings, but do ultimately write out a `Gopkg.toml`, `Gopkg.lock`, and `vendor/` - just, not the ones you wanted. Before we dig into those, though, let's set some context. 63 | 64 | While dep contributors have invested enormous effort into creating automated migration paths into dep, these paths will always best-effort and imprecise. It's simply not always possible to convert from other tools or GOPATH with full fidelity. dep is an opinionated tool, with a correspondingly opinionated model, and that model does sometimes fundamentally differ from that of other tools. Sometimes these model mismatches result in hard failures, sometimes soft, and sometimes there's no harm at all. 65 | 66 | Because these are deep assumptions, their symptoms can be varied and surprising. Keeping these assumptions in mind could save you some hair-pulling later on. 67 | 68 | * dep does not allow nested `vendor/` directories; it flattens all dependencies to the topmost `vendor/` directory, at the root of your project. This is foundational to dep's model, and cannot be disabled. 69 | * dep wholly controls `vendor`, and will blow away any manual changes or additions made to it that deviate from the version of an upstream source dep selects. 70 | * dep requires that all packages from a given project/repository be at the same version. 71 | * dep generally does not care about what's on your GOPATH; it deals exclusively with projects sourced from remote network locations. (Hint inference is the only exception to this; once solving begins, GOPATH - and any custom changes you've made to code therein - is ignored.) 72 | * dep generally prefers semantic versioning-tagged releases to branches (when not given any additional rules). This is a significant shift from the "default branch" model of `go get` and some other tools. It can result in dep making surprising choices for dependencies for which it could not infer a rule. 73 | * dep assumes that all generated code exists, and has been committed to the source. 74 | 75 | A small number of projects that have reported being unable, thus far, to find a reasonable way of adapting to these requirements. If you can't figure out how to make your project fit, please file an issue - while dep necessarily cannot accommodate every single existing approach, it is dep's goal is define rules to which all Go projects can reasonably adapt. 76 | 77 | ### Hard failures 78 | 79 | All of the hard failure modes are covered extensively in the reference on [failure modes](failure-modes.md). 80 | 81 | Because the solver, and all its possible failures, are the same for `dep init` as for `dep ensure`, there's a separate section for understanding and dealing with them: [dealing with solving failures](failure-modes.md#solving-failures). It can be trickier with `dep init`, however, as many remediations require tweaking `Gopkg.toml`. 82 | 83 | Unfortunately, `dep init` does not write out a partial `Gopkg.toml` when it fails. This is a known, critical problem, and [we have an open issue (help wanted!)](https://github.com/golang/dep/issues/909). 84 | 85 | In the meantime, if the particular errors you are encountering do entail `Gopkg.toml` tweaks, you unfortunately may have to do without the automation of `dep init`: create an empty [`Gopkg.toml`](Gopkg.toml.md), and populate it with rules by hand. Before resorting to that, make sure you've run `dep init` with various combinations of the inferencing flags (`-skip-tools` and `-gopath`) to see if they can at least give you something to start from. 86 | 87 | ### Soft failures 88 | 89 | Soft failures are cases where `dep init` appears to exit cleanly, but a subsequent `go build` or `go test` fails. Dep's soft failures are usually more drastically than subtly wrong - e.g., an explosion of type errors when you try to build, because a wildly incorrect version for some dependency got selected. 90 | 91 | If you do encounter problems like this, `dep status` is your first diagnostic step; it will report what versions were selected for all your dependencies. It may be clear which dependencies are a problem simply from your building or testing error messages. If not, compare the `dep status` list against the versions recorded by your previous tool to find the differences. 92 | 93 | Once you've identified the problematic dependenc(ies), the next step is exerting appropriate controls over them via `Gopkg.toml`. 94 | 95 | For each of the following items, assume that you should run `dep ensure` after making the suggested change. If that fails, consult [dealing with solving failures](). 96 | 97 | * If the wrong `[[constraint]]` was inferred for one of your direct dependencies, change it. Then, file an issue against dep (please!) - while `dep init` may choose to omit a constraint, converting one incorrectly is considered a bug. 98 | * If one of your transitive dependencies is at the wrong version, define an `[[override]]` on it to force it to the version you need. 99 | * If the version you need is a specific git commit, it's preferable to instead manually change the `revision` to the desired hash in `Gopkg.lock` for that project, then drop the `version` or `branch` fields (if any). 100 | * If one of your direct dependencies is at the wrong version and there's no `[[constraint]]` on it in `Gopkg.toml` already, then define an appropriate one. 101 | * As with the transitive dependencies, if the version you need is a specific git commit, prefer doing that manually in `Gopkg.lock`. 102 | 103 | Hopefully this information is enough to get you through your project's migration to dep. If not, please feel free to file an issue, or join us in [#vendor on the Gopher's slack](https://gophers.slack.com/messages/C0M5YP9LN) for help! 104 | -------------------------------------------------------------------------------- /docs/Gopkg.toml.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gopkg.toml 3 | --- 4 | 5 | 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: 6 | 7 | * _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. 8 | * _Package graph rules:_ [`required`](#required) and [`ignored`](#ignored) allow the user to manipulate the import graph by including or excluding import paths, respectively. 9 | * [`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. 10 | * [`prune`](#prune) settings determine what files and directories can be deemed unnecessary, and thus automatically removed from `vendor/`. 11 | * [`noverify`](#noverify) is a list of project roots for which [vendor verification](glossary.md#vendor-verification) is skipped. 12 | 13 | Note that because TOML does not adhere to a tree structure, the `required` and `ignored` fields must be declared before any `[[constraint]]` or `[[override]]`. 14 | 15 | 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. 16 | 17 | ## Dependency rules: `[[constraint]]` and `[[override]]` 18 | 19 | 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: 20 | 21 | * `name` - the import path corresponding to the [source root](glossary.md#source-root) of a dependency (generally: where the VCS root is) 22 | * At most one [version rule](#version-rules) 23 | * An optional [`source` rule](#source) 24 | * [`metadata`](#metadata) that is specific to the `name`'d project 25 | 26 | 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: 27 | 28 | ```toml 29 | [[constraint]] 30 | # Required: the root import path of the project being constrained. 31 | name = "github.com/user/project" 32 | # Recommended: the version constraint to enforce for the project. 33 | # Note that only one of "branch", "version" or "revision" can be specified. 34 | version = "1.0.0" 35 | branch = "master" 36 | revision = "abc123" 37 | 38 | # Optional: an alternate location (URL or import path) for the project's source. 39 | source = "https://github.com/myfork/package.git" 40 | 41 | # Optional: metadata about the constraint or override that could be used by other independent systems 42 | [metadata] 43 | key1 = "value that convey data to other systems" 44 | system1-data = "value that is used by a system" 45 | system2-data = "value that is used by another system" 46 | ``` 47 | 48 | ### `[[constraint]]` 49 | 50 | 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. 51 | 52 | **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). 53 | 54 | ### `[[override]]` 55 | 56 | 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. 57 | 58 | **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) 59 | 60 | Overrides should be used cautiously and temporarily, when possible. 61 | 62 | ### `source` 63 | 64 | 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. 65 | 66 | `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. 67 | 68 | ### Version rules 69 | 70 | 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. 71 | 72 | #### `version` 73 | 74 | `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. 75 | 76 | Specifying semantic version ranges can be done using the following operators: 77 | 78 | * `=`: equal 79 | * `!=`: not equal 80 | * `>`: greater than 81 | * `<`: less than 82 | * `>=`: greater than or equal to 83 | * `<=`: less than or equal to 84 | * `-`: literal range. E.g., 1.2 - 1.4.5 is equivalent to >= 1.2, <= 1.4.5 85 | * `~`: minor range. E.g., ~1.2.3 is equivalent to >= 1.2.3, < 1.3.0 86 | * `^`: major range. E.g., ^1.2.3 is equivalent to >= 1.2.3, < 2.0.0 87 | * `[xX*]`: wildcard. E.g., 1.2.x is equivalent to >= 1.2.0, < 1.3.0 88 | 89 | 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. 90 | 91 | **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: 92 | 93 | * `1.2.3` becomes the range `>=1.2.3, <2.0.0` 94 | * `0.2.3` becomes the range `>=0.2.3, <0.3.0` 95 | * `0.0.3` becomes the range `>=0.0.3, <0.1.0` 96 | 97 | `~` 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: 98 | 99 | ``` 100 | ^1.2.3 means 1.2.3 <= X < 2.0.0 101 | ^0.2.3 means 0.2.3 <= X < 0.3.0 102 | ^0.0.3 means 0.0.3 <= X < 0.1.0 103 | ``` 104 | 105 | To pin a version of direct dependency in manifest, prefix the version with `=`. For example: 106 | 107 | ```toml 108 | [[constraint]] 109 | name = "github.com/pkg/errors" 110 | version = "=0.8.0" 111 | ``` 112 | 113 | #### `branch` 114 | 115 | 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`. 116 | 117 | In general, you should prefer semantic versions to branches, when a project has made them available. 118 | 119 | #### `revision` 120 | 121 | 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. 122 | 123 | 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. 124 | 125 | ## Package graph rules: `required` and `ignored` 126 | 127 | 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. 128 | 129 | ### `required` 130 | 131 | `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. 132 | 133 | ```toml 134 | required = ["github.com/user/thing/cmd/thing"] 135 | ``` 136 | 137 | **Use this for:** linters, generators, and other development tools that 138 | 139 | * Are needed by your project 140 | * Aren't `import`ed by your project, [directly or transitively](FAQ.md#what-is-a-direct-or-transitive-dependency) 141 | * You don't want to put them in your `GOPATH`, and/or you want to lock the version 142 | 143 | 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`: 144 | 145 | ```bash 146 | cd vendor/pkg/to/install 147 | go install . 148 | ``` 149 | 150 | This only works reliably if this is the only project to install these executables. This is not enough if you want to be able to run a different version of the same executable depending on the project you're working. In that case you have to use a different `GOBIN` for each project, by doing something like this before running the above commands: 151 | 152 | ```bash 153 | export GOBIN=$PWD/bin 154 | export PATH=$GOBIN:$PATH 155 | ``` 156 | 157 | You might also try [virtualgo](https://github.com/GetStream/vg), which installs dependencies in the `required` list automatically in a project specific `GOBIN`. 158 | 159 | ### `ignored` 160 | 161 | `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. 162 | 163 | ```toml 164 | ignored = ["github.com/user/project/badpkg"] 165 | ``` 166 | 167 | 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 `*`. 168 | 169 | ```toml 170 | ignored = ["github.com/user/project/badpkg*"] 171 | ``` 172 | 173 | **Use this for:** preventing a package, and any of that package's unique dependencies, from being incorporated in `Gopkg.lock`. 174 | 175 | ## `metadata` 176 | 177 | `metadata` can exist at the root as well as under `constraint` and `override` declarations. 178 | 179 | `metadata` declarations are ignored by dep and are meant for usage by other independent systems. 180 | 181 | The root `metadata` declaration defines information about the project itself, while a `metadata` declaration under a `[[constraint]]` or an `[[override]]` defines metadata about that rule, for the `name`d project. 182 | 183 | ```toml 184 | [metadata] 185 | key1 = "value that convey data to other systems" 186 | system1-data = "value that is used by a system" 187 | system2-data = "value that is used by another system" 188 | ``` 189 | 190 | ## `prune` 191 | 192 | `prune` defines the global and per-project prune options for dependencies. The options determine which files are discarded when writing the `vendor/` tree. 193 | 194 | The following are the current available options: 195 | 196 | * `unused-packages` indicates that files from directories that do not appear in the package import graph should be pruned. 197 | * `non-go` prunes files that are not used by Go. 198 | * `go-tests` prunes Go test files. 199 | 200 | Out of an abundance of caution, dep non-optionally preserves files that may have legal significance. 201 | 202 | Pruning options are disabled by default. However, generating a `Gopkg.toml` via `dep init` will add lines to enable `go-tests` and `unused-packages` prune options at the root level. 203 | 204 | ```toml 205 | [prune] 206 | go-tests = true 207 | unused-packages = true 208 | ``` 209 | 210 | The same prune options can be defined per-project. An additional `name` field is required and, as with `[[constraint]]` and `[[override]]`, should be a [source root](glossary.md#source-root), not just any import path. 211 | 212 | ```toml 213 | [prune] 214 | non-go = true 215 | 216 | [[prune.project]] 217 | name = "github.com/project/name" 218 | go-tests = true 219 | non-go = false 220 | ``` 221 | 222 | Almost all projects will be fine without setting any project-specific rules, and enabling the following pruning rules globally: 223 | 224 | ```toml 225 | [prune] 226 | unused-packages = true 227 | go-tests = true 228 | ``` 229 | 230 | It is usually safe to set `non-go = true`, as well. However, as dep only has a clear model for the role played by Go files, and non-Go files necessarily fall outside that model, there can be no comparable general definition of safety. 231 | 232 | ## `noverify` 233 | 234 | The `noverify` field is a list of paths, typically [project roots](glossary.md#project-root), to exclude from [vendor verification](glossary.md#vendor-verification). 235 | 236 | Dep uses per-project hash digests, computed after pruning and recorded in [Gopkg.lock](Gopkg.lock.md#digest), to determine if the contents of `vendor/` are as expected. If the recorded digest and the hash of the corresponding tree in `vendor/` differ, that project is considered to be out of sync: 237 | 238 | * `dep ensure` will regenerate it 239 | * `dep check` will complain of a hash mismatch and exit 1 240 | 241 | It is strongly recommended that you leave `vendor/` unmodified, in whatever state dep puts it in. However, this isn't always feasible. If you have no choice but to modify `vendor/` for a particular project, then add the project root for that project to `noverify`. This will have the following effects: 242 | 243 | * `dep ensure` will ignore hash mismatches for the project, and only regenerate it in `vendor/` if absolutely necessary (prune options change, package list changes, version changes) 244 | * `dep check` will continue to report hash mismatches (albeit with an annotation about `noverify`) for the project, but will no longer exit 1. 245 | 246 | `noverify` can also be used to preserve certain excess paths that would otherwise be removed; for example, adding `WORKSPACE` to the `noverify` list would allow you to preserve `vendor/WORKSPACE`, which can help with some Bazel-based workflows. 247 | 248 | ## Scope 249 | 250 | `dep` evaluates 251 | 252 | * `[[override]]` 253 | * `required` 254 | * `ignored` 255 | 256 | only in the root project, i.e. the project where `dep` runs. For example, if you have a project: `github.com/urname/goproject`, and `github.com/foo/bar` is a dependency for your project, then dep will evaluate the `Gopkg.toml` files of these projects as follows: 257 | 258 | | github.com/urname/goproject | github.com/foo/bar | 259 | | --------------------------- | ------------------ | 260 | | [[constraint]] ✔ | [[constraint]] ✔ | 261 | | [[override]] ✔ | [[override]] ✖ | 262 | | required ✔ | required ✖ | 263 | | ignored ✔ | ignored ✖ | 264 | 265 | ✔ : Evaluated 266 | ✖ : Not evaluated 267 | 268 | # Example 269 | 270 | A sample `Gopkg.toml` with most elements present: 271 | 272 | ```toml 273 | required = ["github.com/user/thing/cmd/thing"] 274 | 275 | ignored = [ 276 | "github.com/user/project/pkgX", 277 | "bitbucket.org/user/project/pkgA/pkgY" 278 | ] 279 | 280 | noverify = ["github.com/something/odd"] 281 | 282 | [metadata] 283 | codename = "foo" 284 | 285 | [prune] 286 | non-go = true 287 | 288 | [[prune.project]] 289 | name = "github.com/project/name" 290 | go-tests = true 291 | non-go = false 292 | 293 | [[constraint]] 294 | name = "github.com/user/project" 295 | version = "1.0.0" 296 | 297 | [metadata] 298 | property1 = "value1" 299 | property2 = 10 300 | 301 | [[constraint]] 302 | name = "github.com/user/project2" 303 | branch = "dev" 304 | source = "github.com/myfork/project2" 305 | 306 | [[override]] 307 | name = "github.com/x/y" 308 | version = "2.4.0" 309 | 310 | [metadata] 311 | propertyX = "valueX" 312 | ``` 313 | -------------------------------------------------------------------------------- /docs/FAQ.zh.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: FAQ 3 | --- 4 | FAQ之前的其余部分的介绍.如果这里的东西与其他指南或参考文件冲突,可能在这里是错误的-请提交PR! 5 | 6 | ## Concepts 7 | 8 | - [做`dep`代替`go get`?](#does-dep-replace-go-get) 9 | - [为什么是`dep ensure`而不是`dep install`?](#why-is-it-dep-ensure-instead-of-dep-install) 10 | - [什么是直接的或传递的依赖关系?](#what-is-a-direct-or-transitive-dependency) 11 | 12 | ## Configuration 13 | 14 | - [Gopkg.toml("清单")和Gopkg.lock("锁")的区别是什么?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock) 15 | - [如何约束传递依赖的版本?](#how-do-i-constrain-a-transitive-dependency-s-version) 16 | - [如何更改依赖项的版本?](#how-do-i-change-the-version-of-a-dependency) 17 | - [我能把清单和锁放在供应商目录中吗?](#can-i-put-the-manifest-and-lock-in-the-vendor-directory) 18 | - [我如何得到`dep`对…进行认证`git`回购协议?](#how-do-i-get-dep-to-authenticate-to-a-git-repo) 19 | - [我如何得到`dep`私下消费`git`使用GITHUB令牌吗?](#how-do-i-get-dep-to-consume-private-git-repos-using-a-github-token) 20 | 21 | ## Behavior 22 | 23 | - [如何`dep`决定使用什么版本的依赖项?](#how-does-dep-decide-what-version-of-a-dependency-to-use) 24 | - [默认值是多少`dep ensure -update`依赖于导入的但不包含为一个依赖项的行为`[[Constraint]]`在里面`Gopkg.toml`?](#what-is-the-default-dep-ensure--update-behavior-for-dependencies-that-are-imported-but-not-included-as-a-constraint-in-gopkgtoml) 25 | - [支持哪些外部工具?](#what-external-tools-are-supported) 26 | - [为什么是`dep`忽略清单中的版本约束?](#why-is-dep-ignoring-a-version-constraint-in-the-manifest) 27 | - [为什么`dep`对包X使用不同的修改,而不是锁定文件中的修订?](#why-did-dep-use-a-different-revision-for-package-x-instead-of-the-revision-in-the-lock-file) 28 | - [为什么是`dep`慢?](#why-is-dep-slow) 29 | - [如何`dep`处理符号链接?](#how-does-dep-handle-symbolic-links) 30 | - [做`dep`支持相对进口?](#does-dep-support-relative-imports) 31 | - [我该怎么做`dep`解决依赖关系`GOPATH`?](#how-do-i-make-dep-resolve-dependencies-from-my-gopath) 32 | - [威尔`dep`让我使用Git子模块来存储依赖项`vendor`?](#will-dep-let-me-use-git-submodules-to-store-dependencies-in-vendor) 33 | - [如何`dep`不改变我的套餐进口吗?](#how-does-dep-work-without-changing-my-packages-imports) 34 | 35 | ## Best Practices 36 | 37 | - [我应该提交我的供应商目录吗?](#should-i-commit-my-vendor-directory) 38 | - [如何滚动发布`dep`能用吗?](#how-do-i-roll-releases-that-dep-will-be-able-to-use) 39 | - [我应该使用什么样的SEMVER版本?](#what-semver-version-should-i-use) 40 | - [现在做出前后不兼容的变化是否可以?](#is-it-ok-to-make-backwards-incompatible-changes-now) 41 | - [我的家属不使用`dep`然而.我该怎么办?](#my-dependers-don-t-use-dep-yet-what-should-i-do) 42 | - [如何配置不标记其发布的依赖项](#how-do-i-configure-a-dependency-that-doesn-t-tag-its-releases) 43 | - [如何使用`dep`和Docker在一起?](#how-do-i-use-dep-with-docker) 44 | - [如何使用`dep`在CI?](#how-do-i-use-dep-in-ci) 45 | 46 | ## Concepts 47 | 48 | ### Does `dep` replace `go get`? 49 | 50 | 不.`dep`和`go get`服务主要是不同的目的. 51 | 52 | 以下是一些你可以使用的建议`dep`或`go get`: 53 | 54 | > 我认为DEP并不能代替Go GET,但它们都可以做类似的事情.以下是我如何使用它们: 55 | > 56 | > `go get`我想下载一个GO项目的源代码,这样我就可以自己动手,或者安装一个工具.这克隆了GopaTM下的RPO,供所有人使用. 57 | > 58 | > `dep ensure`我在代码中导入了一个新的依赖项,希望下载依赖关系,这样我就可以开始使用它了.我的工作流程是"将导入添加到代码中,然后运行DEP确保,以便更新清单/锁/供应商".这将复制项目供应商目录下的回购,并记住所使用的修订版本,以便保证每个从事项目工作的人都使用相同版本的依赖项. 59 | > 60 | > [公元376年的卡罗来纳](https://github.com/golang/dep/issues/376#issuecomment-293964655) 61 | > 62 | > 长远的眼光是一个明智的,整体一致的GO工具.我的将军是这样的`go get`是用于消耗GO代码的人,DEP家族命令是为开发它的人使用的. 63 | > 64 | > ["376"中的SDBy耶](https://github.com/golang/dep/issues/376#issuecomment-294045873) 65 | 66 | ### Why is it `dep ensure` instead of `dep install`? 67 | 68 | > 是的,我们到处找名字.[很多](https://gist.github.com/jessfraz/315db91b272441f510e81e449f675a8b). 69 | > 70 | > "确保"的概念大致是"确保我所有的本地状态——代码树、清单、锁和供应商——彼此同步."当参数被传递时,它变成"确保这个参数被满足,以及所有本地状态之间的同步." 71 | > 72 | > 我们之所以选择这种方法,是因为我们得出的结论是,允许工具在中间状态执行部分工作/退出最终会创建一个具有更多命令的工具,具有更多可能的有效退出和输入状态,并且通常充满了步枪.在这种方法中,用户拥有大多数相同的最终控制,但是行使的方式不同(通过修改代码/清单和重新运行dep来确保). 73 | > 74 | > ["371"中的SDBy耶](https://github.com/golang/dep/issues/371#issuecomment-293246832) 75 | 76 | ### What is a direct or transitive dependency? 77 | 78 | - 直接依赖项是由项目直接导入的依赖项:它们出现在来自项目的至少一个导入语句中. 79 | - 传递依赖关系是依赖关系的依赖关系.编译所需的,但不直接由代码使用. 80 | 81 | ## Configuration 82 | 83 | ### What is the difference between `Gopkg.toml` (the "manifest") and `Gopkg.lock` (the "lock")? 84 | 85 | > 清单描述用户意图,并且锁描述计算输出.在锁中不存在的清单中具有灵活性,因为"分支":"主"约束将匹配当前版本主HAPPENS的任何版本,而锁被固定到特定的版本. 86 | > 87 | > 这种灵活性很重要,因为它允许我们提供简单的命令(例如).`dep ensure -update`它可以在您指定的约束内为您管理更新过程,因为它允许您的项目(当由其他人导入时)协作地指定您自己的依赖项的约束. 88 | > 89 | > ["281"中的SDBy耶](https://github.com/golang/dep/issues/281#issuecomment-284118314) 90 | 91 | ## How do I constrain a transitive dependency's version? 92 | 93 | 首先,如果您对此感到疑惑,因为您正试图防止传递依赖的版本发生更改,那么您将处理以下问题`dep`的设计.锁定文件,`Gopkg.lock`它将使所选版本的传递依赖关系保持稳定,除非您显式地请求升级,或者无法在不更改该版本的情况下找到解决方案. 94 | 95 | 如果这不是你的用例,你仍然需要限制传递依赖性,那么你有几个选项: 96 | 97 | 1. 使传递依赖性成为直接的依赖关系,既可以使用虚拟导入,也可以使用`required`列入`Gopkg.toml`. 98 | 2. 使用重写. 99 | 100 | 超越是一把大锤,只能作为最后的手段.同时以相同的方式声明约束和重写.`Gopkg.toml`他们的行为不同: 101 | 102 | - 制约因素: 103 | 1. 可以通过任何项目清单来声明,您的清单或依赖项 104 | 2. 仅应用于声明约束的项目的直接依赖关系 105 | 3. 不得与之冲突`constraint`在任何其他项目清单中声明的条目 106 | - 超越: 107 | 1. 仅从当前/项目清单中使用 108 | 2. 全局应用,以直接和传递依赖关系 109 | 3. 取代所有清单中声明的约束,您的约束或依赖项的约束 110 | 111 | 还讨论了在一些可视化中的重写.[GPS文档](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides). 112 | 113 | ## How do I change the version of a dependency 114 | 115 | 如果你想: 116 | 117 | - 更改允许`version`/`branch`/`revision` 118 | - 切换到使用叉子 119 | 120 | 对于一个或多个依赖项,请执行以下操作: 121 | 122 | 1. 手动编辑您的`Gopkg.toml`. 123 | 2. 跑 124 | 125 | ```sh 126 | $ dep ensure 127 | ``` 128 | 129 | ## Can I put the manifest and lock in the vendor directory? 130 | 131 | 不. 132 | 133 | > 把这些文件放在里面`vendor/`会把我们具体地束缚在一起`vendor/`从长远来看.我们更喜欢对待`vendor/`作为实现细节. 134 | > 135 | > [打包管理列表](https://groups.google.com/d/msg/go-package-management/et1qFUjrkP4/LQFCHP4WBQAJ) 136 | 137 | ## How do I get dep to authenticate to a git repo? 138 | 139 | `dep`目前使用`git`在引擎盖下的命令,因此为您希望认证的每个存储库配置凭据以允许`dep`使用已验证的存储库. 140 | 141 | 首先,配置`git`使用特定存储库的凭据选项. 142 | 143 | 例如,如果您使用GITLAB,并且您希望访问`https://gitlab.example.com/example/package.git`然后,您将希望使用以下配置: 144 | 145 | ``` 146 | $ git config --global credential.https://gitlab.example.com.example yourusername 147 | ``` 148 | 149 | 在该示例中,主机名`gitlab.example.com.example`字符串似乎不正确,但实际上是主机名加上您正在访问的回购协议的名称.`username`. 尾随"您的用户名"是您将用于实际身份验证的用户名. 150 | 151 | 您还需要配置`git`使用您希望使用的身份验证提供者.您可以通过以下命令获得提供者列表: 152 | 153 | ``` 154 | $ git help -a | grep credential- 155 | credential-cache remote-fd 156 | credential-cache--daemon remote-ftp 157 | credential-osxkeychain remote-ftps 158 | credential-store remote-http 159 | ``` 160 | 161 | 然后选择合适的提供者.例如,要使用OXKEY链,您将使用以下内容: 162 | 163 | ``` 164 | git config --global credential.helper osxkeychain 165 | ``` 166 | 167 | 如果您需要为CI系统这样做,那么您可能希望使用"存储"提供程序.请参阅有关如何配置该文档的文档:[HTTPS://GIT-SCM.COM/DOCS/GIT-Cuto存储](https://git-scm.com/docs/git-credential-store) 168 | 169 | 配置后`git`您可能需要使用`git`手动一次让它存储凭据.一旦您手动检查了回购协议,它将使用存储的凭据.这至少是OXKEY链提供程序的行为. 170 | 171 | ### How do I get dep to consume private git repos using a GitHub Token? 172 | 173 | 另一种选择`dep`与私人回购公司合作使用A[个人GITHUB令牌](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)并将其配置在[`.netrc`文件](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html)如下面的例子: 174 | 175 | ``` 176 | machine github.com 177 |    login [YOUR_GITHUB_USERNAME] 178 | password [YOUR_GITHUB_TOKEN] 179 | ``` 180 | 181 | 一旦设置好,DEP将自动使用该令牌对存储库进行身份验证. 182 | 183 | ## How do I get dep to authenticate via SSH to a git repo? 184 | 185 | 您可以重写RePo URL,并使用GIT+SSH SeMMA,以下示例: 186 | 187 | ``` 188 | git config --global url."git@github.yourEnterprise.com:".insteadOf "https://github.yourEnterprise.com/" 189 | ``` 190 | 191 | ## Behavior 192 | 193 | ### How does `dep` decide what version of a dependency to use? 194 | 195 | 完整的算法是复杂的,但最重要的是要理解的是`dep`在A中尝试版本[一定顺序](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade)根据指定的约束检查是否可以接受一个版本. 196 | 197 | - 所有的SSEVER版本都是第一种,主要根据Sever 2规范进行排序,有一个例外: 198 | - Sever版本的预存排序后*全部的*非预处理的SEMVER.在这个子集中,它们首先由它们的数值成分排序,然后按它们的预版本进行词典编纂. 199 | - 接下来是缺省分支;"缺省分支"的语义是特定于底层源类型的,但是这通常是从`go get`. 200 | - 所有其他分支都是下一个,按词典分类. 201 | - 接下来,所有非半版本版本(标签)按字典排序. 202 | - 如果有的话,修订是最后的,词典编纂.修订通常不会出现在版本列表中,所以我们保持的唯一不变性就是确定性——更深层的语义,比如时间或拓扑,并不重要. 203 | 204 | 因此,给出了以下的一个版本: 205 | 206 | - Branch:`master` `devel` 207 | - Simver标签:`v1.0.0` `v1.1.0` `v1.1.0-alpha1` 208 | - 非域名标签:`footag` 209 | - 修订:`f6e74e8d` 210 | 211 | 排序升级将导致以下切片: 212 | 213 | `[v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]` 214 | 215 | 有许多因素可以消除对版本的考虑,其中最简单的是它与约束不匹配.但是如果你想弄明白为什么`dep`就是做它做的事情,理解它的基本作用是尝试按照这种顺序进行版本,这应该可以帮助您对正在发生的事情进行推理. 216 | 217 | ## What is the default `dep ensure -update` behavior for dependencies that are imported but not included as a `[[Constraint]]` in `Gopkg.toml`? 218 | 219 | `dep`更新对最新的Sever标签的依赖关系.如果没有SAMVER标签,`dep`使用大师的提示. 220 | 221 | ## What external tools are supported? 222 | 223 | 期间`dep init`从其他依赖管理器的配置被检测并导入,除非`-skip-tools`指定. 224 | 225 | 支持以下工具:`glide`,`godep`,`vndr`,`govend`,`gb`,`gvt`,`govendor`和`glock`. 226 | 227 | 见[α186](https://github.com/golang/dep/issues/186#issuecomment-306363441)如何添加对另一个工具的支持. 228 | 229 | ## Why is `dep` ignoring a version constraint in the manifest? 230 | 231 | 只有项目的直接导入依赖项受`constraint`清单中的条目.传递依赖性不受影响.见[如何约束传递依赖的版本](#how-do-i-constrain-a-transitive-dependency-s-version)? 232 | 233 | ## Why did `dep` use a different revision for package X instead of the revision in the lock file? 234 | 235 | 有时在锁定文件中指定的修订不再有效.这可能会发生以下几种情况: 236 | 237 | - 生成锁文件时,在您的包X存储库的本地副本中有一个未提交的提交.`GOPATH`. (这个案子很快就要结束了) 238 | - 在生成锁文件之后,新的提交被强制推送到包X的存储库,导致锁文件中的提交修订不再存在. 239 | 240 | 若要排除故障,可以将DEP的更改还原为锁,然后运行.`dep ensure -v -n`. 此命令在启用了冗长日志的干运行模式下重试命令.检查输出,如下面的警告,指示锁中的提交不再有效. 241 | 242 | ``` 243 | Unable to update checked out version: fatal: reference is not a tree: 4dfc6a8a7e15229398c0a018b6d7a078cccae9c8 244 | ``` 245 | 246 | > 锁定文件表示一组精确的、通常是不可变的版本,用于项目的整个依赖项的传递闭包.但是,"项目"可以分解为一组算法的参数.当这些输入改变时,锁也可能需要改变. 247 | > 248 | > 在大多数情况下,如果这些参数不变,那么锁仍然是正确的.你碰到了少数情况下保证不适用的情况之一.您运行dep.,并且它DID了一个解决方案,这个事实是某些参数变化的产物;这个解决方案失败了,因为这个特定的提交已经过时了,这是一个单独的问题. 249 | > 250 | > ["405"中的SDBy耶](https://github.com/golang/dep/issues/405#issuecomment-295998489) 251 | 252 | ## Why is `dep` slow? 253 | 254 | 有两件事真的很慢`dep`下来.一个是不可避免的,另一个是我们有一个计划. 255 | 256 | 不可避免的部分是最初的克隆.`dep`依赖于本地存储库的缓存(存储在`$GOPATH/pkg/dep`),这是按需填充的.不幸的是,第一`dep`运行,特别是对于大型项目,可能需要一段时间,因为所有依赖项都被克隆到缓存中. 257 | 258 | 幸运的是,这只是一个*最初的*克隆-支付一次,然后你就完成了.当你跑步的时候,这个问题会有点重复.`dep`这是第一次,有新的变更集来获取,但即使如此,这些成本只在变更集支付一次. 259 | 260 | 另一部分是检索依赖关系信息的工作.这里有三个部分: 261 | 262 | 1. 从上游源获得最新版本的列表 263 | 2. 阅读`Gopkg.toml`对于本地缓存之外的特定版本 264 | 3. 在特定版本中解析导入语句的包树 265 | 266 | 第一个需要一个或多个网络调用;第二个通常意味着类似于`git checkout`第三个是文件系统行走,加上加载和解析.`.go`文件夹.所有这些都是昂贵的操作. 267 | 268 | 幸运的是,我们可以缓存第二个和第三个.而且,当对一个不可变的标识符键入一个Git提交的Sh1散列时,该缓存可以是永久的.第一个有点棘手,但我们可以考虑避免网络完全的合理的权衡.有个问题要解决[实现持久缓存](https://github.com/golang/dep/issues/431)这是所有这些改进的大门. 269 | 270 | 还有一个主要的性能问题要困难得多——选择版本本身的过程是一个NP完全问题.`dep`目前的设计.这是一个棘手的问题. 271 | 272 | ## How does `dep` handle symbolic links? 273 | 274 | > 因为我们不是疯狂的人,他们喜欢把混乱带入我们的生活,我们需要在一个内部工作.`GOPATH`一次.-["247"中的SDBy耶](https://github.com/golang/dep/pull/247#issuecomment-284181879) 275 | 276 | 为了方便起见,人们可能会在它们的目录中创建一个链接.`GOPATH/src`,例如`ln -s ~/go/src/github.com/user/awesome-project ~/Code/awesome-project`. 277 | 278 | 什么时候?`dep`用一个SyLink的项目根来调用,它将按照以下规则来解决: 279 | 280 | - 如果SyLink在外部`GOPATH`和一个目录内的链接`GOPATH`然后,反之亦然`dep`将选择内部路径`GOPATH`. 281 | - 如果SyLink在一个`GOPATH`解决的路径在一个*不同的* `GOPATH`然后引发错误. 282 | - 如果SyLink和解析路径都是相同的`GOPATH`然后引发错误. 283 | - 如果SyLink和解析路径都不在`GOPATH`然后引发错误. 284 | 285 | 这是唯一的符号链接支持`dep`真的打算提供.与一般惯例相一致`go`工具,`dep`倾向于忽略Salink(当步行)或复制Simulink本身,这取决于正在执行的文件系统操作. 286 | 287 | ## Does `dep` support relative imports? 288 | 289 | 不. 290 | 291 | > DEP根本不允许相对进口.这是少数几个限制工具链本身允许的情况之一.我们不允许他们仅仅是因为: 292 | > 293 | > - 工具链已经对他们产生了严重的不满.
294 | > - 这对我们的情况来说更糟,因为我们开始冒险.[点地狱](http://doc.cat-v.org/plan_9/4th_edition/papers/lexnames)领土当试图证明进口不逃脱项目树 295 | > 296 | > ["899"中的SDBy耶](https://github.com/golang/dep/issues/899#issuecomment-317904001) 297 | 298 | 有关GO的推荐工作区组织的更新程序,请参见["如何编写GO代码"](https://golang.org/doc/code.html)在GO文档中的文章.以这种方式组织代码,可以为每个包提供唯一的导入路径. 299 | 300 | ## How do I make `dep` resolve dependencies from my `GOPATH`? 301 | 302 | `dep init`提供扫描的选项`GOPATH`通过依赖来做依赖`dep init -gopath`当没有找到包时,它返回到网络模式.`GOPATH`. `dep ensure`不与项目一起工作`GOPATH`. 303 | 304 | ## Will `dep` let me use git submodules to store dependencies in `vendor`? 305 | 306 | 不,只有一个小小的例外:`dep`蜜饯`/vendor/.git`,如果它存在.这是在[蟑螂](https://github.com/cockroachdb/cockroach)的请求,谁依靠它来保持`vendor`从他们的主要储存库膨胀. 307 | 308 | Git子模块不是DEP的一部分的原因最好表示为Pro/CON列表: 309 | 310 | **赞成的意见** 311 | 312 | - Git子模块提供了一种结构良好的嵌套存储库的方法. 313 | 314 | **欺骗** 315 | 316 | - g it子模块执行的嵌套并不比dep已经执行的功能更强大,也更富表现力,但是dep更一般(对于bzr和hg)并且更具体地进行域嵌套(例如,消除嵌套的供应商目录). 317 | - 以任何方式合并git子模块都会在逻辑中产生新的路径来处理子模块情况,这意味着非平凡的复杂性增加. 318 | - DEP目前不知道或关心它运行的项目是否在版本控制之下.依赖子模块将意味着DEP开始关注这一点.它只会有条件地不能使它更好——逻辑上更复杂的路径,更复杂. 319 | - 将子模块以一种对用户可见的方式进行整合(为什么你会这样做?)使DEP的工作流程更加复杂和不可预测:*有时*预期与子模块相关的行动;*有时*子模块派生的工作流是足够的. 320 | - 在另一个库中嵌套一个存储库意味着,可以直接在该子库中进行更改.这与DEP的基本原理是相反的.`vendor`是死代码,直接修改任何东西都有错误. 321 | 322 | ## How does `dep` work without changing my packages imports? 323 | 324 | `dep`不需要进口(或`$GOPATH`要更新,因为[GO从版本1.5开始对供应商目录进行本地支持](https://golang.org/cmd/go/#hdr-Vendor_Directories). 您不需要更新导入路径是相对的.例如,`import github.com/user/awesome-project`将在项目中找到`/vendor/github.com/user/awesome-project`在寻找之前`$GOPATH/src/github.com/user/awesome-project`. 325 | 326 | ## Best Practices 327 | 328 | ### Should I commit my vendor directory? 329 | 330 | 这取决于你: 331 | 332 | **赞成的意见** 333 | 334 | - 这是获得真正可复制的构建的唯一方法,因为它防止上游重命名、删除和提交历史重写. 335 | - 你不需要额外的`dep ensure`同步步`vendor/`具有`Gopkg.lock`在大多数操作之后,例如`go get`克隆、获得最新、合并等. 336 | 337 | **欺骗** 338 | 339 | - 你的回购将更大,潜在的更大,虽然[`prune`](Gopkg.toml.md#prune)可以帮助最小化这个问题. 340 | - PR差异将包括文件下的更改`vendor/`什么时候?`Gopkg.lock`被修改,但是文件在`vendor/`是[默认隐藏](https://github.com/github/linguist/blob/v5.2.0/lib/linguist/generated.rb#L328)在吉瑟布上. 341 | 342 | ## How do I roll releases that `dep` will be able to use? 343 | 344 | 简而言之:确保你已经承诺了自己的承诺.`Gopkg.toml`和`Gopkg.lock`然后在您的版本控制系统中创建一个标签并将其推到标准位置.`dep`被设计为自动地从这种元数据中工作.`git`,`bzr`和`hg`. 345 | 346 | 你非常喜欢使用它.[塞弗](http://semver.org)兼容的标签名.我们希望尽快开发出更精确的描述文档,但与此同时,[npm](https://docs.npmjs.com/misc/semver)文档匹配我们的模式很好. 347 | 348 | ## What semver version should I use? 349 | 350 | 这可能是一个微妙的问题,并且社区将不得不制定一些公认的标准,以便如何将semver应用于Go项目.然而,在最高层,这些规则是: 351 | 352 | - 下面`v1.0.0`什么都行.使用这些版本来确定您希望API是什么. 353 | - 上面`v1.0.0`一般的Go最佳实践仍然适用——不要进行向后不兼容的更改——导出的标识符可以添加到,但不能更改或删除. 354 | - 如果必须进行向后不兼容的更改,则点击主版本. 355 | 356 | 重要的是要注意有一个`v1.0.0`不排除您拥有Alpha/beta / ETC版本.Sever规范允许[预版本](http://semver.org/#spec-item-9)和`dep`小心*不*允许这样的版本,除非`Gopkg.toml`包含显式包含预删除的范围约束:如果存在版本`v1.0.1-alpha4`然后约束`>=1.0.0`不会匹配它,但是`>=1.0.1-alpha1`威尔. 357 | 358 | 已经做了一些工作.[一个工具](https://github.com/bradleyfalzon/apicompat)这将分析和比较你的代码和最后一个版本,并建议你应该使用的下一个版本. 359 | 360 | ## Is it OK to make backwards-incompatible changes now? 361 | 362 | 对.但是. 363 | 364 | `dep`将使GO生态系统能够更优雅地处理落后的不兼容变化.然而,`dep`不是某种神奇的灵丹妙药.版本和依赖性管理是硬的,依赖性地狱是真实的.长期以来避免破坏变化的社区智慧仍然很重要.任何`v1.0.0`发布应该伴随着如何避免将来打破API更改的计划. 365 | 366 | 一个好的策略可能是添加到API中,而不是改变它,在旧进程中删去旧版本.然后,当时间是正确的,你可以滚动一个新的主要版本,并清理出一堆废弃的符号一次. 367 | 368 | 请注意,在突破性变化(即,垫片)上提供增量迁移路径是棘手的,而且是我们的一些事情.[还没有好的答案](https://groups.google.com/forum/#!topic/go-package-management/fp2uBMf6kq4). 369 | 370 | ## My dependers don't use `dep` yet. What should I do? 371 | 372 | 在大多数情况下,你不需要做任何不同的事情. 373 | 374 | 唯一可能的问题是,你的项目是否曾经作为一个图书馆被消耗掉.如果是这样的话,那么你可能会对你的承诺提心吊胆.`vendor/`目录,因为它可以[原因问题](https://groups.google.com/d/msg/golang-nuts/AnMr9NL6dtc/UnyUUKcMCAAJ). 如果你的家属正在使用`dep`这不是一个问题,因为`dep`注意剥离嵌套`vendor`目录. 375 | 376 | ## How do I configure a dependency that doesn't tag its releases? 377 | 378 | 添加约束`Gopkg.toml`指定的`branch: "master"`(或者你需要的分支)`[[constraint]]`对于这种依赖性.`dep ensure`将确定当前对依赖关系的主分支的修订,并将其放置在`Gopkg.lock`为你.参见:[GopkG.ToML和Gopk.God的区别是什么?](#what-is-the-difference-between-gopkgtoml-the-manifest-and-gopkglock-the-lock) 379 | 380 | ## How do I use `dep` with Docker? 381 | 382 | `dep ensure -vendor-only`从有效的文件夹中创建供应商文件夹`Gopkg.toml`和`Gopkg.lock`不检查GO代码.这对于使用缓存层在DOCKER内部构建尤其有用. 383 | 384 | Sample Dockerfile: 385 | 386 | ```Dockerfile 387 | FROM golang:1.9 AS builder 388 | 389 | RUN curl -fsSL -o /usr/local/bin/dep https://github.com/golang/dep/releases/download/vX.X.X/dep-linux-amd64 && chmod +x /usr/local/bin/dep 390 | 391 | RUN mkdir -p /go/src/github.com/*** 392 | WORKDIR /go/src/github.com/*** 393 | 394 | COPY Gopkg.toml Gopkg.lock ./ 395 | # copies the Gopkg.toml and Gopkg.lock to WORKDIR 396 | 397 | RUN dep ensure -vendor-only 398 | # install the dependencies without checking for go code 399 | 400 | ... 401 | ``` 402 | 403 | ## How do I use `dep` in CI? 404 | 405 | 自从`dep`有望改变,直到`v1.0.0`是发布的,建议依赖发布版本.您可以从中找到最新的二进制文件.[发行版](https://github.com/golang/dep/releases)页. 406 | 407 | Travis CI的示例配置: 408 | 409 | ```yml 410 | # ... 411 | 412 | env: 413 | - DEP_VERSION="X.X.X" 414 | 415 | before_install: 416 | # Download the binary to bin folder in $GOPATH 417 | - curl -L -s https://github.com/golang/dep/releases/download/v${DEP_VERSION}/dep-linux-amd64 -o $GOPATH/bin/dep 418 | # Make the binary executable 419 | - chmod +x $GOPATH/bin/dep 420 | 421 | install: 422 | - dep ensure 423 | ``` 424 | 425 | 缓存也可以启用,但有两个注意事项您应该注意: 426 | 427 | > 直到最近,我们已经断断续续的高速缓存损坏,这将是非常恼人的,如果它也打破了特拉维斯建设. 428 | > 429 | > 还根据[http://dcs.特拉维斯Cy.com/用户/缓存/不缓存的事物](https://docs.travis-ci.com/user/caching/#Things-not-to-cache)他们不推荐使用更大的缓存. 430 | > 431 | > [http://DOCS.C.C.com/用户/缓存/μi缓存工作如何%3F](https://docs.travis-ci.com/user/caching/#How-does-the-caching-work%3F) 432 | > 433 | > > 注意,这使得我们的缓存不是网络本地的,它仍然绑定到S3的网络带宽和DNS解析.这会影响您可以在缓存中存储的内容.如果你在缓存中存储大于几百兆字节的档案,那么你不太可能看到一个大的速度提升. 434 | > 435 | > [公元1293年的卡罗来纳](https://github.com/golang/dep/pull/1293#issuecomment-342969292) 436 | 437 | 如果您确信要在特拉维斯上启用缓存,可以通过添加`$GOPATH/pkg/dep`默认位置为`dep`缓存到缓存目录: 438 | 439 | ```yml 440 | # ... 441 | 442 | cache: 443 | directories: 444 | - $GOPATH/pkg/dep 445 | ``` 446 | -------------------------------------------------------------------------------- /docs/ensure-mechanics.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Models and Mechanisms 3 | --- 4 | 5 | While dep has many discrete components and moving parts, all of these parts revolve around a central model. This document explains that model, then explores the dep's primary mechanisms in the context of that model. 6 | 7 | ## States and flows 8 | 9 | Dep is centered around the idea of the "four state system" - a model for classifying and organizing the on-disk state with which a package manager interacts. This was first articulated as a coherent, general model in [this (long) article](https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527), though many of the principles in the four state model were derived from existing package managers. 10 | 11 | Briefly, the four states are: 12 | 13 | 1. The [current project's](glossary.md#current-project) source code. 14 | 2. A [manifest](glossary.md#manifest) - a file describing the current project's dependency requirements. In dep, this is the [`Gopkg.toml`](Gopkg.toml.md) file. 15 | 3. A [lock](glossary.md#lock) - a file containing a transitively-complete, reproducible description of the dependency graph. In dep, this is the [`Gopkg.lock`](Gopkg.lock.md) file. 16 | 4. The source code of the dependences themselves. In dep's current design, this is the `vendor/` directory. 17 | 18 | We can visually represent these four states as follows: 19 | 20 | ![dep's four states](assets/four-states.png) 21 | 22 | ### Functional flow 23 | 24 | It's useful to think of dep as a system that imposes a unidirectional, functional flow on the relationships between these states. These functions treat the above states as inputs and outputs, moving them from left to right. Specifically, there are two functions: 25 | 26 | * A _solving function_, that takes as its input the set of imports in the current project and the rules in `Gopkg.toml`, and returns as its output a transitively-complete, immutable dependency graph - the information in a `Gopkg.lock`. 27 | * A _vendoring function_, that takes the information in a `Gopkg.lock` as its input and ensures an on-disk arrangement of source files such that the compiler will use the versions designated in the lock. 28 | 29 | We can represent these two functions visually: 30 | 31 | ![dep's two main functions](assets/annotated-func-arrows.png) 32 | 33 | This is `dep ensure` - the typical flow, used when a `Gopkg.toml` already exists. When a project does not yet have a `Gopkg.toml`, `dep init` can generate one. The essential flow remains the same, but with changed inputs: instead of reading from an existing `Gopkg.toml` file, `dep init` constructs one out of data inferred from the user's GOPATH, and/or [a metadata file from another tool](). (In other words, `dep init` automatically migrates a project from other approaches to organizing dependencies.) 34 | 35 | This diagram directly corresponds to code as well. The solving function is actually split into a constructor and a method - we first create a [`Solver`](https://godoc.org/github.com/golang/dep/gps#Solver) type, then call its `Solve()` method. The inputs to the constructor are wrapped up in a [`SolveParameters`](https://godoc.org/github.com/golang/dep/gps#SolveParameters), which should look familiar: 36 | 37 | ```go 38 | type SolveParameters struct { 39 | RootPackageTree pkgtree.PackageTree // Parsed project src; contains lists of imports 40 | Manifest gps.RootManifest // Gopkg.toml 41 | ... 42 | } 43 | ``` 44 | 45 | The vendoring function is [`gps.WriteDepTree()`](https://godoc.org/github.com/golang/dep/gps#WriteDepTree). While it takes a handful of arguments, the relevant one is a [`gps.Lock`](https://godoc.org/github.com/golang/dep/gps#Lock) - an interface representing an abstracted form of the data held in a `Gopkg.lock`. 46 | 47 | The four state system, and these functional flows through it, are the foundation on which all of dep's behavior is built. If you want to understand dep's mechanics, keep this model at the forefront of your mind. 48 | 49 | ### Staying in sync 50 | 51 | One of dep's design goals is that both of its "functions" minimize both the work they do, and the change they induce in their respective outputs. Consequently, both functions peek ahead at the pre-existing output to understand what work actually needs to be done: 52 | 53 | * The solving function checks the existing `Gopkg.lock` to determine if all of its inputs are satisfied. If they are, the solving function can be bypassed entirely. If not, the solving function proceeds, but attempts to change as few of the selections in `Gopkg.lock` as possible. 54 | * The vendoring function hashes each discrete project already in `vendor/` to see if the code present on disk is what `Gopkg.lock` indicates it should be. Only projects with hash mismatches are rewritten. 55 | 56 | Specifically, dep defines a number of invariants that must be met: 57 | 58 | | Sync invariant | Resolution when desynced | Func | 59 | | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------- | 60 | | All [`required`](Gopkg.toml.md#required) statements in `Gopkg.toml` must be present in the [`input-imports`](Gopkg.lock.md#input-imports) list in `Gopkg.lock`. | Re-solve, update `Gopkg.lock` and `vendor/` for projects that changed | Solving | 61 | | All `import` statements in the current project's non-[`ignored`]((Gopkg.toml.md#ignored)), non-hidden packages must be present in [`input-imports`](Gopkg.lock.md#input-imports) list in `Gopkg.lock`. | Re-solve, update `Gopkg.lock` and `vendor/` for projects that changed | Solving | 62 | | All [versions in `Gopkg.lock`](Gopkg.lock.md#version-information-revision-version-and-branch) must be acceptable with respect to the `[[constraint]]` or `[[override]]` declarations made in `Gopkg.toml`. | Re-solve, update `Gopkg.lock` and `vendor/` for projects that changed | Solving | 63 | | The [`pruneopts`](Gopkg.lock.md#pruneopts) of each `[[project]]` in `Gopkg.lock` must equal the declaration in `Gopkg.toml`. | Update `Gopkg.lock` and `vendor/` | Vendoring* | 64 | | The [`digest`](Gopkg.lock.md#digest) of each `[[project]]` in `Gopkg.lock` must equal the value derived from hashing the current contents of `vendor/` | Regenerate the projects in `vendor/ `, and update `Gopkg.lock` with the new hash digest if necessary | Vendoring | 65 | 66 | (*`pruneopts` is a little weird, because the desync is between `Gopkg.toml` and `Gopkg.lock`, but it doesn't trigger a solve.) 67 | 68 | If peeking ahead reveals that the sync invariants are already met, then the corresponding function needn't do any work; if they don't, then dep takes the resolution step. Either way, when `dep ensure` finishes, we can be sure that we're in the "known good state" of where all sync invariants are maintained. 69 | 70 | `dep check` will evaluate all of the above relations, and if any invariants do not hold, it will print a description of the desync and exit 1. This behavior can be disabled on a per-project basis using the [`noverify` field in Gopkg.toml](Gopkg.toml.md#noverify). 71 | 72 | ## `dep ensure` flags and behavior variations 73 | 74 | Each of `dep ensure`'s various flags affects the behavior of the solving and vendoring functions - or even whether they run at all. Some flags can also temporarily result in the project being out of sync. Thinking about these effects in the context of dep's basic model is the fastest path to understanding what's going on. 75 | 76 | ### `-no-vendor` and `-vendor-only` 77 | 78 | These two flags are mutually exclusive, and determine which of `dep ensure`'s two functions are actually performed. Passing `-no-vendor` will cause only the solving function to be run, resulting in the creation of a new `Gopkg.lock`; `-vendor-only` will skip solving and run only the vendoring function, causing `vendor/` to be repopulated from the pre-existing `Gopkg.lock`. 79 | 80 | ![Flags to run only one or the other of dep's functions](assets/func-toggles.png) 81 | 82 | Passing `-no-vendor` has the additional effect of causing the solving function to run unconditionally, bypassing the pre-check ordinarily made against `Gopkg.lock` to see if it already satisfies all inputs. 83 | 84 | ### `-add` 85 | 86 | The general purpose of `dep ensure -add` is to facilitate the introduction of new dependencies into the depgraph. Whereas `-update` is restricted to [source roots](glossary.md#source-root), (e.g. `github.com/foo/bar`), `-add` can take any package import path as an argument (e.g. `github.com/foo/bar` OR `github.com/foo/bar/baz`). 87 | 88 | Conceptually, there are two possible things that `-add` might be introducing. Any `dep ensure -add` run will do at least one of these: 89 | 90 | 1. Running the solving function in order to generate a new `Gopkg.lock` with the new dependenc(ies) 91 | 2. Appending a version constraint into `Gopkg.toml` 92 | 93 | This implies two preconditions for `dep ensure -add`, at least one of which must be met: 94 | 95 | 1. The named import path is not currently in the project's import statements, or in `Gopkg.toml`'s `required` list 96 | 2. There is no `[[constraint]]` stanza in `Gopkg.toml` for the project root corresponding to the named import path 97 | 98 | It is also possible to explicitly specify a version constraint: 99 | 100 | ```bash 101 | $ dep ensure -add github.com/foo/bar@v1.0.0 102 | ``` 103 | 104 | When no version constraint is included in the argument, the solving function will select the latest version that works (generally, the newest semver release, or the default branch if there are no semver releases). If solving succeeds, then either the argument-specified version, or if none then the version selected by the solver, will be appended into `Gopkg.toml`. 105 | 106 | The behavioral variations that arise from the assorted differences in input and current project state are best expressed as a matrix: 107 | 108 | | Argument to `dep ensure -add` | Has `[[constraint]]` stanza in `Gopkg.toml` | In imports or `required` | Result | 109 | | ----------------------------- | ------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | 110 | | `github.com/foo/bar` | N | N | Added temporarily to `Gopkg.lock` & `vendor/`; inferred version constraint appended to `Gopkg.toml` | 111 | | `github.com/foo/bar@v1.0.0` | N | N | Added temporarily to `Gopkg.lock` & `vendor/`; specified version constraint appended to `Gopkg.toml` | 112 | | `github.com/foo/bar` | Y | N | Added temporarily to `Gopkg.lock` & `vendor/` | 113 | | `github.com/foo/bar@v1.0.0` | Y | - | **Immediate error**: constraint already present in `Gopkg.toml` | 114 | | `github.com/foo/bar` | N | Y | Infer version constraint from `Gopkg.lock` and add to `Gopkg.toml` | 115 | | `github.com/foo/bar` | Y | Y | **Immediate error:** nothing to do | 116 | 117 | For any of the paths where `dep ensure -add` needs to run the solving function in order to generate an updated `Gopkg.lock`, the relevant information from CLI arguments is applied to the in-memory representation of `Gopkg.toml`: 118 | 119 | ![Model modifications made by -add](assets/required-arrows.png) 120 | 121 | Import path arguments that need to be added are injected via the `required` list, and if an explicit version requirement was specified, the equivalent of a `[[constraint]]` is created. 122 | 123 | Though these rules may ultimately be persisted if solving succeeds, they are ephemeral at least until solving succeeds. And, from the solver's perspective, the ephemeral rules are indistinguishable from rules sourced directly from disk. Thus, to the solver, `dep ensure -add foo@v1.0.0` is identical to modifying `Gopkg.toml` by adding `"foo"` to the `required` list, plus a `[[constraint]]` stanza with `version = "v1.0.0"`, then running `dep ensure`. 124 | 125 | However, because these modifications are ephemeral, a successful `dep ensure -add` may actually push the project out of sync. Constraint modifications generally do not, but if the `required` list is modified, then the project will desync. The user is warned accordingly: 126 | 127 | ```bash 128 | $ dep ensure -add github.com/foo/bar 129 | "github.com/foo/bar" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/. 130 | If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/. 131 | ``` 132 | 133 | ### `-update` 134 | 135 | The behavior of `dep ensure -update` is intimately linked to the behavior of the solver itself. Full detail on that is a topic for the [solver reference material](the-solver.md), but for the purposes of understanding `-update`, we can simplify a bit. 136 | 137 | First, to solidify an implication in the discussion of [functional optimizations](#staying-in-sync), the solving function actually takes into account the pre-existing `Gopkg.lock` when it runs: 138 | 139 | ![Pre-existing lock feeds back into solving function](assets/lock-back.png) 140 | 141 | Injecting `Gopkg.lock` into the solver is a necessity. If we want the solver to preserve previously-selected versions by default, then the solver has to learn about the existing `Gopkg.lock` from somewhere. Otherwise, it wouldn't know what to preserve! 142 | 143 | As such, the lock is another one of the properties encoded onto the [previously-discussed]() `SolveParameters` struct. That, plus two other properties, are the salient ones for `-update`: 144 | 145 | ```go 146 | type SolveParameters struct { 147 | ... 148 | Lock gps.Lock // Gopkg.lock 149 | ToChange []gps.ProjectRoot // args to -update 150 | ChangeAll bool // true if no -update args passed 151 | ... 152 | } 153 | ``` 154 | 155 | Ordinarily, when the solver encounters a project name for which there's an entry in `Gopkg.lock`, it pulls that version out and puts it at the head of the queue of possible versions for that project. When a specific dependency is passed to `dep ensure -update`, however, it is added to the `ToChange` list; when the solver encounters a project listed in `ToChange`, it simply skips pulling the version from the lock. 156 | 157 | "Skips pulling the version from the lock" would imply that `dep ensure -update github.com/foo/bar` is equivalent to removing the `[[project]]` stanza for `github.com/foo/bar` from your `Gopkg.lock`, then running `dep ensure`. And indeed it is - however, that approach is not recommended, and subtle changes may be introduced in the future that complicate the equivalency. 158 | 159 | If `-update` is passed with no arguments, then `ChangeAll` is set to `true`, resulting in the solver ignoring `Gopkg.lock` for all newly-encountered project names. This is equivalent to explicitly passing all of your dependences as arguments to `dep ensure -update`, as well as `rm Gopkg.lock && dep ensure`. Again, however, neither of these approaches are recommended, and future changes may introduce subtle differences. 160 | 161 | When a version hint from `Gopkg.lock` is not placed at the head of the version queue, it means that dep will explore the set of possible versions for a particular dependency. This exploration is performed according to a [fixed sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade), where newer versions are tried first, resulting in an update. 162 | 163 | For example, say there is a project, `github.com/foo/bar`, with the following versions: 164 | 165 | ```bash 166 | v1.2.0, v1.1.1, v1.1.0, v1.0.0, master 167 | ``` 168 | 169 | If we depend on that project with `^1.1.0`, and have `v1.1.0` in our `Gopkg.lock` , then it means there are three versions that match our constraint, and two of them are newer than the one currently selected. (There's also an older version, `v1.0.0`, and a `master` branch, but these aren't allowed by a `^1.1.0` constraint.) An ordinary `dep ensure` run will duplicate and push `v1.1.0` ahead of all the others in the queue: 170 | 171 | ```bash 172 | [v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master] 173 | ``` 174 | 175 | And `v1.1.0` will be selected again, unless some other condition is presented that forces the solver to discard it. When running `dep ensure -update github.com/foo/bar`, however, the locked version is not prepended: 176 | 177 | ```bash 178 | [v1.2.0, v1.1.1, v1.1.0, v1.0.0, master] 179 | ``` 180 | 181 | So, barring some other conflict, `v1.2.0` is selected, resulting in the desired update. 182 | 183 | #### `-update` and constraint types 184 | 185 | Continuing with our example, it's important to note that updates with `-update` are achieved incidentally - the solver never explicitly targets a newer version. It just skips adding a hint from the lock, then selects the first version in the queue that satisfies constraints. Consequently, `-update` is only effective with certain types of constraints. 186 | 187 | It does work with branch constraints, which we can observe by including the underlying revision. If the user has constrained on `branch = "master"`, and `Gopkg.lock` points at a topologically older revision (say, `aabbccd`) than the tip of the canonical source's `master` branch (say, `bbccdde`), then `dep ensure` will end up constructing a queue that looks like this: 188 | 189 | ```bash 190 | [master@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master@bbccdde] 191 | ``` 192 | 193 | With `-update`, the hint at the head will be omitted; `branch = "master"` will cause the solver to reject all of the semantic versions, and finally settle on `master@bbccdde`. 194 | 195 | All versions in the version queue keep track of an underlying revision, which means the same is true if, for example, some upstream project force-pushes a git tag: 196 | 197 | ```bash 198 | [v1.1.0@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0@bbccdde, v1.0.0, master] 199 | ``` 200 | 201 | Thus, even if an upstream tag is force-pushed in one of your project's dependences, dep will retain the original revision until you explicitly allow it to change via a `dep ensure -update`. 202 | 203 | The key takeaway here is that `-update`'s behavior is governed by the type of constraints specified: 204 | 205 | | `Gopkg.toml` version constraint type | Constraint example | `dep ensure -update` behavior | 206 | | ------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | 207 | | `version` (semver range) | `"^1.0.0"` | Tries to get the latest version allowed by the range | 208 | | `branch` | `"master"` | Tries to move to the current tip of the named branch | 209 | | `version` (non-range semver) | `"=1.0.0"` | Change can only occur if the upstream release was moved (e.g. `git push --force `) | 210 | | `version` (non-semver) | `"foo"` | Change can only occur if the upstream release was moved | 211 | | `revision` | `aabbccd...` | No change is possible | 212 | | (none) | (none) | The first version that works, according to [the sort order](https://godoc.org/github.com/golang/dep/gps#SortForUpgrade) | 213 | -------------------------------------------------------------------------------- /docs/failure-modes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Failure Modes 3 | --- 4 | 5 | Like all complex, network-oriented software, dep has known failure modes. These generally fall into two categories: I/O and logical. I/O errors arise from unexpected responses to system calls that interact with the network or local disk. Logical failures occur when dep encounters issues within the package management problem domain. 6 | 7 | ## I/O errors 8 | 9 | dep reads from the network, and reads and writes to disk, and is thus subject to all the typical errors that are possible with such activities. 10 | 11 | full disks, failed disks, lack of permissions, network partitions, firewalls, etc. However, there are three classes of I/O errors that are worth addressing specifically: 12 | 13 | - Network failures 14 | - Bad local cache state 15 | - `vendor` write errors 16 | 17 | In general, these problems aren't things we can reasonably program around in dep. Therefore, they can't be considered bugs for us to fix. Fortunately, most of these problems have straightforward remediations. 18 | 19 | ### Network failures 20 | 21 | > **Remediation tl;dr:** most network issues are ephemeral, even if they may last for a few minutes, and can be addressed simply by re-running the same command. Always try this before attempting more invasive solutions. 22 | 23 | dep talks to the network at several different points. These vary somewhat depending on source (VCS) type and local disk state, but this list of operations is generally instructive: 24 | 25 | - When dep cannot [statically deduce](deduction.md#static-deduction) the source root of an import path, it issues a `go-get` HTTP metadata request to a URL constructed from the import path. 26 | - Retrieving the list of available versions for a source (think `git ls-remote`) necessarily requires network activity. 27 | - Initially downloading (in git terms, `git clone`) an upstream source into the local cache also necessarily requires network activity. 28 | - Updating a local cache (in git terms, `git fetch`) with the latest changes from an upstream source. 29 | - Writing out code trees under `vendor` is typically done from the local cache, but under some circumstances a tarball may be fetched on-the-fly from a remote source. 30 | 31 | Network failures that you actually may observe are biased towards the earlier items in the list, simply because those operations tend to happen first: you generally don't see update failures as much as version-listing failures, because they usually have the same underlying cause (source host is down, network partition, etc.), but the version-list request happens first on most paths. 32 | 33 | #### Persistent network failures 34 | 35 | Although most network failures are ephemeral, there are three well-defined cases where they're more permanent: 36 | 37 | - **The network on which the source resides is permanently unreachable from the user's location:** in practice, this generally means one of two things: you've forgotten to log into your company VPN, or you're behind [the GFW](https://en.wikipedia.org/wiki/Great_Firewall). In the latter case, setting the _de facto_ standard HTTP proxy environment variables that [`http.ProxyFromEnvironment()`](https://golang.org/pkg/net/http/#ProxyFromEnvironment) respects will cause dep's `go-get` HTTP metadata requests, as well as git, bzr, and hg subcommands, to utilize the proxy. 38 | 39 | - Remediation is also exactly the same when the custom `go-get` HTTP metadata service for a source is similarly unreachable. The failure messages, however, will look like [deduction failures](#deduction-failures). 40 | 41 | - **The source has been permanently deleted or moved:** these are [left-pad](https://www.theregister.co.uk/2016/03/23/npm_left_pad_chaos/) events, though note that [GitHub automatically redirects traffic after renames](https://help.github.com/articles/renaming-a-repository/), mitigating the rename problem. But, if an upstream source is removed, dep will be unable to proceed until a new upstream source is established for the import path. To that end: 42 | 43 | - If you still have a copy of the source repository in your local cache or GOPATH, consider uploading it to a new location (e.g. forking it) and using a [`source`](Gopkg.toml.md#source) rule to point to the fork. 44 | - If you don't have a whole repository locally, then extracting the code currently in your `vendor` directory into a new repository and pushing it to a . (Note: this may have licensing implications.) 45 | - If you have no instances of the code locally, then there's little that can be done - that code is simply gone, and you'll need to refactor your project. 46 | 47 | Future versions of dep will be able to better handle an interim period before a new upstream/forked source is created, or simply living in a world where a given code tree exists solely in your project's `vendor` directory. 48 | 49 | - **The user lacks the necessary credentials to interact with a source:** see the [FAQ on configuring credentials](FAQ.md#how-do-i-get-dep-to-authenticate-to-a-git-repo). 50 | 51 | The exact error text will vary depending on which of the operations is running, what type of source dep is trying to communicate with, and what actual network problem has occurred. The error text may not always make it immediately clear which combination of these you're dealing with, but for persistent problems, it should at least reduce the search space. 52 | 53 | #### Hangs 54 | 55 | > **Remediation tl;dr:** hangs are almost always network congestion, or sheer amount of network data to fetch. Wait, or cancel and try again with `-v` to try to get more context. 56 | 57 | Almost any case where a dep command, run with `-v`, hangs for more than ten minutes will ultimately be a bug. However, the most common explanation for an apparent dep hangs is actually normal behavior: because dep's operation requires that it keep its own copies of upstream sources hidden away in the [local cache](glossary.md#local-cache), the first run of dep against a project, especially large projects, can take a long time while it populates the cache. 58 | 59 | The only known case where dep may hang indefinitely is if one of the underlying VCS binaries it calls is prompting for some kind of input. Typically this means credentials (though not always - make sure to accept remote hosts' SSH keys into your known hosts!), and dep's normal assumption is that necessary credentials have been provided via environmental mechanisms - [configuration files or daemons](FAQ.md#how-do-i-get-dep-to-authenticate-to-a-git-repo), SSH agents, etc. This assumption is necessary for dep's concurrent network activity to work. If your use case absolutely cannot support the use of any such environmental caching mechanism, [please weigh in on this issue](https://github.com/golang/dep/issues/1476). 60 | 61 | Unfortunately, until dep [improves the observability of its ongoing I/O operations](), it cannot accurately report to the user which operations are actually underway at any given moment. This can make it difficult to differentiate from other hangs - credentials prompts, long network timeouts induced by firewalls, sluggish TCP when faced with packet loss, etc. 62 | 63 | ### Bad local cache state 64 | 65 | > **Remediation tl;dr:** Remove the local cache dir: `rm -rf $GOPATH/pkg/dep/sources`. 66 | 67 | It is possible for parts of the [local cache](glossary.md#local-cache) maintained by dep to get into a bad state. This primarily happens when dep processes are forcibly terminated (e.g. Ctrl-C). This can, for example, terminate a `git` command partway through, leaving bad state on disk. By dep's definition, a [dirty git working copy]() is bad state. 68 | 69 | The error messages arising from bad local cache state often do not include full paths, so it may not be immediately obvious that problems are originating in the local cache. If full paths aren't included, then the best hint tends to be that the errors look like local VCS errors, but they're not on files from your own project. 70 | 71 | However, for the most part, **dep automatically discovers and recovers from bad local cache state problems**, rebounding back into a good state as it bootstraps each command execution. If you do encounter what appears to be a local cache problem from which dep does not automatically recover, then the fix is typically to just throw out the cache, `rm -rf $GOPATH/pkg/dep/sources`; dep will repopulate it automatically on the next run. However, if you have time, please preserve the local cache dir and report it as a bug! 72 | 73 | There are no known cases where, in the course of normal operations, dep can irreparably corrupt its own local cache. Any such case would be considered a critical bug in dep, and you should report it! If you think you've encountered such a case, it should have the following characteristics: 74 | 75 | - The error message you're seeing is consistent with some sort of disk state error in a downloaded source within `$GOPATH/pkg/dep/sources` 76 | - You can identify a bad state (generally: a vcs "status"-type command will either fail outright, or report a modified working tree) in a subdirectory of `$GOPATH/pkg/dep/sources` suggested by the above error 77 | - The exact same error recurs after removing the local cache dir and running the same command, **without** prematurely terminating the project (e.g. via Ctrl-C) 78 | 79 | ### `vendor` write errors 80 | 81 | Dep may encounter errors while attempting to write out the `vendor` directory itself (any such errors will result in a full rollback; causing no changes to be made to disk). To help pinpoint where the problem may be, know that this is the flow for populating `vendor`: 82 | 83 | 1. Allocate a new temporary directory within the system temporary directory. 84 | 2. Rename the existing `vendor` directory to `vendor.orig`. Do this within the current project's root directory if possible; if not, rename and move it to the tempdir. 85 | 3. Create a new `vendor` directory within the tempdir and concurrently populate it with all the projects named in `Gopkg.lock`. 86 | 4. Move the new `vendor` directory into place in the current project's root directory. 87 | 5. Delete the old `vendor` directory. 88 | 89 | Note: this flow will become more targeted after [vendor verification]() allows dep to identify and target the subset of projects currently in `vendor` that need to be changed. 90 | 91 | Known problems in this category include: 92 | 93 | - Insufficient space in the temporary directory will cause an error, triggering a rollback. However, because the rollback process cleans up files written so-far, the temporary partition won't actually be full after dep exits, which can be misleading. 94 | - Attempting to [re]move the original `vendor` directory can fail with permissions errors if any of the files therein are "open", in some editors/on some OSes (particularly Windows). [There's an issue for this](). 95 | 96 | ## Logical failures 97 | 98 | Logical failures encompass everything that can happen within dep's logical problem-solving domain - after 99 | 100 | Some of these failures can be as straightforward as typos, and are just as easily resolved. Others, unfortunately, may necessitate forking and modifying an upstream project - although such cases are very rare. 101 | 102 | ### Deduction failures 103 | 104 | Import path deduction, as detailed in the [deduction reference](deduction.md), has both static and dynamic phases. When neither of these phases is able to determine the source root for a given import path, it is considered to be a deduction failure. Deduction failures all contain this key error text: 105 | 106 | ```bash 107 | ...unable to deduce repository and source type for ""... 108 | ``` 109 | 110 | _Note: there are [more varied error messages for the small subset of cases](#malformed-import-paths) where an import path appears to be deducible, but is somehow malformed._ 111 | 112 | When a deduction failure occurs on a given import path, the proximal cause will have been one of following five scenarios (arranged from most to least likely): 113 | 114 | - The import path was never deducible. 115 | - **Dynamic deduction failures:** 116 | - The import path was, at one time, dynamically deducible, and the metadata service for it is up, but it is unreachable by dep. 117 | - The import path was, at one time, dynamically deducible, but the metadata service for it is down. 118 | - **Static rule changes:** 119 | - The import path cannot be statically deduced by the running version of dep, but a newer version of dep has added rules that can statically deduce it. 120 | - The import path was once statically deducible, but the running version of dep has discontinued support for it. 121 | 122 | In all of these cases, your last recourse will be to add a [`source`](Gopkg.toml.md#source) directive to fix the problem. However, these directives are brittle, and should only be used when other options have been exhausted; also, until [this problem is solved](https://github.com/golang/dep/issues/860), even `source` may not be able to help. 123 | 124 | #### Undeducible paths 125 | 126 | > **Remediation tl;dr:** You made a typo; fix it. If not, you may need a `source`, but be sparing with those. 127 | 128 | The most likely cause of deduction failure is minor user error. Specifically, the user is the _current_ user (you), and the error is there is a mistyped import path somewhere in the current (your) project. The problem may be in your `Gopkg.toml`, or one of your imports, but the error message should point you directly at the problem, and the solution is usually obvious - e.g., "gihtub". 129 | 130 | Validation of the inputs from the current project are made fast and up front in dep, so these errors will tend to present themselves immediately. Between this fast validation, and the fact that projects are typically uncompilable, or at least not `go get`-able, with these kinds of errors, they tend to be caught early. This is why truly undeducible paths pop up primarily as temporary accidents while hacking on your own projects - you have to fix them to move on. 131 | 132 | That undeducibility is an immediate and hard blocker, however, has led to this being a sticking point for migration to dep. In particular, there are two issues: 133 | 134 | - Several other Go dependency management tools do allow specifying arbitrary VCS/source URLs, and [but support for that via `source` in dep is still pending](https://github.com/golang/dep/issues/860). 135 | - GitHub Enterprise only implements `go-get` HTTP metadata correctly for the root package of a repository. In practice, this makes all import paths pointing to GHE undeducible, and `source` can't help either without the aforementioned improvement. 136 | 137 | If the problem import path is in your current project, but the problem isn't an obvious typo, then you're likely experiencing a dynamic failure, or may need to check the [deduction reference](deduction.md) to understand what what a deducible import path looks like. 138 | 139 | #### Dynamic deduction failures 140 | 141 | Most dynamic deduction failures are either ephemeral network or service availability issues, and will go away by re-running the previous command. Always try that first. 142 | 143 | If the issue persists, and you're certain the import path should be deducible, network issues are the first culprit to check. The typical causes (VPN, firewalls) and remediation for when a metadata service is unreachable are the same as [when a source itself is unreachable](#persistent-network-failures). 144 | 145 | The next possibility is a metadata service that's permanently gone away. Whereas network errors are still reasonably common, it is rare to encounter an import path pointing to a defunct public metadata service. Consider: that one import path can render the entire project unfetchable and/or uncompilable, and neither of those are states that popular projects can afford to be in for long. So, being that most (public Go ecosystem) dependencies are on the more popular projects, as long as you're also depending on the more popular projects, you're unlikely to encounter this. 146 | 147 | Of course, defunct _private_ metadata services may be much more common, as they are subject to entirely different incentives. 148 | 149 | If you think you've encountered a defunct metadata service, try probing the domain portion of the import path directly to see if there is an HTTP(S) server there at all. If not, you can only force with `source` - assuming you know what source URL you should use. If not, you may need to refactor your code (if the problem is in your project), pick a different version of the problem dependency, or drop the problem dependency entirely; sometimes, you just have to get rid of dead code. 150 | 151 | #### Static rule changes 152 | 153 | > **Remediation tl;dr:** make sure you have the latest released version of dep. 154 | 155 | Static rule changes are very unlikely to be the cause of your deduction failures. 156 | 157 | It is plausible that dep will add new static deduction rules in the future. And it is possible that, if you have an older version of dep, and you collaborate with or pull in code from someone using a newer version of dep, then their code may take advantage of new import path patterns that your dep doesn't know about yet. But very, very few static rules additions are likely to ever be made to dep over its lifetime - and getting access to them is just a question of updating once. 158 | 159 | The final scenario - dep discontinuing support for a static deduction pattern - is included for clarity and completeness, but simply should never happen. Even if a hosting service covered by static rules today were to shut down, dep would retain the existing static rules; if hosted code had been migrated elsewhere, then dep would attempt to perform a remapping automatically. If no such remapping were possible, then dep would still recognize the basic host pattern, but may fall back on using malformed import path errors - the next topic - to informatively reject new imports from the host. 160 | 161 | #### Malformed import paths 162 | 163 | For the most part, static ("is it one of the handful of hosts we know?") and dynamic ("just do whatever the metadata service tells us to do") deduction are single-pass checks. However, both cases can perform some minor additional validation: 164 | 165 | - In static deduction, the rules are necessarily specific to each host, but most enforce allowable characters and schemes in URLs that are known to be required by the underlying host. 166 | - In dynamic deduction, responses from the metadata service are minimally validated to ensure that the source type and scheme are all supported, and that the URL contains valid characters. 167 | 168 | ### Solving failures 169 | 170 | When `dep ensure` or `dep init` exit with an error message looking something like this: 171 | 172 | ```bash 173 | $ dep init 174 | init failed: unable to solve the dependency graph: Solving failure: No versions of github.com/foo/bar met constraints: 175 | v1.0.1: Could not introduce github.com/foo/bar@v1.13.1, as its subpackage github.com/foo/bar/foo is missing. (Package is required by (root).) 176 | v1.0.0: Could not introduce github.com/foo/bar@v1.13.0, as... 177 | v0.1.0: (another error) 178 | master: (another error) 179 | ``` 180 | 181 | _Note: all three of the other hard failure types can sometimes be reported as the errors for individual versions in a list like this. This primarily happens because dep is in need of a [thorough refactor of its error handling](https://github.com/golang/dep/issues/288)._ 182 | 183 | It means that the solver was unable to find a combination of versions for all dependencies that satisfy all the rules enforced by the solver. It is crucial to note that, just because dep provides a big list of reasons why each version failed _doesn't mean_ you have to address each one! That's just dep telling you why it ultimately couldn't use each of those versions in a solution. 184 | 185 | These rules, and specific remediations for failing to meet them, are described in detail in the section on [solver invariants](the-solver.md#solving-invariants). This section is about the steps to take when solving failures occur in general. But, to set context, here's a summary: 186 | 187 | - **`[[constraint]]` conflicts:** when projects in the dependency graph disagree on what [versions](Gopkg.toml.md#version-rules) are acceptable for a project, or where to [source](Gopkg.toml.md#source) it from. 188 | - Remediation will usually be either changing a `[[constraint]]` or adding an `[[override]]`, but genuine conflicts may require forking and hacking code. 189 | - **Package validity failure:** when an imported package is quite obviously not capable of being built. 190 | - There usually isn't much remediation here beyond "stop importing that," as it indicates something broken at a particular version. 191 | - **Import comment failure:** when the import path used to address a package differs from the [import comment](https://golang.org/cmd/go/#hdr-Import_path_checking) the package uses to specify how it should be imported. 192 | - Remediation is to use the specified import path, instead of whichever one you used. 193 | - **Case-only import variation failure:** when two equal-except-for-case imports exist in the same build. 194 | - Remediation is to pick one case variation to use throughout your project, then manually update all projects in your depgraph to use the new casing. 195 | 196 | Let's break down the process of addressing a solving failure into a series of steps: 197 | 198 | 1. First, look through the failed versions list for a version of the dependency that works for you (or a failure that seems fixable), then try to work that one out. Often enough, you'll see a single failure repeated across the entire version list, which makes it pretty clear what problem you need to solve. 199 | 2. Take the remediation steps specific to that failure. 200 | 3. Re-run the same command you ran that produced the failure. There are three possible outcomes: 201 | 1. Success! 202 | 2. Your fix was ineffective - the same failure re-occurs. Either re-examine your fix (step 2), or look for a new failure to fix (step 1). 203 | 3. Your fix was effective, but some new failure arose. Return to step 1 with the new failure list. 204 | --------------------------------------------------------------------------------