└── README.md /README.md: -------------------------------------------------------------------------------- 1 | ## The Go vendor file specification 2 | 3 | ### Specification 4 | * Description and purpose: 5 | - Copying third-party vendor packages into a local project structure requires 6 | a meta-data file describing the vendor's packages. 7 | - The meta-data file describing the vendor's packages will be referred to as 8 | the vendor file. 9 | - The vendor file is to be used by a vendor tool or the developer; the vendor 10 | file is not used for compiling source code. 11 | * Vendor File: 12 | - The vendor file will be called "vendor.json" and be placed in a folder 13 | named "vendor". 14 | - The vendor file describes the packages in the vendor folder the vendor file is in. 15 | - The vendor file does not describe any nested vendor folders; nested vendor 16 | folders must contain their own vendor file. 17 | - The vendor file must be in or under a descendant of the "$GOPATH/src/" directory. 18 | - Additional fields may be added to the vendor file that is tool specific. 19 | - Each copied package entry is defined to match a single Go package. A 20 | vendor file Package entry does NOT match a package tree; a vendor file 21 | Package entry matches a single Go package. 22 | - A tool MUST persist any unknown fields when reading and writing out the 23 | vendor file. A tool may remove unknown fields on an explicit user request. 24 | This implies that a tool must not marshal or unmarshal from a known struct. 25 | 26 | The following struct describes well-known fields: 27 | ```go 28 | struct { 29 | // Comment is free text for human use. Example "Revision abc123 introduced 30 | // changes that are not backwards compatible, so leave this as def876." 31 | Comment string `json:"comment,omitempty"` 32 | 33 | // Package represents a collection of vendor packages that have been copied 34 | // locally. Each entry represents a single Go package. 35 | Package []struct { 36 | // Import path. Example "rsc.io/pdf". 37 | // go get should fetch the remote package. 38 | Path string `json:"path"` 39 | 40 | // Origin is an import path where it was copied from. This import path 41 | // may contain "vendor" segments. 42 | // 43 | // If empty or missing origin is assumed to be the same as the Path field. 44 | Origin string `json:"origin"` 45 | 46 | // The revision of the package. This field must be persisted by all 47 | // tools, but not all tools will interpret this field. 48 | // The value of Revision should be a single value that can be used 49 | // to fetch the same or similar revision. 50 | // Examples: "abc104...438ade0", "v1.3.5" 51 | Revision string `json:"revision"` 52 | 53 | // RevisionTime is the time the revision was created. The time should be 54 | // parsed and written in the "time.RFC3339" format. 55 | RevisionTime string `json:"revisionTime"` 56 | 57 | // Comment is free text for human use. 58 | Comment string `json:"comment,omitempty"` 59 | } `json:"package"` 60 | } 61 | ``` 62 | 63 | ### Example 64 | *vendor file path: "$GOPATH/src/github.com/kardianos/mypkg/vendor/vendor.json"* 65 | 66 | *first package copied to: "$GOPATH/src/github.com/kardianos/mypkg/vendor/rsc.io/pdf"* 67 | 68 | ```json 69 | { 70 | "comment": "Note the use of a non-standard crypto package.", 71 | "package": [ 72 | { 73 | "path": "rsc.io/pdf", 74 | "revision": "3a3aeae79a3ec4f6d093a6b036c24698938158f3", 75 | "revisionTime": "2014-09-25T17:07:18-04:00", 76 | "comment": "located on disk at $GOPATH/src/github.com/kardianos/mypkg/vendor/rsc.io/pdf" 77 | }, 78 | { 79 | "origin": "github.com/MSOpenTech/azure-sdk-for-go/vendor/crypto/tls", 80 | "path": "crypto/tls", 81 | "revision": "80a4e93853ca8af3e273ac9aa92b1708a0d75f3a", 82 | "revisionTime": "2015-04-07T09:07:15-07:00", 83 | "comment": "located on disk at $GOPATH/src/github.com/kardianos/mypkg/vendor/crypto/tls" 84 | }, 85 | { 86 | "path": "github.com/coreos/etcd/raft", 87 | "revision": "25f1feceb5e13da68a35ee552069f86d18d63fee", 88 | "revisionTime": "2015-04-09T05:06:17-08:00", 89 | "comment": "located on disk at $GOPATH/src/github.com/kardianos/mypkg/vendor/github.com/coreos/etcd/raft" 90 | }, 91 | { 92 | "path": "golang.org/x/net/context", 93 | "revision": "25f1feceb5e13da68a35ee552069f86d18d63fee", 94 | "revisionTime": "2015-04-09T05:06:17-08:00", 95 | "comment": "Use the 25f1 version. Located on disk at $GOPATH/src/github.com/kardianos/mypkg/vendor/golang.org/x/net/context" 96 | } 97 | ] 98 | } 99 | ``` 100 | *The above example would have the import paths as follows:* 101 | ```go 102 | import ( 103 | "rsc.io/pdf" 104 | "crypto/tls" 105 | "github.com/coreos/etcd/raft" 106 | "golang.org/x/net/context" 107 | ) 108 | ``` 109 | 110 | ### Package.Path and Package.Origin fields 111 | The Path field identifies the package with the import path. The package it 112 | describes will be rooted in the same vendor folder as the vendor file and be 113 | located at "Path" relative to the vendor folder. 114 | 115 | The Origin field contains the import path of the package it was copied from. 116 | If this field is empty or not present it is assumed to be the same as the Path 117 | field. This field is useful when updating dependencies. 118 | 119 | ### Revision and RevisionTime fields 120 | Both revision and revisionTime fields are optional. However tools must persist any information 121 | present in them. The interpretation of both fields is dependent on the tool 122 | itself. While the exact interpretation of the fields are tool specific, the 123 | semantics are not. The Revision field must either be empty or contain a single 124 | value that can be used to fetch a specific revision. The RevisionTime must be 125 | empty or have a valid RFC3339 time string. If the Revision field is non-empty 126 | the RevisionTime field must correlate with the Revision field. If the Revision 127 | field is empty the meaning of the RevisionTime field is tool specific. 128 | 129 | ## List of tools that support this specification 130 | * [github.com/kardianos/govendor](https://github.com/kardianos/govendor) 131 | --------------------------------------------------------------------------------