From ad4100140c41b906d187134551beb8fb2253a83d Mon Sep 17 00:00:00 2001
From: sam boyer <tech@samboyer.org>
Date: Wed, 26 Apr 2017 00:47:31 -0400
Subject: [PATCH 1/5] Expand example Gopkg.toml text; always add on init

---
 .../ensure/empty/case1/final/Gopkg.toml       | 41 ++++++++++++-
 .../ensure/empty/case2/final/Gopkg.toml       | 44 ++++++++++++++
 .../ensure/empty/case3/final/Gopkg.toml       | 44 ++++++++++++++
 .../ensure/override/case1/final/Gopkg.toml    | 44 ++++++++++++++
 .../harness_tests/init/case1/final/Gopkg.toml | 44 ++++++++++++++
 .../harness_tests/init/case2/final/Gopkg.toml | 44 ++++++++++++++
 .../harness_tests/init/case3/final/Gopkg.toml | 44 ++++++++++++++
 .../init/skip-hidden/final/Gopkg.toml         | 41 ++++++++++++-
 .../remove/force/case1/final/Gopkg.toml       | 44 ++++++++++++++
 .../remove/specific/case1/final/Gopkg.toml    | 44 ++++++++++++++
 .../remove/specific/case2/final/Gopkg.toml    | 44 ++++++++++++++
 .../remove/unused/case1/final/Gopkg.toml      | 44 ++++++++++++++
 .../status/case1/final/Gopkg.toml             | 44 ++++++++++++++
 testdata/txn_writer/expected_manifest.toml    | 44 ++++++++++++++
 txn_writer.go                                 | 59 +++++++++++++++----
 15 files changed, 653 insertions(+), 16 deletions(-)

diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
index 77028df6ae..b6da94ea8f 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
@@ -1,9 +1,44 @@
 
-# Example:
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
 # [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
 # source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
 # branch = "master"
-# name = "github.com/vendor/package"
-# Note: revision will depend on your repository type, i.e git, svc, bzr etc...
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
index 6deaa21764..ebd2ce2684 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
@@ -2,3 +2,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptest"
   version = "^0.8.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
index dd0150055a..9eca018e68 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
@@ -3,3 +3,47 @@ ignored = ["github.com/sdboyer/deptestdos"]
 [[dependencies]]
   branch = "master"
   name = "github.com/sdboyer/deptest"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
index 7f784a4c56..6af7446ae0 100644
--- a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
@@ -2,3 +2,47 @@
 [[overrides]]
   name = "github.com/sdboyer/deptest"
   version = "1.0.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
index 05db85d196..bf55a9e26d 100644
--- a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
@@ -6,3 +6,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
index a5284b92c0..5d13a6095f 100644
--- a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
@@ -2,3 +2,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
index 74acf5e6a6..0e8664c8fa 100644
--- a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
@@ -6,3 +6,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
index 77028df6ae..b6da94ea8f 100644
--- a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
@@ -1,9 +1,44 @@
 
-# Example:
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
 # [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
 # source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
 # branch = "master"
-# name = "github.com/vendor/package"
-# Note: revision will depend on your repository type, i.e git, svc, bzr etc...
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
index a5284b92c0..5d13a6095f 100644
--- a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
@@ -2,3 +2,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
index 05db85d196..bf55a9e26d 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
@@ -6,3 +6,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
index 05db85d196..bf55a9e26d 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
@@ -6,3 +6,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
index 05db85d196..bf55a9e26d 100644
--- a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
@@ -6,3 +6,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
index a5284b92c0..5d13a6095f 100644
--- a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
@@ -2,3 +2,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/testdata/txn_writer/expected_manifest.toml b/testdata/txn_writer/expected_manifest.toml
index d1057a0f57..2c31ad5289 100644
--- a/testdata/txn_writer/expected_manifest.toml
+++ b/testdata/txn_writer/expected_manifest.toml
@@ -2,3 +2,47 @@
 [[dependencies]]
   name = "github.com/sdboyer/dep-test"
   version = "1.0.0"
