diff --git a/README.md b/README.md index a546b60c..b6ed6996 100644 --- a/README.md +++ b/README.md @@ -49,9 +49,13 @@ $ dep ensure -update `dep init` will do the following: 1. Look for [existing dependency management files](docs/FAQ.md#what-external-tools-are-supported) to convert -1. Back up your existing `vendor/` directory to +1. Check if your dependencies use dep +1. Identify your dependencies +1. Back up your existing `vendor/` directory (if you have one) to `_vendor-TIMESTAMP/` +1. Pick the highest compatible version for each dependency 1. Generate [`Gopkg.toml`](Gopkg.toml.md) ("manifest") and `Gopkg.lock` files +1. Install the dependencies in `vendor/` ### Day-to-day workflows @@ -66,6 +70,8 @@ $ dep help ensure #### Installing dependencies +(if your `vendor/` directory isn't [checked in with your code](](docs/FAQ.md#should-i-commit-my-vendor-directory))) + ```sh $ dep ensure ``` @@ -85,12 +91,12 @@ matches the constraints from the manifest. If the dependency is missing from #### Changing dependencies -When you want to do the following for one or more dependencies: +If you want to: * Change the allowed `version`/`branch`/`revision` * Switch to using a fork -do the following: +for one or more dependencies, do the following: 1. Modify your `Gopkg.toml`. 1. Run @@ -99,6 +105,16 @@ do the following: $ dep ensure ``` +#### Checking the status of dependencies + +```sh +$ dep status +PROJECT CONSTRAINT VERSION REVISION LATEST +github.com/Masterminds/semver branch 2.x branch 2.x 139cc09 c2e7f6c +github.com/Masterminds/vcs ^1.11.0 v1.11.1 3084677 3084677 +github.com/armon/go-radix * branch master 4239b77 4239b77 +``` + #### Updating dependencies (to the latest version allowed by the manifest) @@ -107,6 +123,43 @@ do the following: $ dep ensure -update ``` +#### Removing dependencies + +1. Remove the `import`s and all usage from your code. +1. Run + + ```sh + $ dep ensure + ``` + +1. Remove from `Gopkg.toml`, if it was in there. + +#### Testing changes to a dependency + +Making changes in your `vendor/` directory directly is not recommended, as dep +will overwrite any changes. Instead: + +1. Delete the dependency from the `vendor/` directory. + + ```sh + rm -rf vendor/ + ``` + +1. Add that dependency to your `GOPATH`, if it isn't already. + + ```sh + $ go get + ``` + +1. Modify the dependency in `$GOPATH/src/`. +1. Test, build, etc. + +Don't run `dep ensure` until you're done. `dep ensure` will reinstall the +dependency into `vendor/` based on your manifest, as if you were installing from +scratch. + +To test out code that is pushed, see [changing dependencies](#changing-dependencies). + ## Feedback Feedback is greatly appreciated. diff --git a/docs/FAQ.md b/docs/FAQ.md index 5ac55a6b..e586ac02 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -28,7 +28,6 @@ Summarize the question and quote the reply, linking back to the original comment ## Best Practices * [Should I commit my vendor directory?](#should-i-commit-my-vendor-directory) -* [How can I test changes to a dependency?](#how-can-i-test-changes-to-a-dependency) * [How do I roll releases that `dep` will be able to use?](#how-do-i-roll-releases-that-dep-will-be-able-to-use) * [What semver version should I use?](#what-semver-version-should-i-use) * [Is it OK to make backwards-incompatible changes now?](#is-it-ok-to-make-backwards-incompatible-changes-now) @@ -305,14 +304,6 @@ It's up to you: - your repo will be bigger, potentially a lot bigger - PR diffs are more annoying -## How can I test changes to a dependency? - -> I would recommend against ever working in your vendor directory since dep will overwrite any changes. It’s too easy to lose work that way. --[@carolynvs in #706](https://github.com/golang/dep/issues/706#issuecomment-305807261) - -If you have a fork, add a `[[constraint]]` entry for the project in `Gopkg.toml` and set `source` to the fork source. This will ensure that `dep` will fetch the project from the fork instead of the original source. -Otherwise, if you want to test changes locally, you can delete the package from `vendor/` and make changes directly in `GOPATH/src/*package*` so that your changes are picked up by the go tool chain. - ## How do I roll releases that `dep` will be able to use? In short: make sure you've committed your `Gopkg.toml` and `Gopkg.lock`, then