+
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
+# [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
diff --git a/txn_writer.go b/txn_writer.go
index 297d0b9517..4ad3e08e84 100644
--- a/txn_writer.go
+++ b/txn_writer.go
@@ -21,15 +21,50 @@ import (
 // Example string to be written to the manifest file
 // if no dependencies are found in the project
 // during `dep init`
-const exampleToml = `
-# Example:
+const exampleTOML = `
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
 # [[dependencies]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
 # source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
 # branch = "master"
-# name = "github.com/vendor/package"
-# Note: revision will depend on your repository type, i.e git, svc, bzr etc...
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. However, only the current
+## project's overrides will apply.
+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained
+# name = "github.com/user/project"
+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
+# branch = "master"
+## Note: revision will depend on your repository type; git and hg have SHA1s,
+## bzr a 3-part id, svn a revision number.
+# revision = "abc123"
+
+## "required" lists a set of packages (not projects) that must be included in
+## Gopkg.lock. This has the same effect as directly importing a package, but
+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
 `
 
 // SafeWriter transactionalizes writes of manifest, lock, and vendor dir, both
@@ -271,12 +306,16 @@ func (sw *SafeWriter) Write(root string, sm gps.SourceManager) error {
 	defer os.RemoveAll(td)
 
 	if sw.Payload.HasManifest() {
-		if sw.Payload.Manifest.IsEmpty() {
-			err := modifyWithString(filepath.Join(td, ManifestName), exampleToml)
-			if err != nil {
-				return errors.Wrap(err, "failed to generate example text")
-			}
-		} else if err := writeFile(filepath.Join(td, ManifestName), sw.Payload.Manifest); err != nil {
+		// Always write the example text to the bottom of the TOML file.
+		examples := []byte(exampleTOML)
+		tb, err := sw.Payload.Manifest.MarshalTOML()
+		if err != nil {
+			return errors.Wrap(err, "failed to marshal manifest to TOML")
+		}
+
+		// 0666 is before umask; mirrors behavior of os.Create (used by
+		// writeFile())
+		if err = ioutil.WriteFile(filepath.Join(td, ManifestName), append(tb, examples...), 0666); err != nil {
 			return errors.Wrap(err, "failed to write manifest file to temp dir")
 		}
 	}

From f4079c9050a1f0dbf13709ac58a11b8964512995 Mon Sep 17 00:00:00 2001
From: sam boyer <tech@samboyer.org>
Date: Thu, 27 Apr 2017 21:31:58 -0400
Subject: [PATCH 2/5] Trim out/tighten up examples text

---
 .../ensure/empty/case1/final/Gopkg.toml       | 26 +++++++------------
 .../ensure/empty/case2/final/Gopkg.toml       | 26 +++++++------------
 .../ensure/empty/case3/final/Gopkg.toml       | 26 +++++++------------
 .../ensure/override/case1/final/Gopkg.toml    | 26 +++++++------------
 .../harness_tests/init/case1/final/Gopkg.toml | 26 +++++++------------
 .../harness_tests/init/case2/final/Gopkg.toml | 26 +++++++------------
 .../harness_tests/init/case3/final/Gopkg.toml | 26 +++++++------------
 .../init/skip-hidden/final/Gopkg.toml         | 26 +++++++------------
 .../remove/force/case1/final/Gopkg.toml       | 26 +++++++------------
 .../remove/specific/case1/final/Gopkg.toml    | 26 +++++++------------
 .../remove/specific/case2/final/Gopkg.toml    | 26 +++++++------------
 .../remove/unused/case1/final/Gopkg.toml      | 26 +++++++------------
 .../status/case1/final/Gopkg.toml             | 26 +++++++------------
 testdata/txn_writer/expected_manifest.toml    | 26 +++++++------------
 txn_writer.go                                 | 26 +++++++------------
 15 files changed, 135 insertions(+), 255 deletions(-)

diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
index b6da94ea8f..88726bdefa 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
@@ -1,4 +1,7 @@
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -15,27 +18,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
index ebd2ce2684..aaf4b360a6 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/deptest"
   version = "^0.8.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
index 9eca018e68..98c427ddd4 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
@@ -4,6 +4,9 @@ ignored = ["github.com/sdboyer/deptestdos"]
   branch = "master"
   name = "github.com/sdboyer/deptest"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -20,27 +23,16 @@ ignored = ["github.com/sdboyer/deptestdos"]
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
index 6af7446ae0..9f8ab4c7da 100644
--- a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/deptest"
   version = "1.0.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
index bf55a9e26d..2c6d74172a 100644
--- a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
@@ -7,6 +7,9 @@
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -23,27 +26,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
index 5d13a6095f..3603716a6a 100644
--- a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
index 0e8664c8fa..ff5104bf39 100644
--- a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
@@ -7,6 +7,9 @@
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -23,27 +26,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
index b6da94ea8f..88726bdefa 100644
--- a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
@@ -1,4 +1,7 @@
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -15,27 +18,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
index 5d13a6095f..3603716a6a 100644
--- a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
index bf55a9e26d..2c6d74172a 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
@@ -7,6 +7,9 @@
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -23,27 +26,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
index bf55a9e26d..2c6d74172a 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
@@ -7,6 +7,9 @@
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -23,27 +26,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
index bf55a9e26d..2c6d74172a 100644
--- a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
@@ -7,6 +7,9 @@
   name = "github.com/sdboyer/deptestdos"
   revision = "a0196baa11ea047dd65037287451d36b861b00ea"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -23,27 +26,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
index 5d13a6095f..3603716a6a 100644
--- a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/deptest"
   version = ">=0.8.0, <1.0.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/testdata/txn_writer/expected_manifest.toml b/testdata/txn_writer/expected_manifest.toml
index 2c31ad5289..c96351e0c9 100644
--- a/testdata/txn_writer/expected_manifest.toml
+++ b/testdata/txn_writer/expected_manifest.toml
@@ -3,6 +3,9 @@
   name = "github.com/sdboyer/dep-test"
   version = "1.0.0"
 
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -19,27 +22,16 @@
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when
diff --git a/txn_writer.go b/txn_writer.go
index 4ad3e08e84..f08d706a81 100644
--- a/txn_writer.go
+++ b/txn_writer.go
@@ -22,6 +22,9 @@ import (
 // if no dependencies are found in the project
 // during `dep init`
 const exampleTOML = `
+
+## EXAMPLES & DOCS - safe to delete!
+
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -38,27 +41,16 @@ const exampleTOML = `
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 
-## Overrides have the same structure as [[dependencies]], but supercede all
-## [[dependencies]] declarations from all projects. However, only the current
-## project's overrides will apply.
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
+## all [[dependencies]] declarations from all projects. Only the current project's
+## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-# [[overrides]]
-## Required: the root import path of the project being constrained
-# name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
-## Optional, but recommended: the version constraint to enforce for the project.
-## Only one of "branch", "version" or "revision" can be specified.
-# version = "1.0.0"
-# branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
-# revision = "abc123"
 
 ## "required" lists a set of packages (not projects) that must be included in
-## Gopkg.lock. This has the same effect as directly importing a package, but
-## can be used to require "main" packages.
+## Gopkg.lock. This list is merged with the set of packages imported by the current
+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
 
 ## "ignored" lists a set of packages (not projects) that are ignored when

From c070fbe76d96d72bc68f3d0d44e6aa5be34af31e Mon Sep 17 00:00:00 2001
From: sam boyer <tech@samboyer.org>
Date: Thu, 27 Apr 2017 22:04:39 -0400
Subject: [PATCH 3/5] Put the examples at the top instead

Injecting the comments at the bottom is suboptimal, as it means that
additional dependencies injected by later `dep ensure` calls (under
the new spec) will be separated from the original `init` set.

This seems slightly annoying now, but once we add a flag to allow
bypassing example injection, it'll be less of a problem.
---
 .../ensure/empty/case1/final/Gopkg.toml       | 11 ++++----
 .../ensure/empty/case2/final/Gopkg.toml       | 19 ++++++-------
 .../ensure/empty/case3/final/Gopkg.toml       | 21 ++++++++-------
 .../ensure/override/case1/final/Gopkg.toml    | 19 ++++++-------
 .../harness_tests/init/case1/final/Gopkg.toml | 27 ++++++++++---------
 .../harness_tests/init/case2/final/Gopkg.toml | 19 ++++++-------
 .../harness_tests/init/case3/final/Gopkg.toml | 27 ++++++++++---------
 .../init/skip-hidden/final/Gopkg.toml         | 11 ++++----
 .../remove/force/case1/final/Gopkg.toml       | 19 ++++++-------
 .../remove/specific/case1/final/Gopkg.toml    | 27 ++++++++++---------
 .../remove/specific/case2/final/Gopkg.toml    | 27 ++++++++++---------
 .../remove/unused/case1/final/Gopkg.toml      | 27 ++++++++++---------
 .../status/case1/final/Gopkg.toml             | 19 ++++++-------
 testdata/txn_writer/expected_manifest.toml    | 19 ++++++-------
 txn_writer.go                                 | 14 +++++-----
 15 files changed, 160 insertions(+), 146 deletions(-)

diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
index 88726bdefa..2eaaa0fde4 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
@@ -1,7 +1,6 @@
 
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -17,20 +16,22 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
index aaf4b360a6..9f33fae4b9 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
@@ -1,11 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = "^0.8.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = "^0.8.0"
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
index 98c427ddd4..13c03a3323 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
@@ -1,12 +1,6 @@
-ignored = ["github.com/sdboyer/deptestdos"]
-
-[[dependencies]]
-  branch = "master"
-  name = "github.com/sdboyer/deptest"
-
 
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -22,20 +16,27 @@ ignored = ["github.com/sdboyer/deptestdos"]
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+ignored = ["github.com/sdboyer/deptestdos"]
+
+[[dependencies]]
+  branch = "master"
+  name = "github.com/sdboyer/deptest"
diff --git a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
index 9f8ab4c7da..cc942db4b9 100644
--- a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
@@ -1,11 +1,6 @@
 
-[[overrides]]
-  name = "github.com/sdboyer/deptest"
-  version = "1.0.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[overrides]]
+  name = "github.com/sdboyer/deptest"
+  version = "1.0.0"
diff --git a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
index 2c6d74172a..edfd7acb39 100644
--- a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
@@ -1,15 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-[[dependencies]]
-  name = "github.com/sdboyer/deptestdos"
-  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -25,20 +16,30 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptestdos"
+  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
diff --git a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
index 3603716a6a..f28f98cc41 100644
--- a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
@@ -1,11 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
diff --git a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
index ff5104bf39..a76c2671ff 100644
--- a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
@@ -1,15 +1,6 @@
 
-[[dependencies]]
-  branch = "master"
-  name = "github.com/sdboyer/deptest"
-
-[[dependencies]]
-  name = "github.com/sdboyer/deptestdos"
-  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -25,20 +16,30 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  branch = "master"
+  name = "github.com/sdboyer/deptest"
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptestdos"
+  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
diff --git a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
index 88726bdefa..2eaaa0fde4 100644
--- a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
@@ -1,7 +1,6 @@
 
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -17,20 +16,22 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
diff --git a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
index 3603716a6a..f28f98cc41 100644
--- a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
@@ -1,11 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
index 2c6d74172a..edfd7acb39 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
@@ -1,15 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-[[dependencies]]
-  name = "github.com/sdboyer/deptestdos"
-  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -25,20 +16,30 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptestdos"
+  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
index 2c6d74172a..edfd7acb39 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
@@ -1,15 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-[[dependencies]]
-  name = "github.com/sdboyer/deptestdos"
-  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -25,20 +16,30 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptestdos"
+  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
diff --git a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
index 2c6d74172a..edfd7acb39 100644
--- a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
@@ -1,15 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-[[dependencies]]
-  name = "github.com/sdboyer/deptestdos"
-  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -25,20 +16,30 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptestdos"
+  revision = "a0196baa11ea047dd65037287451d36b861b00ea"
diff --git a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
index 3603716a6a..f28f98cc41 100644
--- a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
@@ -1,11 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/deptest"
-  version = ">=0.8.0, <1.0.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/deptest"
+  version = ">=0.8.0, <1.0.0"
diff --git a/testdata/txn_writer/expected_manifest.toml b/testdata/txn_writer/expected_manifest.toml
index c96351e0c9..d49cb4a62d 100644
--- a/testdata/txn_writer/expected_manifest.toml
+++ b/testdata/txn_writer/expected_manifest.toml
@@ -1,11 +1,6 @@
 
-[[dependencies]]
-  name = "github.com/sdboyer/dep-test"
-  version = "1.0.0"
-
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -21,20 +16,26 @@
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
+
+[[dependencies]]
+  name = "github.com/sdboyer/dep-test"
+  version = "1.0.0"
diff --git a/txn_writer.go b/txn_writer.go
index f08d706a81..5c33b09c84 100644
--- a/txn_writer.go
+++ b/txn_writer.go
@@ -22,9 +22,8 @@ import (
 // if no dependencies are found in the project
 // during `dep init`
 const exampleTOML = `
-
 ## EXAMPLES & DOCS - safe to delete!
-
+#
 ## Dependencies define constraints on how dependent projects should be
 ## incorporated into Gopkg.lock. They are respected by dep whether
 ## this project is the current project, or if it's a dependency.
@@ -40,23 +39,25 @@ const exampleTOML = `
 ## Note: revision will depend on your repository type; git and hg have SHA1s,
 ## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
-
+#
 ## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
 ## all [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer, and should be used only as a last resort.
-
+#
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-
+#
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
+
+
 `
 
 // SafeWriter transactionalizes writes of manifest, lock, and vendor dir, both
@@ -299,7 +300,6 @@ func (sw *SafeWriter) Write(root string, sm gps.SourceManager) error {
 
 	if sw.Payload.HasManifest() {
 		// Always write the example text to the bottom of the TOML file.
-		examples := []byte(exampleTOML)
 		tb, err := sw.Payload.Manifest.MarshalTOML()
 		if err != nil {
 			return errors.Wrap(err, "failed to marshal manifest to TOML")
@@ -307,7 +307,7 @@ func (sw *SafeWriter) Write(root string, sm gps.SourceManager) error {
 
 		// 0666 is before umask; mirrors behavior of os.Create (used by
 		// writeFile())
-		if err = ioutil.WriteFile(filepath.Join(td, ManifestName), append(tb, examples...), 0666); err != nil {
+		if err = ioutil.WriteFile(filepath.Join(td, ManifestName), append([]byte(exampleTOML), tb...), 0666); err != nil {
 			return errors.Wrap(err, "failed to write manifest file to temp dir")
 		}
 	}

From 99f78614687d00fbb7980fdcba39382e1c29c88f Mon Sep 17 00:00:00 2001
From: sam boyer <tech@samboyer.org>
Date: Thu, 27 Apr 2017 23:51:57 -0400
Subject: [PATCH 4/5] Polish text some more

---
 .../ensure/empty/case1/final/Gopkg.toml       | 62 ++++++++++++-------
 .../ensure/empty/case2/final/Gopkg.toml       | 62 ++++++++++++-------
 .../ensure/empty/case3/final/Gopkg.toml       | 62 ++++++++++++-------
 .../ensure/override/case1/final/Gopkg.toml    | 62 ++++++++++++-------
 .../harness_tests/init/case1/final/Gopkg.toml | 62 ++++++++++++-------
 .../harness_tests/init/case2/final/Gopkg.toml | 62 ++++++++++++-------
 .../harness_tests/init/case3/final/Gopkg.toml | 62 ++++++++++++-------
 .../init/skip-hidden/final/Gopkg.toml         | 62 ++++++++++++-------
 .../remove/force/case1/final/Gopkg.toml       | 62 ++++++++++++-------
 .../remove/specific/case1/final/Gopkg.toml    | 62 ++++++++++++-------
 .../remove/specific/case2/final/Gopkg.toml    | 62 ++++++++++++-------
 .../remove/unused/case1/final/Gopkg.toml      | 62 ++++++++++++-------
 .../status/case1/final/Gopkg.toml             | 62 ++++++++++++-------
 testdata/txn_writer/expected_manifest.toml    | 62 ++++++++++++-------
 txn_writer.go                                 | 62 ++++++++++++-------
 15 files changed, 615 insertions(+), 315 deletions(-)

diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
index 2eaaa0fde4..06737feb4d 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
@@ -1,37 +1,57 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
index 9f33fae4b9..21a7bcdcf1 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
index 13c03a3323..09cff29fe4 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 ignored = ["github.com/sdboyer/deptestdos"]
diff --git a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
index cc942db4b9..e684194d45 100644
--- a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
index edfd7acb39..7cc76698e4 100644
--- a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
index f28f98cc41..8f3166c45d 100644
--- a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
index a76c2671ff..17f88d4fa5 100644
--- a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
index 2eaaa0fde4..06737feb4d 100644
--- a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
@@ -1,37 +1,57 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
diff --git a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
index f28f98cc41..8f3166c45d 100644
--- a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
index edfd7acb39..7cc76698e4 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
index edfd7acb39..7cc76698e4 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
index edfd7acb39..7cc76698e4 100644
--- a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
index f28f98cc41..8f3166c45d 100644
--- a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/testdata/txn_writer/expected_manifest.toml b/testdata/txn_writer/expected_manifest.toml
index d49cb4a62d..cbd415a29e 100644
--- a/testdata/txn_writer/expected_manifest.toml
+++ b/testdata/txn_writer/expected_manifest.toml
@@ -1,38 +1,58 @@
 
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 
diff --git a/txn_writer.go b/txn_writer.go
index 5c33b09c84..6a3bdf325d 100644
--- a/txn_writer.go
+++ b/txn_writer.go
@@ -22,40 +22,60 @@ import (
 // if no dependencies are found in the project
 // during `dep init`
 const exampleTOML = `
-## EXAMPLES & DOCS - safe to delete!
+## EXAMPLE (these lines may be deleted)
+#
+## "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. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#
+#
+## "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.
+# ignored = ["github.com/user/project/badpkg"]
+#
 #
-## Dependencies define constraints on how dependent projects should be
-## incorporated into Gopkg.lock. They are respected by dep whether
-## this project is the current project, or if it's a dependency.
 # [[dependencies]]
-## Required: the root import path of the project being constrained
+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
-## Optional: an alternate location (URL or import path) for the project's source
-# source = "https://github.com/myfork/package.git"
+#
 ## Optional, but recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
-## Note: revision will depend on your repository type; git and hg have SHA1s,
-## bzr a 3-part id, svn a revision number.
 # revision = "abc123"
 #
-## [[overrides]] follow the exact same structure as [[dependencies]], but supercede
-## all [[dependencies]] declarations from all projects. Only the current project's
+## Optional: an alternate location (URL or import path) for the project's source.
+# source = "https://github.com/myfork/package.git"
+#
+#
+# [[overrides]]
+## Overrides have the same structure as [[dependencies]], but supercede all
+## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
-## Overrides are a sledgehammer, and should be used only as a last resort.
+## Overrides are a sledgehammer. Use them only as a last resort.
 #
-## "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. Use it when your project needs a package it doesn't explicitly import -
-## including "main" packages.
-# required = ["github.com/user/thing/cmd/thing"]
+## Required: the root import path of the project being constrained.
+# name = "github.com/user/project"
 #
-## "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.
-# ignored = ["github.com/user/project/badpkg"]
+## Optional: specifying a version constraint override will cause all other
+## constraints on this project to be ignored; only the overriden constraint
+## need be satisfied.
+## Again, only one of "branch", "version" or "revision" can be specified.
+# version = "1.0.0"
+# branch = "master"
+# revision = "abc123"
+#
+## Optional: specifying an alternate source location as an override will
+## enforce that the alternate location is used for that project, regardless of
+## what source location any dependent projects specify.
+# source = "https://github.com/myfork/package.git"
 
 
 `

From f861939606061b06c72b00743ca1521dcb1cfe47 Mon Sep 17 00:00:00 2001
From: sam boyer <tech@samboyer.org>
Date: Fri, 28 Apr 2017 01:11:17 -0400
Subject: [PATCH 5/5] More tweaks based on review

---
 .../ensure/empty/case1/final/Gopkg.toml       | 21 +++++++------------
 .../ensure/empty/case2/final/Gopkg.toml       | 21 +++++++------------
 .../ensure/empty/case3/final/Gopkg.toml       | 21 +++++++------------
 .../ensure/override/case1/final/Gopkg.toml    | 21 +++++++------------
 .../harness_tests/init/case1/final/Gopkg.toml | 21 +++++++------------
 .../harness_tests/init/case2/final/Gopkg.toml | 21 +++++++------------
 .../harness_tests/init/case3/final/Gopkg.toml | 21 +++++++------------
 .../init/skip-hidden/final/Gopkg.toml         | 21 +++++++------------
 .../remove/force/case1/final/Gopkg.toml       | 21 +++++++------------
 .../remove/specific/case1/final/Gopkg.toml    | 21 +++++++------------
 .../remove/specific/case2/final/Gopkg.toml    | 21 +++++++------------
 .../remove/unused/case1/final/Gopkg.toml      | 21 +++++++------------
 .../status/case1/final/Gopkg.toml             | 21 +++++++------------
 testdata/txn_writer/expected_manifest.toml    | 21 +++++++------------
 txn_writer.go                                 | 21 +++++++------------
 15 files changed, 120 insertions(+), 195 deletions(-)

diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
index 06737feb4d..6b7a32babb 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
index 21a7bcdcf1..f00cb6004e 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case2/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
index 09cff29fe4..3988c0b041 100644
--- a/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/empty/case3/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
index e684194d45..d4b673fcb6 100644
--- a/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/ensure/override/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
index 7cc76698e4..7e37517cde 100644
--- a/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
index 8f3166c45d..4df6b969b4 100644
--- a/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case2/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
index 17f88d4fa5..32e395a63a 100644
--- a/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/case3/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
index 06737feb4d..6b7a32babb 100644
--- a/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/init/skip-hidden/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
index 8f3166c45d..4df6b969b4 100644
--- a/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/force/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
index 7cc76698e4..7e37517cde 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
index 7cc76698e4..7e37517cde 100644
--- a/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/specific/case2/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
index 7cc76698e4..7e37517cde 100644
--- a/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/remove/unused/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
index 8f3166c45d..4df6b969b4 100644
--- a/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
+++ b/cmd/dep/testdata/harness_tests/status/case1/final/Gopkg.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/testdata/txn_writer/expected_manifest.toml b/testdata/txn_writer/expected_manifest.toml
index cbd415a29e..e0e080df27 100644
--- a/testdata/txn_writer/expected_manifest.toml
+++ b/testdata/txn_writer/expected_manifest.toml
@@ -1,27 +1,24 @@
 
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -29,15 +26,13 @@
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
diff --git a/txn_writer.go b/txn_writer.go
index 6a3bdf325d..a31b511c16 100644
--- a/txn_writer.go
+++ b/txn_writer.go
@@ -22,29 +22,26 @@ import (
 // if no dependencies are found in the project
 // during `dep init`
 const exampleTOML = `
-## EXAMPLE (these lines may be deleted)
-#
+## Gopkg.toml example (these lines may be deleted)
+
 ## "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. Use it when your project needs a package it doesn't explicitly import -
 ## including "main" packages.
 # required = ["github.com/user/thing/cmd/thing"]
-#
-#
+
 ## "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.
 # ignored = ["github.com/user/project/badpkg"]
-#
-#
-# [[dependencies]]
+
 ## Dependencies define constraints on dependent projects. They are respected by
 ## dep whether coming from the Gopkg.toml of the current project or a dependency.
-#
+# [[dependencies]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #
-## Optional, but recommended: the version constraint to enforce for the project.
+## Recommended: the version constraint to enforce for the project.
 ## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"
 # branch = "master"
@@ -52,15 +49,13 @@ const exampleTOML = `
 #
 ## Optional: an alternate location (URL or import path) for the project's source.
 # source = "https://github.com/myfork/package.git"
-#
-#
-# [[overrides]]
+
 ## Overrides have the same structure as [[dependencies]], but supercede all
 ## [[dependencies]] declarations from all projects. Only the current project's
 ## [[overrides]] are applied.
 ##
 ## Overrides are a sledgehammer. Use them only as a last resort.
-#
+# [[overrides]]
 ## Required: the root import path of the project being constrained.
 # name = "github.com/user/project"
 #