Goモジュールリファレンス（Go Modules Reference）

はじめに

モジュールは、Goが依存関係を管理する方法です。

この文書は、Goのモジュールシステムに関する詳細なリファレンスマニュアルです。Goプロジェクトの作成に関する紹介については、Goコードの書き方を参照してください。モジュールの使用、プロジェクトのモジュールへの移行、その他のトピックに関する情報については、Goモジュールの使用から始まるブログシリーズを参照してください。

モジュール、パッケージ、およびバージョン

モジュールは、リリースされ、バージョン管理され、一緒に配布されるパッケージのコレクションです。モジュールは、バージョン管理リポジトリまたはモジュールプロキシサーバーから直接ダウンロードできます。

モジュールは、モジュールパスによって識別され、go.modファイルに宣言され、モジュールの依存関係に関する情報とともに提供されます。モジュールルートディレクトリは、go.modファイルを含むディレクトリです。メインモジュールは、goコマンドが呼び出されるディレクトリを含むモジュールです。

モジュール内の各パッケージは、同じディレクトリ内のソースファイルのコレクションであり、一緒にコンパイルされます。パッケージパスは、モジュールパスと、モジュールルートに対して相対的なパッケージを含むサブディレクトリを結合したものです。たとえば、モジュール"golang.org/x/net"は、ディレクトリ"html"にパッケージを含んでいます。そのパッケージのパスは"golang.org/x/net/html"です。

モジュールパス

モジュールパスは、モジュールの標準名であり、モジュールのgo.modファイル内のmoduleディレクティブで宣言されます。モジュールのパスは、モジュール内のパッケージパスのプレフィックスです。

モジュールパスは、モジュールが何をするかと、どこで見つけるかを説明する必要があります。通常、モジュールパスは、リポジトリのルートパス、リポジトリ内のディレクトリ（通常は空）、およびメジャーバージョンのサフィックス（メジャーバージョン2以上の場合のみ）で構成されます。

• リポジトリのルートパスは、モジュールが開発されているバージョン管理リポジトリのルートディレクトリに対応するモジュールパスの部分です。ほとんどのモジュールは、リポジトリのルートディレクトリで定義されているため、通常はこの全体のパスです。たとえば、golang.org/x/netは、同名のモジュールのリポジトリルートパスです。モジュールパスを使用してリポジトリを見つける方法については、モジュールパスのリポジトリを見つけるを参照してください。
• モジュールがリポジトリのルートディレクトリで定義されていない場合、モジュールサブディレクトリは、メジャーバージョンサフィックスを含まないディレクトリの名前を示すモジュールパスの部分です。これは、セマンティックバージョンタグのプレフィックスとしても機能します。たとえば、モジュールgolang.org/x/tools/goplsは、ルートパスgolang.org/x/toolsのリポジトリのgoplsサブディレクトリにあるため、モジュールサブディレクトリgoplsを持ちます。コミットにバージョンをマッピングおよびリポジトリ内のモジュールディレクトリを参照してください。
• モジュールがメジャーバージョン2以上でリリースされる場合、モジュールパスは/v2のようなメジャーバージョンサフィックスで終わる必要があります。これは、サブディレクトリ名の一部である場合もあれば、そうでない場合もあります。たとえば、パスgolang.org/x/repo/sub/v2のモジュールは、リポジトリgolang.org/x/repoの/subまたは/sub/v2サブディレクトリにある可能性があります。

他のモジュールが依存する可能性があるモジュールの場合、goコマンドがモジュールを見つけてダウンロードできるように、これらのルールを遵守する必要があります。また、モジュールパスに許可される文字に関するいくつかの字句制限もあります。

他のモジュールの依存関係として決して取得されないモジュールは、そのモジュールパスに対して有効なパッケージパスを使用できますが、モジュールの依存関係やGo標準ライブラリで使用される可能性のあるパスと衝突しないように注意する必要があります。Go標準ライブラリは、最初のパス要素にドットを含まないパッケージパスを使用し、goコマンドは、ネットワークサーバーからそのようなパスを解決しようとはしません。パスexampleおよびtestはユーザーのために予約されています：これらは標準ライブラリでは使用されず、チュートリアルやサンプルコードで定義された自己完結型モジュールや、テストの一部として作成および操作されるモジュールで使用するのに適しています。

バージョン

バージョンは、モジュールの不変のスナップショットを識別します。これは、リリースまたはプレリリースのいずれかです。各バージョンは、vの文字で始まり、その後にセマンティックバージョンが続きます。バージョンのフォーマット、解釈、および比較に関する詳細については、セマンティックバージョニング2.0.0を参照してください。

要約すると、セマンティックバージョンは、ドットで区切られた3つの非負整数（左から右に、メジャー、マイナー、パッチバージョン）で構成されます。パッチバージョンの後には、ハイフンで始まるオプションのプレリリース文字列が続く場合があります。プレリリース文字列またはパッチバージョンの後には、プラスで始まるビルドメタデータ文字列が続く場合があります。たとえば、v0.0.0、v1.12.134、v8.0.5-pre、およびv2.0.9+metaは有効なバージョンです。

バージョンの各部分は、そのバージョンが安定しているかどうか、また以前のバージョンと互換性があるかどうかを示します。

• メジャーバージョンは、モジュールの公開インターフェースまたは文書化された機能に対して後方互換性のない変更が行われた後にインクリメントされ、マイナーバージョンとパッチバージョンはゼロに設定される必要があります。たとえば、パッケージが削除された後です。
• マイナーバージョンは、後方互換性のある変更が行われた後にインクリメントされ、パッチバージョンはゼロに設定される必要があります。たとえば、新しい関数が追加された後です。
• パッチバージョンは、モジュールの公開インターフェースに影響を与えない変更（バグ修正や最適化など）の後にインクリメントされる必要があります。
• プレリリースサフィックスは、バージョンがプレリリースであることを示します。プレリリースバージョンは、対応するリリースバージョンの前にソートされます。たとえば、v1.2.3-preはv1.2.3の前に来ます。
• ビルドメタデータサフィックスは、バージョンの比較の目的で無視されます。goコマンドは、ビルドメタデータを含むバージョンを受け入れ、それらを擬似バージョンに変換して、バージョン間の全体的な順序を維持します。特別なサフィックス+incompatibleは、モジュールバージョンメジャーバージョン2またはそれ以降に移行する前にリリースされたバージョンを示します（非モジュールリポジトリとの互換性を参照）。

バージョンは、メジャーバージョンが0であるか、プレリリースサフィックスがある場合は不安定と見なされます。不安定なバージョンは互換性要件の対象ではありません。たとえば、v0.2.0はv0.1.0と互換性がない場合があり、v1.5.0-betaはv1.5.0と互換性がない場合があります。

Goは、これらの規則に従わないタグ、ブランチ、またはリビジョンを使用してバージョン管理システム内のモジュールにアクセスできます。ただし、メインモジュール内では、goコマンドがこの標準に従わないリビジョン名を自動的に標準バージョンに変換します。goコマンドも、このプロセスの一環としてビルドメタデータサフィックス（+incompatibleを除く）を削除します。これにより、リビジョン識別子（Gitコミットハッシュなど）とバージョン管理システムからのタイムスタンプをエンコードしたプレリリースバージョンである擬似バージョンが生成される場合があります。たとえば、go get golang.org/x/net@daa7c041コマンドは、コミットハッシュdaa7c041を擬似バージョンv0.0.0-20191109021931-daa7c04131f5に変換します。標準バージョンはメインモジュールの外部で必要であり、goコマンドは、masterのような非標準バージョンがgo.modファイルに現れた場合にエラーを報告します。

擬似バージョン

擬似バージョンは、バージョン管理リポジトリ内の特定のリビジョンに関する情報をエンコードした特別にフォーマットされたプレリリースバージョンです。たとえば、v0.0.0-20191109021931-daa7c04131f5は擬似バージョンです。

擬似バージョンは、セマンティックバージョンタグが利用できないリビジョンを参照することがあります。これらは、バージョンタグを作成する前にコミットをテストするために使用される場合があります。たとえば、開発ブランチでの使用です。

各擬似バージョンには3つの部分があります：

• ベースバージョンプレフィックス（vX.0.0またはvX.Y.Z-0）、これはリビジョンの前にあるセマンティックバージョンタグから派生したものであるか、vX.0.0である場合があります。
• タイムスタンプ（yyyymmddhhmmss）、これはリビジョンが作成されたUTC時間です。Gitでは、これはコミット時間であり、著者時間ではありません。
• リビジョン識別子（abcdefabcdef）、これはコミットハッシュの12文字のプレフィックス、またはSubversionではゼロパディングされたリビジョン番号です。

各擬似バージョンは、ベースバージョンに応じて3つの形式のいずれかになります。これらの形式は、擬似バージョンがそのベースバージョンよりも高く、次のタグ付きバージョンよりも低く比較されることを保証します。

• vX.0.0-yyyymmddhhmmss-abcdefabcdefは、既知のベースバージョンがない場合に使用されます。すべてのバージョンと同様に、メジャーバージョンXはモジュールのメジャーバージョンサフィックスと一致する必要があります。
• vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdefは、ベースバージョンがvX.Y.Z-preのようなプレリリースバージョンである場合に使用されます。
• vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdefは、ベースバージョンがvX.Y.Zのようなリリースバージョンである場合に使用されます。たとえば、ベースバージョンがv1.2.3の場合、擬似バージョンはv1.2.4-0.20191109021931-daa7c04131f5になる可能性があります。

複数の擬似バージョンが異なるベースバージョンを使用して同じコミットを参照することがあります。これは、擬似バージョンが書かれた後に低いバージョンがタグ付けされると自然に発生します。

これらの形式は、擬似バージョンに2つの便利な特性を与えます：

• 既知のベースバージョンを持つ擬似バージョンは、それらのバージョンよりも高く、後のバージョンの他のプレリリースよりも低くソートされます。
• 同じベースバージョンプレフィックスを持つ擬似バージョンは、時系列でソートされます。

- ベースバージョンが指定されている場合、擬似バージョンで説明されているリビジョンの先祖である対応するセマンティックバージョンタグが存在する必要があります。これにより、開発者が擬似バージョンを使用して、`````v1.999.999-99999999999999-daa7c04131f5`````のようなすべてのタグ付きバージョンよりも高く比較されることを回避できます。 
- タイムスタンプはリビジョンのタイムスタンプと一致する必要があります。これにより、攻撃者が[モジュールプロキシ](#glos-module-proxy)に無限の数の同一の擬似バージョンを氾濫させることを防ぎます。また、モジュールの消費者がバージョンの相対的な順序を変更することを防ぎます。 
- リビジョンは、モジュールリポジトリのブランチまたはタグのいずれかの先祖である必要があります。これにより、攻撃者が承認されていない変更やプルリクエストを参照することを防ぎます。
擬似バージョンは手動で入力する必要はありません。多くのコマンドはコミットハッシュまたはブランチ名を受け入れ、自動的に擬似バージョン（または利用可能な場合はタグ付きバージョン）に変換します。たとえば：  
``````bash
go get example.com/mod@master
go list -m -json example.com/mod@abcd1234
`

メジャーバージョンサフィックス

メジャーバージョン2以降、モジュールパスには、/v2のようなメジャーバージョンサフィックスが必要であり、メジャーバージョンと一致する必要があります。たとえば、モジュールがexample.com/modのパスを持ち、v1.0.0である場合、example.com/mod/v2のパスをv2.0.0のバージョンで持つ必要があります。

メジャーバージョンサフィックスは、インポート互換性ルールを実装します：

古いパッケージと新しいパッケージが同じインポートパスを持つ場合、
新しいパッケージは古いパッケージと後方互換性がある必要があります。
定義上、新しいメジャーバージョンのモジュール内のパッケージは、前のメジャーバージョンの対応するパッケージと後方互換性がありません。したがって、v2以降、パッケージには新しいインポートパスが必要です。これは、モジュールパスにメジャーバージョンサフィックスを追加することで実現されます。モジュールパスは、モジュール内の各パッケージのインポートパスのプレフィックスであるため、モジュールパスにメジャーバージョンサフィックスを追加することで、互換性のない各バージョンに対して異なるインポートパスが提供されます。

メジャーバージョンサフィックスは、メジャーバージョンv0またはv1では許可されていません。v0とv1の間でモジュールパスを変更する必要はありません。なぜなら、v0バージョンは不安定であり、互換性の保証がないからです。さらに、ほとんどのモジュールにとって、v1は最後のv0バージョンと後方互換性があります。v1バージョンは、v0と比較して互換性を約束するものであり、互換性のない変更を示すものではありません。

特別なケースとして、gopkg.in/で始まるモジュールパスは、v0およびv1でも常にメジャーバージョンサフィックスを持つ必要があります。サフィックスはスラッシュではなくドットで始まる必要があります（たとえば、gopkg.in/yaml.v2）。

メジャーバージョンサフィックスは、モジュールの複数のメジャーバージョンが同じビルド内で共存できるようにします。これは、ダイヤモンド依存関係の問題が原因で必要になる場合があります。通常、モジュールが推移的依存関係によって2つの異なるバージョンで要求される場合、高いバージョンが使用されます。ただし、2つのバージョンが互換性がない場合、どちらのバージョンもすべてのクライアントを満たすことはできません。互換性のないバージョンは異なるメジャーバージョン番号を持つ必要があるため、メジャーバージョンサフィックスにより異なるモジュールパスを持つ必要があります。これにより、モジュールの衝突が解決されます：異なるサフィックスを持つモジュールは別々のモジュールとして扱われ、そのパッケージはモジュールルートに対して同じサブディレクトリにあるパッケージであっても異なります。

多くのGoプロジェクトは、モジュールに移行する前にメジャーバージョンv2以上のバージョンをリリースしました（おそらくモジュールが導入される前に）。これらのバージョンには、+incompatibleビルドタグ（たとえば、v2.0.0+incompatible）が付けられています。非モジュールリポジトリとの互換性についての詳細は、こちらを参照してください。

パッケージをモジュールに解決する

`````go`````コマンドは、パッケージパスのプレフィックスを持つモジュールを[ビルドリスト](#glos-build-list)で検索することから始まります。たとえば、パッケージ`````example.com/a/b`````がインポートされ、モジュール`````example.com/a`````がビルドリストにある場合、`````go`````コマンドは、`````example.com/a`````が`````b`````ディレクトリにパッケージを含むかどうかを確認します。ディレクトリ内に`````.go`````拡張子を持つファイルが少なくとも1つ存在する必要があります。 [ビルド制約](https://golang.org/pkg/go/build/#hdr-Build_Constraints)はこの目的には適用されません。ビルドリスト内のモジュールがパッケージを提供している場合、そのモジュールが使用されます。モジュールがパッケージを提供していない場合、または2つ以上のモジュールがパッケージを提供している場合、`````go`````コマンドはエラーを報告します。`````-mod=mod`````フラグは、`````go`````コマンドに、欠落しているパッケージを提供する新しいモジュールを見つけようとし、`````go.mod`````および`````go.sum`````を更新するよう指示します。[`````go get`````](#go-get)および[`````go mod tidy`````](#go-mod-tidy)コマンドはこれを自動的に行います。  
`````go`````コマンドがパッケージパスの新しいモジュールを検索する際、`````GOPROXY`````環境変数を確認します。これは、プロキシURLのカンマ区切りリストまたはキーワード`````direct`````または`````off`````です。プロキシURLは、`````go`````コマンドが[モジュールプロキシ](#glos-module-proxy)に[`````GOPROXY`````プロトコル](#goproxy-protocol)を使用して連絡する必要があることを示します。`````direct`````は、`````go`````コマンドが[バージョン管理システム](#vcs)と通信する必要があることを示します。`````off`````は、通信を試みないことを示します。`````GOPRIVATE`````および`````GONOPROXY````` [環境変数](#environment-variables)もこの動作を制御するために使用できます。  
`````GOPROXY`````リスト内の各エントリについて、`````go`````コマンドは、パッケージを提供する可能性のある各モジュールパス（すなわち、パッケージパスの各プレフィックス）の最新バージョンを要求します。成功裏に要求された各モジュールパスについて、`````go`````コマンドは、最新バージョンのモジュールをダウンロードし、そのモジュールが要求されたパッケージを含むかどうかを確認します。1つ以上のモジュールが要求されたパッケージを含む場合、最も長いパスを持つモジュールが使用されます。1つ以上のモジュールが見つかりましたが、いずれも要求されたパッケージを含まない場合、エラーが報告されます。モジュールが見つからない場合、`````go`````コマンドは`````GOPROXY`````リストの次のエントリを試みます。エントリが残っていない場合、エラーが報告されます。  
たとえば、`````go`````コマンドがパッケージ`````golang.org/x/net/html`````を提供するモジュールを探しているとし、`````GOPROXY`````が`````https://corp.example.com,https://proxy.golang.org`````に設定されているとします。`````go`````コマンドは、次のリクエストを行う場合があります：  
- `````https://corp.example.com/`````に（並行して）：  
  - `````golang.org/x/net/html`````の最新バージョンを要求  
  - `````golang.org/x/net`````の最新バージョンを要求  
  - `````golang.org/x`````の最新バージョンを要求  
  - `````golang.org`````の最新バージョンを要求   
- `````https://proxy.golang.org/`````に、`````https://corp.example.com/`````へのすべてのリクエストが404または410で失敗した場合：  
  - `````golang.org/x/net/html`````の最新バージョンを要求  
  - `````golang.org/x/net`````の最新バージョンを要求  
  - `````golang.org/x`````の最新バージョンを要求  
  - `````golang.org`````の最新バージョンを要求
適切なモジュールが見つかった後、`````go`````コマンドは、新しいモジュールのパスとバージョンをメインモジュールの`````go.mod`````ファイルに新しい[要件](#go-mod-file-require)として追加します。これにより、将来同じパッケージがロードされるときに、同じモジュールが同じバージョンで使用されることが保証されます。解決されたパッケージがメインモジュール内のパッケージによってインポートされていない場合、新しい要件には`````// indirect`````コメントが付けられます。  
 <a name="go-mod-file"></a>
## go.modファイル
モジュールは、ルートディレクトリにある`````go.mod`````という名前のUTF-8エンコードされたテキストファイルによって定義されます。`````go.mod`````ファイルは行指向です。各行は、キーワードと引数で構成される単一のディレクティブを保持します。たとえば：  
``````bash
module example.com/my/thing
go 1.12
require example.com/other/thing v1.0.2
require example.com/new/thing/v2 v2.3.4
exclude example.com/old/thing v1.2.3
replace example.com/bad/thing v1.4.5 => example.com/good/thing v1.4.5
retract [v1.9.0, v1.9.5]
`

先頭のキーワードは、隣接する行からファクタリングしてブロックを作成できます。Goのインポートのように。

require (
   example.com/new/thing/v2 v2.3.4
   example.com/old/thing v1.2.3
)

go.modファイルは、人間が読みやすく、機械が書き込めるように設計されています。goコマンドは、go.modファイルを変更するいくつかのサブコマンドを提供します。たとえば、go getは特定の依存関係をアップグレードまたはダウングレードできます。モジュールグラフをロードするコマンドは、必要に応じてgo.modを自動的に更新します。go mod editは、低レベルの編集を実行できます。golang.org/x/mod/modfileパッケージは、Goプログラムによって同じ変更をプログラム的に行うために使用できます。

 <a name="go-mod-file-lexical"></a>
### 字句要素
`````go.mod`````ファイルが解析されると、その内容はトークンのシーケンスに分割されます。トークンにはいくつかの種類があります：ホワイトスペース、コメント、句読点、キーワード、識別子、および文字列。  
*ホワイトスペース*は、スペース（U+0020）、タブ（U+0009）、キャリッジリターン（U+000D）、および改行（U+000A）で構成されます。改行以外のホワイトスペース文字は、結合されるトークンを分離する以外の効果はありません。改行は重要なトークンです。  
*コメント*は`````//`````で始まり、行の終わりまで続きます。`````/* */`````コメントは許可されていません。  
*句読点*トークンには、`````(`````、`````)`````、および`````=>`````が含まれます。  
*キーワード*は、`````go.mod`````ファイル内の異なる種類のディレクティブを区別します。許可されているキーワードは、`````module`````、`````go`````、`````require`````、`````replace`````、`````exclude`````、および`````retract`````です。  
*識別子*は、モジュールパスやセマンティックバージョンなどの非ホワイトスペース文字のシーケンスです。  
*文字列*は、引用符で囲まれた文字のシーケンスです。文字列には2種類あります：引用符で始まり、引用符で終わる解釈された文字列（`````"`````、U+0022）と、グレイヴアクセントで始まり、グレイヴアクセントで終わる生文字列（````` ` `````、U+0060）です。解釈された文字列には、バックスラッシュ（`````\`````、U+005C）の後に別の文字が続くエスケープシーケンスを含めることができます。エスケープされた引用符（`````\"`````）は、解釈された文字列を終了しません。解釈された文字列の引用されていない値は、引用符の間の文字のシーケンスであり、各エスケープシーケンスはバックスラッシュの後の文字に置き換えられます（たとえば、`````\"`````は`````"`````に置き換えられ、`````\n`````は`````n`````に置き換えられます）。対照的に、生文字列の引用されていない値は、単にグレイヴアクセントの間の文字のシーケンスです。生文字列内のバックスラッシュには特別な意味はありません。  
識別子と文字列は、`````go.mod`````文法で相互に置き換え可能です。  
 <a name="go-mod-file-ident"></a>
### モジュールパスとバージョン
ほとんどの識別子と文字列は、`````go.mod`````ファイル内のモジュールパスまたはバージョンです。  
モジュールパスは、次の要件を満たす必要があります：  
- パスは、スラッシュ（`````/`````、U+002F）で区切られた1つ以上のパス要素で構成される必要があります。スラッシュで始まったり終わったりしてはいけません。 
- 各パス要素は、ASCII文字、ASCII数字、および限られたASCII句読点（`````-`````、`````.`````、`````_`````、および`````~`````）で構成された非空の文字列である必要があります。 
- パス要素は、ドット（`````.`````、U+002E）で始まったり終わったりしてはいけません。 
- 最初のドットまでの要素プレフィックスは、Windows上の予約ファイル名であってはならず、大文字小文字を区別しません（`````CON`````、`````com1`````、`````NuL`````など）。 
- 最初のドットまでの要素プレフィックスは、チルダの後に1つ以上の数字が続くことはできません（`````EXAMPL~1.COM`````のように）。
モジュールパスが`````require`````ディレクティブに現れ、置き換えられない場合、またはモジュールパスが`````replace`````ディレクティブの右側に現れる場合、`````go`````コマンドは、そのパスを持つモジュールをダウンロードする必要がある場合があり、いくつかの追加要件を満たす必要があります。  
- 先頭のパス要素（最初のスラッシュまで、ある場合）は、慣例としてドメイン名であり、すべて小文字のASCII文字、ASCII数字、ドット（`````.`````、U+002E）、およびダッシュ（`````-`````、U+002D）で構成される必要があります。少なくとも1つのドットを含む必要があり、ダッシュで始まってはいけません。 
- `````/vN`````の形式の最終パス要素が`````N`````のように見える場合（ASCII数字とドット）、`````N`````は先頭のゼロで始まってはいけません。`````/v1`````であってはならず、ドットを含んではいけません。  
  - `````gopkg.in/`````で始まるパスの場合、この要件は[gopkg.in](https://gopkg.in)サービスの規則に従う必要があります。
`````go.mod`````ファイル内のバージョンは、[標準的](#glos-canonical-version)または非標準的である場合があります。  
標準的なバージョンは、`````v`````の文字で始まり、[セマンティックバージョニング2.0.0](https://semver.org/spec/v2.0.0.html)仕様に従ったセマンティックバージョンが続きます。バージョンに関する詳細は、[バージョン](#versions)を参照してください。  
ほとんどの他の識別子と文字列は、非標準的なバージョンとして使用できますが、ファイルシステム、リポジトリ、および[モジュールプロキシ](#glos-module-proxy)に関する問題を回避するためのいくつかの制限があります。非標準的なバージョンは、メインモジュールの`````go.mod`````ファイル内でのみ許可されます。`````go`````コマンドは、`````go.mod`````ファイルを自動的に[`````go.mod`````](#go-mod-file-updates)を更新する際に、各非標準的なバージョンを同等の標準的なバージョンに置き換えようとします。  
モジュールパスがバージョンに関連付けられている場所（`````require`````、`````replace`````、および`````exclude`````ディレクティブのように）、最終的なパス要素はバージョンと一貫性がなければなりません。[メジャーバージョンサフィックス](#major-version-suffixes)を参照してください。  
 <a name="go-mod-file-grammar"></a>
### 文法
`````go.mod`````構文は、拡張バックナウア形式（EBNF）を使用して以下に指定されています。EBNF構文の詳細については、[Go言語仕様の記法セクション](bd36d26997de6f01.md#Notation)を参照してください。  
``````bash
GoMod = { Directive } .
Directive = ModuleDirective |
   GoDirective |
   RequireDirective |
   ExcludeDirective |
   ReplaceDirective |
   RetractDirective .
`

改行、識別子、および文字列は、それぞれnewline、ident、およびstringで示されます。

モジュールパスとバージョンは、ModulePathおよびVersionで示されます。

ModulePath = ident | string . /* see restrictions above */
Version = ident | string .    /* see restrictions above */

モジュールディレクティブ

``````bash
ModuleDirective = "module" ( ModulePath | "(" newline ModulePath newline ")" ) newline .
`

例：

module golang.org/x/net

非推奨

モジュールは、段落の先頭に Deprecated: という文字列を含むコメントブロックで非推奨としてマークできます（大文字と小文字を区別）。非推奨メッセージはコロンの後に始まり、段落の最後まで続きます。コメントは、module ディレクティブの直前または同じ行の後に表示される場合があります。

例:

// Deprecated: use example.com/mod/v2 instead.
module example.com/mod

Go 1.17以降、go list -m -u は、ビルドリスト内のすべての非推奨モジュールに関する情報をチェックします。go get は、コマンドラインで指定されたパッケージをビルドするために必要な非推奨モジュールをチェックします。

go コマンドがモジュールの非推奨情報を取得すると、go.mod ファイルを @latest バージョンクエリ に一致するバージョンから読み込みますが、撤回 や 除外 は考慮されません。go コマンドは、同じ go.mod ファイルから 撤回されたバージョン のリストを読み込みます。

モジュールを非推奨にするには、著者は // Deprecated: コメントを追加し、新しいリリースにタグを付けることができます。著者は、より高いリリースで非推奨メッセージを変更または削除できます。

非推奨は、モジュールのすべてのマイナーバージョンに適用されます。v2 よりも高いメジャーバージョンは、この目的のために別のモジュールと見なされます。なぜなら、メジャーバージョンの接尾辞 がそれらに異なるモジュールパスを与えるからです。

非推奨メッセージは、モジュールがもはやサポートされていないことをユーザーに通知し、最新のメジャーバージョンへの移行手順を提供することを目的としています。個々のマイナーおよびパッチバージョンは非推奨にすることはできません; retract の方がより適切かもしれません。

go ディレクティブ

go ディレクティブは、モジュールが特定の Go バージョンのセマンティクスを前提として書かれたことを示します。バージョンは有効な Go バージョン でなければならず、1.9、1.14、または 1.21rc1 のようなものでなければなりません。

go ディレクティブは、このモジュールを使用するために必要な Go の最小バージョンを設定します。Go 1.21 より前は、このディレクティブは助言的なものでしたが、現在は必須の要件です: Go ツールチェーンは新しい Go バージョンを宣言するモジュールを使用することを拒否します。

go ディレクティブは、どの Go ツールチェーンを実行するかを選択するための入力です。詳細については、Go toolchains を参照してください。

go ディレクティブは新しい言語機能の使用に影響します:

• モジュール内のパッケージに対して、コンパイラは go ディレクティブで指定されたバージョン以降に導入された言語機能の使用を拒否します。たとえば、モジュールが go 1.12 ディレクティブを持っている場合、そのパッケージは Go 1.13 で導入された 1_000_000 のような数値リテラルを使用できません。
• 古い Go バージョンがモジュールのパッケージの一つをビルドし、コンパイルエラーに遭遇した場合、そのエラーはモジュールが新しい Go バージョンのために書かれたことを示します。たとえば、モジュールが go 1.13 を持ち、パッケージが数値リテラル 1_000_000 を使用しているとします。そのパッケージが Go 1.12 でビルドされると、コンパイラはそのコードが Go 1.13 のために書かれたことを示します。

go ディレクティブは go コマンドの動作にも影響します:

• go 1.14 以上では、自動 vendoring が有効になる場合があります。ファイル vendor/modules.txt が存在し、go.mod と一致している場合、-mod=vendor フラグを明示的に使用する必要はありません。
• go 1.16 以上では、all パッケージパターンは、main module 内のパッケージとテストによって間接的にインポートされたパッケージのみを一致させます。これは、モジュールが導入されて以来、go mod vendor によって保持されているパッケージの同じセットです。低いバージョンでは、all は、メインモジュール内のパッケージによってインポートされたパッケージのテスト、これらのパッケージのテストなども含まれます。
• go 1.17 以上では:
  • go.mod ファイルには、メインモジュール内のパッケージまたはテストによって間接的にインポートされるパッケージを提供する各モジュールに対して明示的な require ディレクティブ が含まれています。(go 1.16 およびそれ以下では、間接依存関係 は、最小バージョン選択 によって他のバージョンが選択される場合にのみ含まれます。)この追加情報は、モジュールグラフの剪定 と 遅延モジュールの読み込み を可能にします。
  • 以前の // indirect バージョンよりも多くの go 依存関係がある可能性があるため、間接依存関係は go.mod ファイル内の別のブロックに記録されます。
  • go mod vendor は、ベンダー依存関係の go.mod および go.sum ファイルを省略します。（これにより、go のサブディレクトリ内での vendor コマンドの呼び出しが正しいメインモジュールを特定できるようになります。）
  • go mod vendor は、各依存関係の go ファイルから go.mod バージョンを vendor/modules.txt に記録します。
• go 1.21 以上では:
  • go 行は、このモジュールで使用するための Go の必要最小バージョンを宣言します。
  • go 行は、すべての依存関係の go 行以上である必要があります。
  • go コマンドは、以前の古い Go バージョンとの互換性を維持しようとしなくなります。
  • go コマンドは、go.mod ファイル内の go.sum ファイルのチェックサムを保持することにより、より注意深くなります。

go.mod ファイルには、最大で 1 つの go ディレクティブを含めることができます。ほとんどのコマンドは、go ディレクティブを現在の Go バージョンで追加します。

go ディレクティブが欠落している場合、go 1.16 が仮定されます。

GoDirective = "go" GoVersion newline .
GoVersion = string | ident .  /* valid release version; see above */

例:

go 1.14

ツールチェインディレクティブ

toolchain ディレクティブは、モジュールで使用することを推奨する Go ツールチェインを宣言します。推奨される Go ツールチェインのバージョンは、go ディレクティブで宣言された必要な Go バージョンよりも小さくてはなりません。toolchain ディレクティブは、モジュールがメインモジュールであり、デフォルトのツールチェインのバージョンが推奨されるツールチェインのバージョンよりも小さい場合にのみ効果があります。

再現性のために、go コマンドは、go ファイルの toolchain 行に自分のツールチェイン名を書き込みます。これは、go.mod ファイルの go バージョンを更新するたびに行われます（通常は go get の間に）。

詳細については、「Go ツールチェイン」を参照してください。

ToolchainDirective = "toolchain" ToolchainName newline .
ToolchainName = string | ident .  /* valid toolchain name; see “Go toolchains” */

例:

toolchain go1.21.0

godebug ディレクティブ

godebug ディレクティブは、このモジュールがメインモジュールであるときに適用される単一の GODEBUG 設定 を宣言します。このような行は複数存在することができ、因数分解することができます。メインモジュールが存在しない GODEBUG キーを指定することはエラーです。godebug key=value の効果は、コンパイルされるすべてのメインパッケージが //go:debug key=value をリストしたソースファイルを含むかのようになります。

GodebugDirective = "godebug" ( GodebugSpec | "(" newline { GodebugSpec } ")" newline ) .
GodebugSpec = GodebugKey "=" GodebugValue newline.
GodebugKey = GodebugChar { GodebugChar }.
GodebugValue = GodebugChar { GodebugChar }.
GodebugChar = any non-space character except , " ` ' (comma and quotes).

例:

godebug default=go1.21
godebug (
   panicnil=1
   asynctimerchan=0
)

require ディレクティブ

require ディレクティブは、特定のモジュール依存関係の最小必要バージョンを宣言します。必要なモジュールバージョンごとに、go コマンドはそのバージョンの go.mod ファイルを読み込み、そのファイルからの要件を組み込みます。すべての要件が読み込まれた後、go コマンドは、最小バージョン選択 (MVS) を使用してそれらを解決し、ビルドリスト を生成します。

go コマンドは、一部の要件に対して自動的に // indirect コメントを追加します。// indirect コメントは、必要なモジュールからのパッケージが メインモジュール のいずれかのパッケージによって直接インポートされていないことを示します。

go ディレクティブ が go 1.16 またはそれ以下を指定している場合、go コマンドは、選択されたモジュールのバージョンが、メインモジュールの他の依存関係によってすでに暗黙的に示されているものよりも高い場合に間接的な要件を追加します。これは、明示的なアップグレード (go get -u ./...)、以前にその要件を課していた他の依存関係の削除 (go mod tidy)、または対応する要件が go.mod ファイルに存在しないパッケージをインポートする依存関係（go.mod ファイルがまったく存在しない依存関係など）によって発生する可能性があります。

go 1.17 以上では、go コマンドは、メインモジュール内のパッケージまたはテストによってインポートされる（間接的に でも）任意のパッケージを提供する各モジュールに対して間接的な要件を追加します。これらのより包括的な要件は、モジュールグラフの剪定 と 遅延モジュールの読み込み を可能にします。

RequireDirective = "require" ( RequireSpec | "(" newline { RequireSpec } ")" newline ) .
RequireSpec = ModulePath Version newline .

例:

require golang.org/x/net v1.2.3
require (
   golang.org/x/crypto v1.4.5 // indirect
   golang.org/x/text v1.6.7
)

exclude ディレクティブ

exclude ディレクティブは、go コマンドによってモジュールバージョンが読み込まれるのを防ぎます。

Go 1.16以降、メインモジュールの go.mod ファイル内の require ディレクティブによって参照されるバージョンが exclude ディレクティブによって除外されている場合、その要件は無視されます。これにより、go get や go mod tidy のようなコマンドが、go.mod に新しい要件を追加することがあり、適切であれば // indirect コメントが付けられます。

Go 1.16以前は、除外されたバージョンが require ディレクティブによって参照されている場合、go コマンドはモジュールの利用可能なバージョンをリストし（go list -m -versions で示されるように）、次の高い非除外バージョンを読み込みました。これにより、次の高いバージョンが時間とともに変わる可能性があるため、非決定的なバージョン選択が発生する可能性があります。この目的のために、リリースバージョンとプレリリースバージョンの両方が考慮されましたが、擬似バージョンは考慮されませんでした。高いバージョンが存在しない場合、go コマンドはエラーを報告しました。

exclude ディレクティブは、メインモジュールの go.mod ファイル内でのみ適用され、他のモジュールでは無視されます。詳細については、最小バージョン選択 を参照してください。

ExcludeDirective = "exclude" ( ExcludeSpec | "(" newline { ExcludeSpec } ")" newline ) .
ExcludeSpec = ModulePath Version newline .

例:

exclude golang.org/x/net v1.2.3
exclude (
   golang.org/x/crypto v1.4.5
   golang.org/x/text v1.6.7
)

replace ディレクティブ

replace ディレクティブは、特定のバージョンのモジュールまたはすべてのバージョンのモジュールの内容を、他の場所で見つかった内容に置き換えます。置き換えは、別のモジュールパスとバージョン、またはプラットフォーム固有のファイルパスのいずれかで指定できます。

バージョンが矢印の左側に存在する場合（=>）、その特定のバージョンのモジュールのみが置き換えられ、他のバージョンは通常通りアクセスされます。左側のバージョンが省略されている場合、モジュールのすべてのバージョンが置き換えられます。

矢印の右側のパスが絶対パスまたは相対パス（./ または ../ で始まる）である場合、それは置き換えモジュールのルートディレクトリへのローカルファイルパスとして解釈され、go.mod ファイルを含む必要があります。この場合、置き換えバージョンは省略する必要があります。

右側のパスがローカルパスでない場合、有効なモジュールパスでなければなりません。この場合、バージョンが必要です。同じモジュールバージョンはビルドリストにも表示されてはいけません。

ローカルパスまたはモジュールパスのいずれかで置き換えが指定されている場合でも、置き換えモジュールに go.mod ファイルがある場合、その module ディレクティブは置き換えられるモジュールパスと一致しなければなりません。

replace ディレクティブは、メインモジュールの go.mod ファイル内でのみ適用され、他のモジュールでは無視されます。詳細については、最小バージョン選択 を参照してください。

複数のメインモジュールがある場合、すべてのメインモジュールの go.mod ファイルが適用されます。メインモジュール間での replace ディレクティブの競合は許可されず、go.work file の置き換え で削除または上書きされなければなりません。

replace ディレクティブ単独では、モジュールグラフ にモジュールを追加しません。置き換えられたモジュールバージョンを参照する require ディレクティブ も必要です。これは、メインモジュールの go.mod ファイルまたは依存関係の go.mod ファイルのいずれかに必要です。左側のモジュールバージョンが必要でない場合、replace ディレクティブは効果がありません。

ReplaceDirective = "replace" ( ReplaceSpec | "(" newline { ReplaceSpec } ")" newline ) .
ReplaceSpec = ModulePath [ Version ] "=>" FilePath newline
   | ModulePath [ Version ] "=>" ModulePath Version newline .
FilePath = /* platform-specific relative or absolute file path */

例:

replace golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5
replace (
   golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5
   golang.org/x/net => example.com/fork/net v1.4.5
   golang.org/x/net v1.2.3 => ./fork/net
   golang.org/x/net => ./fork/net
)

retract ディレクティブ

retract ディレクティブは、go.mod によって定義されたモジュールのバージョンまたはバージョン範囲に依存しないことを示します。retract ディレクティブは、バージョンが早期に公開された場合や、公開後に深刻な問題が発見された場合に便利です。撤回されたバージョンは、ビルドが壊れないように、バージョン管理リポジトリや モジュールプロキシ に残しておく必要があります。撤回という言葉は学術文献から借用されたもので、撤回された研究論文は依然として利用可能ですが、問題があり、今後の作業の基礎としては使用されるべきではありません。

モジュールバージョンが撤回されると、ユーザーは go get、go mod tidy、または他のコマンドを使用して自動的にそれにアップグレードすることはありません。撤回されたバージョンに依存するビルドは引き続き動作するはずですが、ユーザーは go list -m -u で更新を確認したり、go get で関連モジュールを更新したりする際に撤回について通知されます。

バージョンを撤回するには、モジュールの著者は retract ディレクティブを go.mod に追加し、そのディレクティブを含む新しいバージョンを公開する必要があります。新しいバージョンは、他のリリースまたはプレリリースバージョンよりも高くなければなりません。つまり、@latest バージョンクエリ は、撤回が考慮される前に新しいバージョンに解決される必要があります。go コマンドは、go list -m -retracted $modpath@latest で示されたバージョンから撤回を読み込み、適用します（$modpath はモジュールパスです）。

撤回されたバージョンは、go list -m -versions で印刷されるバージョンリストから隠されます。-retracted フラグが使用されている場合を除きます。撤回されたバージョンは、@>=v1.2.3 や @latest のようなバージョンクエリを解決する際に除外されます。

撤回を含むバージョンは、自身を撤回することができます。モジュールの最高リリースまたはプレリリースバージョンが自らを撤回する場合、@latest クエリは、撤回されたバージョンが除外された後に低いバージョンに解決されます。

例として、モジュール example.com/m の著者が v1.0.0 バージョンを誤って公開したケースを考えてみましょう。v1.0.0 へのアップグレードを防ぐために、著者は retract ディレクティブを go.mod に2つ追加し、撤回を持つ v1.0.1 にタグを付けることができます。

retract (
   v1.0.0 // Published accidentally.
   v1.0.1 // Contains retractions only.
)

ユーザーが go get example.com/m@latest を実行すると、go コマンドは v1.0.1 から撤回を読み込みます。これは現在最高バージョンです。v1.0.0 と v1.0.1 は両方とも撤回されているため、go コマンドは次の高いバージョンにアップグレード（またはダウングレード！）します。おそらく v0.9.5 です。

retract ディレクティブは、v1.0.0 のような単一のバージョンまたは、[ と ] で区切られた上限と下限を持つバージョンの閉じた区間（[v1.1.0, v1.2.0] のような）で記述できます。単一のバージョンは、上限と下限が同じである区間に相当します。他のディレクティブと同様に、複数の retract ディレクティブは、行の終わりに ( で区切られたブロック内にグループ化できます。

各 retract ディレクティブには、撤回の理由を説明するコメントが必要ですが、これは必須ではありません。go コマンドは、撤回されたバージョンに関する警告で理由コメントを表示し、go list 出力に表示することがあります。理由コメントは、retract ディレクティブの直上（その間に空行がない）または同じ行の後に書くことができます。ブロックの上にコメントが表示されると、それはそのブロック内のすべての retract ディレクティブに適用されます（独自のコメントがないもの）。理由コメントは複数行にわたることができます。

RetractDirective = "retract" ( RetractSpec | "(" newline { RetractSpec } ")" newline ) .
RetractSpec = ( Version | "[" Version "," Version "]" ) newline .

例:

• v1.0.0 と v1.9.9 の間のすべてのバージョンを撤回する:

retract v1.0.0
retract [v1.0.0, v1.9.9]
retract (
   v1.0.0
   [v1.0.0, v1.9.9]
)

• 早期にリリースされたバージョン v1.0.0 の後に無バージョンに戻る:

retract [v0.0.0, v1.0.1] // assuming v1.0.1 contains this retraction.

• 擬似バージョンとタグ付けされたバージョンを含むモジュールを完全に消去する:

retract [v0.0.0-0, v0.15.2]  // assuming v0.15.2 contains this retraction.

retract ディレクティブは Go 1.16 で追加されました。Go 1.15 およびそれ以下では、メインモジュールの go.mod ファイルに retract ディレクティブが書かれている場合、エラーが報告され、依存関係の go.mod ファイル内の retract ディレクティブは無視されます。

自動更新

ほとんどのコマンドは、go.mod に情報が欠けているか、現実を正確に反映していない場合にエラーを報告します。go get および go mod tidy コマンドを使用して、これらの問題のほとんどを修正できます。さらに、-mod=mod フラグは、ほとんどのモジュール対応コマンド（go build、go test など）と共に使用して、go コマンドに go.mod および go.sum の問題を自動的に修正するよう指示できます。

たとえば、次の go.mod ファイルを考えてみましょう:

module example.com/M
go 1.16
require (
   example.com/A v1
   example.com/B v1.0.0
   example.com/C v1.0.0
   example.com/D v1.2.3
   example.com/E dev
)
exclude example.com/D v1.2.3

-mod=mod でトリガーされた更新は、非標準のバージョン識別子を 標準 のセマンバージョン形式に書き換えます。したがって、example.com/A の v1 は v1.0.0 になり、example.com/E の dev は dev ブランチの最新のコミットの擬似バージョンになります。おそらく v0.0.0-20180523231146-b3f5c0f6e5f1 です。

更新は、除外を尊重するように要件を修正します。したがって、除外された example.com/D v1.2.3 に対する要件は、example.com/D の次の利用可能なバージョンを使用するように更新されます。おそらく v1.2.4 または v1.3.0 です。

更新は、冗長または誤解を招く要件を削除します。たとえば、example.com/A v1.0.0 自体が example.com/B v1.2.0 および example.com/C v1.0.0 を要求している場合、go.mod の example.com/B v1.0.0 に対する要件は誤解を招く（example.com/A の v1.2.0 による必要性によって上書きされる）ものであり、example.com/C v1.0.0 に対する要件は冗長です（example.com/A の同じバージョンに対する必要性によって暗黙的に示される）ため、両方とも削除されます。メインモジュールが example.com/B または example.com/C から直接パッケージをインポートするパッケージを含む場合、要件は保持されますが、実際に使用されているバージョンに更新されます。

最後に、更新は go.mod を標準のフォーマットに再フォーマットします。これにより、将来の機械的変更が最小限の差分をもたらすようになります。go コマンドは、フォーマットの変更のみが必要な場合、go.mod を更新しません。

モジュールグラフはインポート文の意味を定義するため、パッケージを読み込むコマンドはすべて go.mod を使用し、したがってそれを更新できます。これには go build、go get、go install、go list、go test、go mod tidy が含まれます。

Go 1.15 およびそれ以下では、-mod=mod フラグはデフォルトで有効であったため、更新は自動的に行われました。Go 1.16 以降、go コマンドは -mod=readonly が設定されているかのように動作します。go.mod に変更が必要な場合、go コマンドはエラーを報告し、修正を提案します。

最小バージョン選択 (MVS)

Go は、パッケージをビルドする際に使用するモジュールバージョンのセットを選択するために 最小バージョン選択 (MVS) と呼ばれるアルゴリズムを使用します。MVS の詳細は、Russ Cox の 最小バージョン選択 に記載されています。

概念的に、MVS は、go.mod ファイル で指定されたモジュールの有向グラフで動作します。グラフの各頂点はモジュールバージョンを表し、各辺は依存関係の最小必要バージョンを表し、require ディレクティブを使用して指定されます。グラフは、メインモジュールの go.mod ファイル内の exclude および replace ディレクティブによって変更される場合があります。

MVS は、ビルドに使用されるモジュールバージョンのリストである ビルドリスト を出力として生成します。

MVS は、メインモジュール（グラフ内でバージョンを持たない特別な頂点）から開始し、グラフを横断して各モジュールの最も高い必要バージョンを追跡します。横断の最後に、最も高い必要バージョンがビルドリストを構成します。これらはすべての要件を満たす最小バージョンです。

ビルドリストは、go list -m all コマンドで検査できます。他の依存関係管理システムとは異なり、ビルドリストは「ロック」ファイルに保存されません。MVS は決定論的であり、依存関係の新しいバージョンがリリースされてもビルドリストは変わらないため、MVS はすべてのモジュール対応コマンドの開始時にそれを計算するために使用されます。

以下の図の例を考えてみましょう。メインモジュールは、モジュール A をバージョン 1.2 以上、モジュール B をバージョン 1.2 以上要求します。A 1.2 と B 1.2 は、それぞれ C 1.3 と C 1.4 を要求します。C 1.3 と C 1.4 はどちらも D 1.2 を要求します。

MVS は、青で強調表示された各モジュールバージョンの go.mod ファイルを訪問して読み込みます。グラフの横断の最後に、MVS は太字のバージョンを含むビルドリストを返します: A 1.2、B 1.2、C 1.4、および D 1.2。B と D の高いバージョンは利用可能ですが、MVS はそれらを選択しません。なぜなら、何もそれらを要求していないからです。

置き換え

モジュールの内容（go.mod ファイルを含む）は、メインモジュールの go.mod ファイルまたはワークスペースの go.work ファイル内の replace ディレクティブ を使用して置き換えることができます。replace ディレクティブは、特定のバージョンのモジュールまたはすべてのバージョンのモジュールに適用できます。

置き換えはモジュールグラフを変更します。置き換えモジュールは、置き換えられたバージョンとは異なる依存関係を持つ場合があります。

以下の例を考えてみましょう。C 1.4 は R に置き換えられています。R は D 1.3 に依存しており、D 1.2 ではありません。したがって、MVS は A 1.2、B 1.2、C 1.4（R に置き換えられた）、D 1.3 を含むビルドリストを返します。

除外

モジュールは、メインモジュールの go.mod ファイル内の exclude ディレクティブ を使用して特定のバージョンで除外することもできます。

除外もモジュールグラフを変更します。バージョンが除外されると、それはモジュールグラフから削除され、その要件は次の高いバージョンにリダイレクトされます。

以下の例を考えてみましょう。C 1.3 は除外されています。MVS は、A 1.2 が C 1.4（次の高いバージョン）を要求しているかのように動作します。

アップグレード

go get コマンドを使用して、モジュールのセットをアップグレードできます。アップグレードを実行するには、go コマンドがモジュールグラフを変更し、訪問されたバージョンからアップグレードされたバージョンへのエッジを追加します。

以下の例を考えてみましょう。モジュール B は 1.2 から 1.3 にアップグレードされ、C は 1.3 から 1.4 に、D は 1.2 から 1.3 にアップグレードされる可能性があります。

アップグレード（およびダウングレード）は、間接依存関係を追加または削除する場合があります。この場合、E 1.1 と F 1.1 は、B 1.3 に必要なため、アップグレード後にビルドリストに表示されます。

アップグレードを保持するために、go コマンドは go.mod の要件を更新します。B に対する要件をバージョン 1.3 に変更します。また、// indirect コメント付きで C 1.4 および D 1.3 に対する要件も追加します。これらのバージョンは、そうでなければ選択されないでしょう。

ダウングレード

go get コマンドを使用して、モジュールのセットをダウングレードすることもできます。ダウングレードを実行するには、go コマンドがモジュールグラフを変更し、ダウングレードされたバージョンより上のバージョンを削除します。また、削除されたバージョンに依存する他のモジュールのバージョンも削除されます。これらは、依存関係のダウングレードされたバージョンと互換性がない可能性があります。メインモジュールがダウングレードによって削除されたモジュールバージョンを要求する場合、その要件は削除されていない以前のバージョンに変更されます。以前のバージョンが利用できない場合、要件は削除されます。

以下の例を考えてみましょう。C 1.4 に問題が見つかったと仮定し、C 1.3 にダウングレードします。C 1.4 はモジュールグラフから削除されます。B 1.2 も削除されます。なぜなら、それは C 1.4 以上を要求するからです。メインモジュールの B に対する要件は 1.1 に変更されます。

go get は、引数の後に @none サフィックスを使用して依存関係を完全に削除することもできます。これはダウングレードと同様に機能します。指定されたモジュールのすべてのバージョンがモジュールグラフから削除されます。

モジュールグラフのプルーニング

メインモジュールが go 1.17 以上の場合、モジュールグラフ は、最小バージョン選択 のために、各モジュール依存関係が自身の go.mod ファイルで go 1.17 以上を指定している場合の 直接的 要件のみを含みます。ただし、そのモジュールのバージョンが go 1.16 以下の他の依存関係によっても（推移的に）必要とされている場合は除きます。(go 1.17 依存関係の 推移的 依存関係はモジュールグラフから プルーニング されます)。

go 1.17 go.mod ファイルには、そのモジュール内の任意のパッケージやテストをビルドするために必要なすべての依存関係の require ディレクティブ が含まれているため、プルーニングされたモジュールグラフには、メインモジュール に明示的に要求された依存関係のパッケージを go build または go test するために必要なすべての依存関係が含まれます。特定のモジュール内の任意のパッケージやテストをビルドするために必要でないモジュールは、そのパッケージのランタイム動作に影響を与えることはできないため、モジュールグラフからプルーニングされた依存関係は、無関係なモジュール間の干渉を引き起こすだけです。

要件がプルーニングされたモジュールは、モジュールグラフにまだ表示され、go list -m all によって報告されます: それらの 選択されたバージョン は知られており、明確に定義されており、パッケージはそれらのモジュールからロードできます（たとえば、他のモジュールからロードされたテストの推移的依存関係として）。ただし、go コマンドは、これらのモジュールのどの依存関係が満たされているかを簡単に特定できないため、go build および go test の引数には、要件がプルーニングされたモジュールからのパッケージを含めることはできません。go get は、各名前付きパッケージを含むモジュールを明示的な依存関係に昇格させ、そのパッケージに go build または go test を呼び出すことを可能にします。

Go 1.16 およびそれ以前のバージョンはモジュールグラフのプルーニングをサポートしていなかったため、依存関係の完全な推移的閉包 — 推移的 go 1.17 依存関係を含む — は、go 1.16 またはそれ以下を指定する各モジュールに対してまだ含まれています。(go 1.16 およびそれ以下では、go.mod ファイルには 直接依存関係 のみが含まれているため、すべての間接依存関係が含まれることを保証するために、はるかに大きなグラフをロードする必要があります)。

go.sum ファイル は、デフォルトで go mod tidy によってモジュールのために記録され、Go バージョン 1 つ下 のバージョンで必要なチェックサムを含みます。したがって、go 1.17 モジュールには、Go 1.16 によってロードされた完全なモジュールグラフに必要なチェックサムが含まれますが、go 1.18 モジュールには、Go 1.17 によってロードされたプルーニングされたモジュールグラフに必要なチェックサムのみが含まれます。-compat フラグを使用してデフォルトバージョンをオーバーライドできます（たとえば、go 1.17 モジュール内で go.sum ファイルをより積極的にプルーニングするために）。

詳細については、設計文書を参照してください。

レイジーモジュールローディング

モジュールグラフのプルーニングのために追加されたより包括的な要件は、モジュール内で作業する際の別の最適化も可能にします。メインモジュールが go 1.17 以上の場合、go コマンドは、必要になるまで（および必要になる場合にのみ）完全なモジュールグラフをロードすることを避けます。代わりに、メインモジュールの go.mod ファイルのみをロードし、その要件を使用してビルドするパッケージをロードしようとします。インポートされるパッケージ（たとえば、メインモジュールの外部のパッケージのテストの依存関係）がこれらの要件の中に見つからない場合、残りのモジュールグラフはオンデマンドでロードされます。

すべてのインポートされたパッケージがモジュールグラフをロードせずに見つけられる場合、go コマンドは、これらのパッケージを含むモジュールの go.mod ファイルのみをロードし、それらの要件がメインモジュールの要件とローカルで一貫していることを確認します。（不整合は、バージョン管理のマージ、手動編集、および置き換えを使用してローカルファイルシステムパスで変更されたモジュールによって発生する可能性があります。）

ワークスペース

ワークスペースは、最小バージョン選択 (MVS) を実行する際にメインモジュールとして使用されるディスク上のモジュールのコレクションです。

ワークスペースは、ワークスペース内の各モジュールのモジュールディレクトリへの相対パスを指定する go.work ファイル で宣言できます。go.work ファイルが存在しない場合、ワークスペースは現在のディレクトリを含む単一のモジュールで構成されます。

モジュールと連携する go サブコマンドのほとんどは、現在のワークスペースによって決定されたモジュールのセットで操作します。go mod init、go mod why、go mod edit、go mod tidy、go mod vendor、および go get は常に単一のメインモジュールで操作します。

コマンドは、最初に GOWORK 環境変数を調べることによって、ワークスペースコンテキストにいるかどうかを判断します。GOWORK が off に設定されている場合、コマンドは単一モジュールコンテキストにあります。空であるか提供されていない場合、コマンドは現在の作業ディレクトリを検索し、次に連続する親ディレクトリを検索して go.work ファイルを探します。ファイルが見つかると、コマンドはそれが定義するワークスペースで操作します。そうでない場合、ワークスペースには作業ディレクトリを含むモジュールのみが含まれます。GOWORK が .work で終わる既存のファイルへのパスを指定している場合、ワークスペースモードが有効になります。他の値はエラーです。go env GOWORK コマンドを使用して、go.work コマンドが使用している go ファイルを特定できます。go env GOWORK は、go コマンドがワークスペースモードでない場合は空になります。

go.work ファイル

ワークスペースは、go.work という名前の UTF-8 エンコードされたテキストファイルによって定義されます。go.work ファイルは行指向です。各行は、キーワードと引数から成る単一のディレクティブを保持します。たとえば:

go 1.18
use ./my/first/thing
use ./my/second/thing
replace example.com/bad/thing v1.4.5 => example.com/good/thing v1.4.5

go.mod ファイルと同様に、先頭のキーワードは隣接する行からファクタリングしてブロックを作成できます。

use (
   ./my/first/thing
   ./my/second/thing
)

go コマンドは、go.work ファイルを操作するためのいくつかのサブコマンドを提供します。go work init は新しい go.work ファイルを作成します。go work use は go.work ファイルにモジュールディレクトリを追加します。go work edit は低レベルの編集を行います。golang.org/x/mod/modfile パッケージは、Go プログラムによって同じ変更をプログラム的に行うために使用できます。

go コマンドは、ワークスペースによって使用されるハッシュを追跡する go.work.sum ファイルを維持します。

一般的に、go.work ファイルをバージョン管理システムにコミットすることは推奨されません。理由は二つあります:

• チェックインされた go.work ファイルは、開発者の親ディレクトリからの go.work ファイルを上書きする可能性があり、use ディレクティブが適用されないときに混乱を引き起こす可能性があります。
• チェックインされた go.work ファイルは、継続的インテグレーション (CI) システムがモジュールの依存関係の誤ったバージョンを選択し、したがってテストする原因となる可能性があります。CI システムは、他のモジュールによって要求されるときにモジュールの動作をテストできるように、go.work ファイルを使用することは一般的に許可されるべきではありません。モジュール内の go.work ファイルは影響を与えません。

とはいえ、go.work ファイルをコミットすることが意味を持つ場合もあります。たとえば、リポジトリ内のモジュールが外部モジュールと一緒にではなく、互いに専ら開発されている場合、開発者がワークスペース内で異なるモジュールの組み合わせを使用したい理由はないかもしれません。その場合、モジュールの著者は、個々のモジュールが適切にテストされ、リリースされることを確認する必要があります。

字句要素

go.work ファイルの字句要素は、go.mod files と同じ方法で定義されています#go-mod-file-lexical。

文法

go.work 構文は、拡張バックナウア形式 (EBNF) を使用して以下に指定されています。詳細については、Go 言語仕様の記法セクションを参照してください。

GoWork = { Directive } .
Directive = GoDirective |
   ToolchainDirective |
   UseDirective |
   ReplaceDirective .

改行、識別子、および文字列は、それぞれnewline、ident、およびstringで示されます。

モジュールパスとバージョンは ModulePath および Version で示されます。モジュールパスとバージョンは、go.mod files と同じ方法で指定されます#go-mod-file-lexical。

ModulePath = ident | string . /* see restrictions above */
Version = ident | string .    /* see restrictions above */

go ディレクティブ

有効な go.work ファイルには go ディレクティブが必要です。バージョンは有効な Go リリースバージョンでなければなりません: 正の整数の後にドットと非負整数が続きます（たとえば、1.18、1.19）。

go ディレクティブは、go.work ファイルが意図されている Go ツールチェーンのバージョンを示します。go.work ファイル形式に変更が加えられた場合、ツールチェーンの将来のバージョンは、指定されたバージョンに従ってファイルを解釈します。

go.work ファイルには、最大で 1 つの go ディレクティブを含めることができます。

GoDirective = "go" GoVersion newline .
GoVersion = string | ident .  /* valid release version; see above */

例:

go 1.18

ツールチェーンディレクティブ

toolchain ディレクティブは、ワークスペースで使用することを推奨する Go ツールチェーンを宣言します。デフォルトのツールチェーンが推奨ツールチェーンよりも古い場合にのみ効果があります。

詳細については、「Go ツールチェイン」を参照してください。

ToolchainDirective = "toolchain" ToolchainName newline .
ToolchainName = string | ident .  /* valid toolchain name; see “Go toolchains” */

例:

toolchain go1.21.0

godebug ディレクティブ

godebug ディレクティブは、このワークスペースで作業する際に適用される単一の GODEBUG 設定 を宣言します。構文と効果は、go.mod ファイルの godebug ディレクティブと同じです。ワークスペースが使用されている場合、godebug ディレクティブは go.mod ファイルで無視されます。

use ディレクティブ

use は、ディスク上のモジュールをワークスペース内のメインモジュールのセットに追加します。その引数は、モジュールの go.mod ファイルを含むディレクトリへの相対パスです。use ディレクティブは、その引数ディレクトリのサブディレクトリに含まれるモジュールを追加しません。それらのモジュールは、go.mod ファイルを含むディレクトリによって、別の use ディレクティブで追加される可能性があります。

UseDirective = "use" ( UseSpec | "(" newline { UseSpec } ")" newline ) .
UseSpec = FilePath newline .
FilePath = /* platform-specific relative or absolute file path */

例:

use ./mymod  // example.com/mymod
use (
   ../othermod
   ./subdir/thirdmod
)

replace ディレクティブ

replace ディレクティブは、go.mod ファイル内の replace ディレクティブに似ており、特定のバージョンのモジュールの内容、またはモジュールのすべてのバージョンの内容を他の場所で見つかった内容に置き換えます。go.work 内のワイルドカード置き換えは、replace ファイル内のバージョン固有の go.mod をオーバーライドします。

replace ディレクティブは、go.work ファイル内の同じモジュールまたはモジュールバージョンの置き換えをオーバーライドします。

ReplaceDirective = "replace" ( ReplaceSpec | "(" newline { ReplaceSpec } ")" newline ) .
ReplaceSpec = ModulePath [ Version ] "=>" FilePath newline
   | ModulePath [ Version ] "=>" ModulePath Version newline .
FilePath = /* platform-specific relative or absolute file path */

例:

replace golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5
replace (
   golang.org/x/net v1.2.3 => example.com/fork/net v1.4.5
   golang.org/x/net => example.com/fork/net v1.4.5
   golang.org/x/net v1.2.3 => ./fork/net
   golang.org/x/net => ./fork/net
)

非モジュールリポジトリとの互換性

GOPATH からモジュールへのスムーズな移行を確保するために、go コマンドは、go.mod ファイル を追加することによって、モジュールに移行していないリポジトリからモジュール対応モードでパッケージをダウンロードしてビルドできます。

go コマンドがリポジトリから指定されたバージョンのモジュールを直接ダウンロードするとき、モジュールパスのリポジトリ URL を調べ、バージョンをリポジトリ内のリビジョンにマッピングし、そのリビジョンでリポジトリのアーカイブを抽出します。モジュールのパス が リポジトリのルートパス と等しく、リポジトリのルートディレクトリに go.mod ファイルが含まれていない場合、go コマンドは、module ディレクティブ を含む go.mod ファイルをモジュールキャッシュに合成します。それ以外は何も含まれません。合成された go.mod ファイルは、その依存関係のための require ディレクティブ を含まないため、それに依存する他のモジュールは、すべてのビルドで同じバージョンで各依存関係が取得されることを保証するために、追加の require ディレクティブ（// indirect コメント付き）を必要とする場合があります。

go コマンドが プロキシ からモジュールをダウンロードするとき、モジュールの内容の残りの部分とは別に go.mod ファイルをダウンロードします。プロキシは、元のモジュールに合成された go.mod ファイルがない場合、合成された go.mod ファイルを提供することが期待されます。

+互換性のないバージョン

メジャーバージョン 2 以上でリリースされたモジュールは、そのモジュールパスに一致する メジャーバージョンサフィックス を持たなければなりません。たとえば、モジュールが v2.0.0 でリリースされた場合、そのパスには /v2 サフィックスが必要です。これにより、go コマンドは、同じリポジトリで開発されている場合でも、プロジェクトの複数のメジャーバージョンを異なるモジュールとして扱うことができます。

メジャーバージョンサフィックスの要件は、go コマンドにモジュールサポートが追加されたときに導入され、多くのリポジトリはそれ以前にメジャーバージョン 2 以上でリリースをタグ付けしていました。これらのリポジトリとの互換性を維持するために、go コマンドは、go.mod ファイルがないメジャーバージョン 2 以上のバージョンに +incompatible サフィックスを追加します。+incompatible は、バージョンが低いメジャーバージョン番号のバージョンと同じモジュールの一部であることを示します。その結果、go コマンドは、ビルドを壊す可能性があるにもかかわらず、高い +incompatible バージョンに自動的にアップグレードする場合があります。

以下の例の要件を考えてみてください:

require example.com/m v4.1.2+incompatible

バージョン v4.1.2+incompatible は、モジュール example.com/m を提供するリポジトリ内の セマンティックバージョンタグ v4.1.2 を参照します。モジュールはリポジトリのルートディレクトリに存在する必要があります（つまり、リポジトリのルートパス も example.com/m でなければならず、go.mod ファイルは存在してはいけません。モジュールには v1.5.2 のような低いメジャーバージョン番号のバージョンがある可能性があり、go コマンドはそれらのバージョンから v4.1.2+incompatible に自動的にアップグレードする場合があります（アップグレードの動作については、最小バージョン選択 (MVS) を参照してください）。

v2.0.0 でタグ付けされた後にモジュールに移行するリポジトリは、通常、新しいメジャーバージョンをリリースする必要があります。上記の例では、著者は example.com/m/v5 というパスを持つモジュールを作成し、v5.0.0 バージョンをリリースする必要があります。また、著者はモジュール内のパッケージのインポートを example.com/m/v5 プレフィックスを使用するように更新する必要があります。詳細な例については、Go Modules: v2 and Beyond を参照してください。

+incompatible サフィックスはリポジトリのタグに表示されるべきではないことに注意してください。v4.1.2+incompatible のようなタグは無視されます。サフィックスは go コマンドによって使用されるバージョンにのみ表示されます。バージョンとタグの違いについては、バージョンをコミットにマッピング を参照してください。

また、+incompatible サフィックスは 擬似バージョン に表示される場合があります。たとえば、v2.0.1-20200722182040-012345abcdef+incompatible は有効な擬似バージョンである可能性があります。

最小モジュール互換性

メジャーバージョン 2 以上でリリースされたモジュールは、その モジュールパス に メジャーバージョンサフィックス を持つ必要があります。モジュールは、リポジトリ内の メジャーバージョンサブディレクトリ で開発されている場合もあれば、そうでない場合もあります。これは、GOPATH モードでパッケージをビルドする際に、モジュール内のパッケージをインポートするパッケージに影響を与えます。

通常、GOPATH モードでは、パッケージはその リポジトリのルートパス とリポジトリ内のディレクトリを結合したディレクトリに保存されます。たとえば、ルートパスが example.com/repo で、サブディレクトリが sub のリポジトリ内のパッケージは、$GOPATH/src/example.com/repo/sub に保存され、example.com/repo/sub としてインポートされます。

メジャーバージョンサフィックスを持つモジュールの場合、パッケージ example.com/repo/v2/sub がディレクトリ $GOPATH/src/example.com/repo/v2/sub にあることが期待されるかもしれません。これは、モジュールがリポジトリの v2 サブディレクトリで開発されている必要があります。go コマンドはこれをサポートしますが、必須ではありません（バージョンをコミットにマッピングを参照）。

モジュールが メジャーバージョンサブディレクトリ で開発されていない場合、その GOPATH 内のディレクトリにはメジャーバージョンサフィックスが含まれず、そのパッケージはメジャーバージョンサフィックスなしでインポートされる可能性があります。上記の例では、パッケージはディレクトリ $GOPATH/src/example.com/repo/sub に見つかり、example.com/repo/sub としてインポートされます。

これは、モジュールモードと GOPATH モードの両方でビルドされることを意図したパッケージに問題を引き起こします: モジュールモードはサフィックスを必要とし、GOPATH モードは必要としません。

これを修正するために、最小モジュール互換性 が Go 1.11 で追加され、Go 1.9.7 および 1.10.3 にバックポートされました。インポートパスが GOPATH モードでディレクトリに解決されるとき:

• $modpath/$vn/$dir の形式のインポートを解決する場合:
  • $modpath が有効なモジュールパスであり、
  • $vn がメジャーバージョンサフィックスであり、
  • $dir が空である可能性のあるサブディレクトリである場合、
• 次のすべてが真である場合:
  • パッケージ $modpath/$vn/$dir が関連する vendor ディレクトリ に存在しない。
  • go.mod ファイルがインポートファイルと同じディレクトリまたは $GOPATH/src ルートまでの任意の親ディレクトリに存在する。
  • $GOPATH[i]/src/$modpath/$vn/$suffix ディレクトリが存在しない（任意のルート $GOPATH[i] に対して）、
  • ファイル $GOPATH[d]/src/$modpath/go.mod が存在し（任意のルート $GOPATH[d] に対して）モジュールパスを $modpath/$vn として宣言している場合、
• その場合、$modpath/$vn/$dir のインポートは $GOPATH[d]/src/$modpath/$dir のディレクトリに解決されます。

このルールにより、モジュールに移行されたパッケージは、メジャーバージョンサブディレクトリが使用されていない場合でも、GOPATH モードでビルドされるときに、モジュールに移行された他のパッケージをインポートできます。

モジュール対応コマンド

ほとんどの go コマンドは、モジュール対応モード または GOPATH モード で実行できます。モジュール対応モードでは、go コマンドは go.mod ファイルを使用してバージョン付き依存関係を見つけ、通常は モジュールキャッシュ からパッケージをロードし、モジュールが不足している場合はダウンロードします。GOPATH モードでは、go コマンドはモジュールを無視し、vendor ディレクトリ および GOPATH で依存関係を見つけます。

Go 1.16 以降、モジュール対応モードはデフォルトで有効になっており、go.mod ファイルが存在するかどうかに関係なく有効です。以前のバージョンでは、モジュール対応モードは、現在のディレクトリまたは任意の親ディレクトリに go.mod ファイルが存在する場合に有効になっていました。

モジュール対応モードは、GO111MODULE 環境変数で制御でき、on、off、または auto に設定できます。

• GO111MODULE=off の場合、go コマンドは go.mod ファイルを無視し、GOPATH モードで実行されます。
• GO111MODULE=on または未設定の場合、go コマンドは、go.mod ファイルが存在しない場合でもモジュール対応モードで実行されます。すべてのコマンドが go.mod ファイルなしで機能するわけではありません: モジュール外のコマンドを参照してください。
• GO111MODULE=auto の場合、go コマンドは、現在のディレクトリまたは任意の親ディレクトリに go.mod ファイルが存在する場合にモジュール対応モードで実行されます。Go 1.15 およびそれ以前では、これがデフォルトの動作でした。go mod サブコマンドおよび バージョンクエリ を持つ go install は、go.mod ファイルが存在しなくてもモジュール対応モードで実行されます。

モジュール対応モードでは、GOPATH はもはやビルド中のインポートの意味を定義せず、ダウンロードされた依存関係（GOPATH/pkg/mod; モジュールキャッシュを参照）やインストールされたコマンド（GOPATH/bin、GOBIN が設定されていない場合）を保存します。

ビルドコマンド

パッケージに関する情報をロードするすべてのコマンドはモジュール対応です。これには次が含まれます:

• go build
• go fix
• go generate
• go install
• go list
• go run
• go test
• go vet

モジュール対応モードで実行されると、これらのコマンドは go.mod ファイルを使用して、コマンドラインにリストされているインポートパスや Go ソースファイルに書かれているインポートパスを解釈します。これらのコマンドは、すべてのモジュールコマンドに共通する以下のフラグを受け入れます。

• -mod フラグは、go.mod が自動的に更新されるかどうか、および vendor ディレクトリが使用されるかどうかを制御します。
  • -mod=mod は、go コマンドにベンダーディレクトリを無視し、たとえば、インポートされたパッケージが既知のモジュールによって提供されていない場合に go.mod を自動的に更新するように指示します。
  • -mod=readonly は、go コマンドに vendor ディレクトリを無視し、go.mod を更新する必要がある場合にエラーを報告するように指示します。
  • -mod=vendor は、go コマンドに vendor ディレクトリを使用するように指示します。このモードでは、go コマンドはネットワークやモジュールキャッシュを使用しません。
  • デフォルトでは、go.mod の go バージョン が 1.14 以上で、vendor ディレクトリが存在する場合、go コマンドは -mod=vendor が使用されたかのように動作します。そうでない場合、go コマンドは -mod=readonly が使用されたかのように動作します。
  • go get は、このフラグを拒否します。コマンドの目的は依存関係を変更することであり、これは -mod=mod のみが許可されます。
• -modcacherw フラグは、go コマンドにモジュールキャッシュ内に新しいディレクトリを読み書き権限で作成するように指示します。このフラグが一貫して使用されると（通常は環境で GOFLAGS=-modcacherw を設定するか、go env -w GOFLAGS=-modcacherw を実行することによって）、rm -r のようなコマンドでモジュールキャッシュを削除することができ、最初に権限を変更する必要はありません。go clean -modcache コマンドは、-modcacherw が使用されたかどうかにかかわらず、モジュールキャッシュを削除するために使用できます。
• -modfile=file.mod フラグは、go コマンドにモジュールルートディレクトリ内の go.mod の代わりに別のファイルを読み（および書き込む可能性がある）ように指示します。ファイル名は .mod で終わる必要があります。go.mod という名前のファイルは、モジュールルートディレクトリを決定するためにまだ存在する必要がありますが、アクセスされることはありません。-modfile が指定されると、代替の go.sum ファイルも使用されます: そのパスは -modfile フラグから派生し、.mod 拡張子を削除して .sum を追加します。
  

ベンダリング

モジュールを使用する際、go コマンドは通常、モジュールのソースからモジュールをダウンロードしてモジュールキャッシュに保存し、そのダウンロードしたコピーからパッケージを読み込みます。ベンダリングは、古いバージョンの Go との相互運用を可能にするため、またはビルドに使用されるすべてのファイルが単一のファイルツリーに保存されることを保証するために使用されることがあります。

go mod vendor コマンドは、メインモジュールのルートディレクトリに vendor という名前のディレクトリを構築し、メインモジュール内のパッケージをビルドおよびテストするために必要なすべてのパッケージのコピーを含みます。メインモジュールの外部のパッケージのテストによってのみインポートされるパッケージは含まれません。go mod tidy や他のモジュールコマンドと同様に、ignore を除くビルド制約は vendor ディレクトリを構築する際には考慮されません。

go mod vendor は、ベンダリングされたパッケージのリストと、それらがコピーされたモジュールのバージョンを含む vendor/modules.txt ファイルも作成します。ベンダリングが有効になっている場合、このマニフェストは go list -m や go version -m によって報告されるモジュールバージョン情報のソースとして使用されます。go コマンドが vendor/modules.txt を読み込むと、モジュールバージョンが go.mod と一致しているかどうかを確認します。go.mod が vendor/modules.txt が生成されて以来変更されている場合、go コマンドはエラーを報告します。go mod vendor を再度実行して vendor ディレクトリを更新する必要があります。

メインモジュールのルートディレクトリに vendor ディレクトリが存在する場合、メインモジュールの go バージョン が 1.14 以上であれば、自動的に使用されます。ベンダリングを明示的に有効にするには、go コマンドを -mod=vendor フラグと共に呼び出します。ベンダリングを無効にするには、-mod=readonly または -mod=mod フラグを使用します。

ベンダリングが有効になっている場合、go build のようなビルドコマンドは、ネットワークやローカルモジュールキャッシュにアクセスする代わりに vendor ディレクトリからパッケージを読み込みます。go list -m コマンドは、go.mod にリストされたモジュールに関する情報のみを印刷します。[go mod] コマンド（go mod download や go mod tidy など）は、ベンダリングが有効になっていても異なる動作をせず、モジュールをダウンロードし、モジュールキャッシュにアクセスします。go get も、ベンダリングが有効になっていても異なる動作をしません。

GOPATH モードでのベンダリング とは異なり、go コマンドはメインモジュールのルートディレクトリ以外の場所にあるベンダーディレクトリを無視します。さらに、他のモジュールのベンダーディレクトリは使用されないため、go コマンドは モジュール ZIP ファイル をビルドする際にベンダーディレクトリを含めません（ただし、既知のバグ #31562 および #37397 を参照）。

go get

使用法:

go get [-d] [-t] [-u] [ビルドフラグ] [パッケージ]

例:

# 特定のモジュールをアップグレードします。
$ go get golang.org/x/net
# メインモジュール内のパッケージによってインポートされるパッケージを提供するモジュールをアップグレードします。
$ go get -u ./...
# 特定のバージョンのモジュールにアップグレードまたはダウングレードします。
$ go get golang.org/x/text@v0.3.2
# モジュールのマスターブランチのコミットに更新します。
$ go get golang.org/x/text@master
# モジュールへの依存関係を削除し、それを必要とするモジュールをダウングレードします。
# それを必要としないバージョンに。
$ go get golang.org/x/text@none
# メインモジュールの最小必要 Go バージョンをアップグレードします。
$ go get go
# 最小 Go バージョンをそのままにして、推奨される Go ツールチェーンをアップグレードします。
$ go get toolchain
# 推奨される Go ツールチェーンの最新のパッチリリースにアップグレードします。
$ go get toolchain@patch

go get コマンドは、メインモジュール の go.mod ファイル 内のモジュール依存関係を更新し、次にコマンドラインにリストされたパッケージをビルドおよびインストールします。

最初のステップは、どのモジュールを更新するかを決定することです。go get は、パッケージ、パッケージパターン、およびモジュールパスのリストを引数として受け取ります。パッケージ引数が指定されている場合、go get はそのパッケージを提供するモジュールを更新します。パッケージパターンが指定されている場合（たとえば、all または ... ワイルドカードを含むパス）、go get はパターンをパッケージのセットに展開し、次にそのパッケージを提供するモジュールを更新します。引数がモジュールを指定しているがパッケージを指定していない場合（たとえば、モジュール golang.org/x/net のルートディレクトリにパッケージがない場合）、go get はモジュールを更新しますが、パッケージはビルドしません。引数が指定されていない場合、go get は . が指定されたかのように動作します（現在のディレクトリのパッケージ）；これは、-u フラグと組み合わせて、インポートされたパッケージを提供するモジュールを更新するために使用できます。

各引数には、go get golang.org/x/[email protected] のように、希望するバージョンを示す バージョンクエリサフィックス を含めることができます。バージョンクエリサフィックスは、@ シンボルの後に バージョンクエリ が続くもので、特定のバージョン（v0.3.0）、バージョンプレフィックス（v0.3）、ブランチまたはタグ名（master）、リビジョン（1234abcd）、または特別なクエリのいずれか（latest、upgrade、patch、none）を示すことができます。バージョンが指定されていない場合、go get は @upgrade クエリを使用します。

go get が引数を特定のモジュールとバージョンに解決した後、go get はメインモジュールの go.mod ファイル内の require ディレクティブ を追加、変更、または削除して、将来的にモジュールが希望するバージョンのままであることを保証します。go.mod ファイル内の必要なバージョンは 最小バージョン であり、新しい依存関係が追加されると自動的に増加する可能性があります。バージョンがどのように選択され、モジュール対応コマンドによって競合がどのように解決されるかについての詳細は、最小バージョン選択 (MVS) を参照してください。

コマンドラインに名前が付けられたモジュールが追加、アップグレード、またはダウングレードされると、他のモジュールもアップグレードされる場合があります。たとえば、モジュール example.com/a がバージョン v1.5.0 にアップグレードされ、そのバージョンがモジュール example.com/b をバージョン v1.2.0 で要求する場合、example.com/b が現在バージョン v1.1.0 で要求されている場合、go get example.com/[email protected] も example.com/b を v1.2.0 にアップグレードします。

コマンドラインに名前が付けられたモジュールがダウングレードまたは削除されると、他のモジュールもダウングレードされる場合があります。上記の例を続けると、モジュール example.com/b が v1.1.0 にダウングレードされると、モジュール example.com/a も example.com/b をバージョン v1.1.0 以下で要求するバージョンにダウングレードされます。

モジュール要件は、バージョンサフィックス @none を使用して削除できます。これは特別な種類のダウングレードです。削除されたモジュールに依存するモジュールは、必要に応じてダウングレードまたは削除されます。モジュール要件は、メインモジュール内のパッケージによってインポートされているパッケージが1つ以上ある場合でも削除できます。この場合、次のビルドコマンドは新しいモジュール要件を追加する可能性があります。

モジュールが異なる2つのバージョンで必要な場合（コマンドライン引数で明示的に指定されるか、アップグレードやダウングレードを満たすため）、go get はエラーを報告します。

go get が新しいバージョンセットを選択した後、go get は新しく選択されたモジュールバージョンや、コマンドラインに名前が付けられたパッケージを提供するモジュールが 取り消された または 非推奨 であるかどうかを確認します。go get は、見つかった取り消されたバージョンや非推奨モジュールごとに警告を印刷します。go list -m -u all を使用して、すべての依存関係における取り消しや非推奨を確認できます。

go get が go.mod ファイルを更新した後、コマンドラインに名前が付けられたパッケージをビルドします。実行可能ファイルは、GOBIN 環境変数で指定されたディレクトリにインストールされ、$GOPATH/bin または $HOME/go/bin が設定されていない場合はデフォルトで $GOPATH/bin または $HOME/go/bin にインストールされます。

go get は次のフラグをサポートします:

• -d フラグは、go get にパッケージをビルドまたはインストールしないように指示します。-d が使用されると、go get は go.mod 内の依存関係のみを管理します。go get を -d なしで使用してパッケージをビルドおよびインストールすることは非推奨です（Go 1.17 以降）。Go 1.18 では、-d は常に有効になります。
• -u フラグは、go get にコマンドラインに名前が付けられたパッケージによって直接または間接的にインポートされるパッケージを提供するモジュールをアップグレードするように指示します。-u によって選択された各モジュールは、すでに高いバージョン（プレリリース）で要求されていない限り、最新のバージョンにアップグレードされます。
• -u=patch フラグ（-u patch ではない）も go get に依存関係をアップグレードするように指示しますが、go get は各依存関係を最新のパッチバージョンにアップグレードします（@patch バージョンクエリに似ています）。
• -t フラグは、コマンドラインに名前が付けられたパッケージのテストをビルドするために必要なモジュールを考慮するように go get に指示します。-t と -u を一緒に使用すると、go get はテスト依存関係も更新します。
• -insecure フラグはもはや使用されるべきではありません。これは、go get にカスタムインポートパスを解決させ、HTTP などの安全でないスキームを使用してリポジトリやモジュールプロキシから取得させることを許可します。GOINSECURE 環境変数 は、より細かい制御を提供し、代わりに使用されるべきです。

Go 1.16 以降、go install はプログラムのビルドとインストールに推奨されるコマンドです。バージョンサフィックス（@latest や @v1.4.6 のような）を使用すると、go install はモジュール対応モードでパッケージをビルドし、現在のディレクトリまたは親ディレクトリに go.mod ファイルが存在する場合は無視します。

go get は go.mod 内の要件の管理により焦点を当てています。-d フラグは非推奨であり、Go 1.18 では常に有効になります。

go install

使用法:

go install [ビルドフラグ] [パッケージ]

例:

# プログラムの最新バージョンをインストールします。
# 現在のディレクトリの go.mod を無視して。
$ go install golang.org/x/tools/gopls@latest
# プログラムの特定のバージョンをインストールします。
$ go install golang.org/x/tools/gopls@v0.6.4
# 現在のディレクトリのモジュールによって選択されたバージョンのプログラムをインストールします。
$ go install golang.org/x/tools/gopls
# ディレクトリ内のすべてのプログラムをインストールします。
$ go install ./cmd/...

go install コマンドは、コマンドラインで指定されたパスによって名前付けされたパッケージをビルドおよびインストールします。実行可能ファイル（main パッケージ）は、GOBIN 環境変数で指定されたディレクトリにインストールされ、$GOPATH/bin または $HOME/go/bin が設定されていない場合はデフォルトで $GOPATH/bin または $HOME/go/bin にインストールされます。$GOROOT 内の実行可能ファイルは $GOROOT/bin または $GOTOOLDIR にインストールされ、$GOBIN にはインストールされません。非実行可能パッケージはビルドされてキャッシュされますが、インストールされません。

Go 1.16 以降、引数にバージョンサフィックス（@latest や @v1.0.0 のような）がある場合、go install はモジュール対応モードでパッケージをビルドし、現在のディレクトリまたは親ディレクトリに go.mod ファイルが存在する場合は無視します。これは、メインモジュールの依存関係に影響を与えずに実行可能ファイルをインストールするのに便利です。

どのモジュールバージョンがビルドに使用されるかについての曖昧さを排除するために、引数は次の制約を満たす必要があります:

• 引数はパッケージパスまたはパッケージパターン（「...」ワイルドカードを含む）でなければなりません。標準パッケージ（fmt）、メタパターン（std、cmd、all）、または相対または絶対ファイルパスであってはなりません。
• すべての引数は同じバージンサフィックスを持たなければなりません。異なるクエリは許可されず、同じバージョンを参照していても許可されません。
• すべての引数は同じバージョンの同じモジュール内のパッケージを参照しなければなりません。
• パッケージパス引数は main パッケージを参照しなければなりません。パターン引数は main パッケージにのみ一致します。
• どのモジュールも メインモジュール と見なされません。
  • コマンドラインで名前が付けられたパッケージを含むモジュールに go.mod ファイルがある場合、それはメインモジュールである場合に異なる解釈を引き起こすディレクティブ（replace および exclude）を含んではなりません。
  • モジュールは自分自身のより高いバージョンを要求してはなりません。
  • ベンダーディレクトリはどのモジュールでも使用されません。（ベンダーディレクトリは モジュール ZIP ファイル に含まれないため、go install はそれらをダウンロードしません。）

バージョンクエリ のサポートされているバージョンクエリ構文を参照してください。Go 1.15 およびそれ以前のバージョンでは、go install でバージョンクエリを使用することはサポートされていませんでした。

引数にバージョンサフィックスがない場合、go install はモジュール対応モードまたは GOPATH モードで実行される可能性があり、GO111MODULE 環境変数と go.mod ファイルの存在に依存します。モジュール対応モードが有効になっている場合、go install はメインモジュールのコンテキストで実行され、これはインストールされるパッケージを含むモジュールとは異なる場合があります。

go list -m

使用法:

go list -m [-u] [-retracted] [-versions] [list flags] [modules]

例:

$ go list -m all
$ go list -m -versions example.com/m
$ go list -m -json example.com/m@latest

-m フラグは、go list にモジュールをリストするように指示します。このモードでは、go list への引数はモジュール、モジュールパターン（... ワイルドカードを含む）、バージョンクエリ、または特別なパターン all であり、これは ビルドリスト 内のすべてのモジュールに一致します。引数が指定されていない場合、メインモジュール がリストされます。

モジュールをリストする際、-f フラグは依然として Go 構造体に適用されるフォーマットテンプレートを指定しますが、今は Module 構造体です:

type Module struct {
   Path       string        // module path
   Version    string        // module version
   Versions   []string      // available module versions
   Replace    *Module       // replaced by this module
   Time       *time.Time    // time version was created
   Update     *Module       // available update (with -u)
   Main       bool          // is this the main module?
   Indirect   bool          // module is only indirectly needed by main module
   Dir        string        // directory holding local copy of files, if any
   GoMod      string        // path to go.mod file describing module, if any
   GoVersion  string        // go version used in module
   Retracted  []string      // retraction information, if any (with -retracted or -u)
   Deprecated string        // deprecation message, if any (with -u)
   Error      *ModuleError  // error loading module
}
type ModuleError struct {
   Err string // the error itself
}

デフォルトの出力は、モジュールパスを印刷し、その後にバージョンや置き換えに関する情報を印刷します。たとえば、go list -m all は次のように印刷されるかもしれません:

example.com/main/module
golang.org/x/net v0.1.0
golang.org/x/text v0.3.0 => /tmp/text
rsc.io/pdf v0.1.1

Module 構造体には、この出力行をフォーマットする String メソッドがあり、デフォルトのフォーマットは -f '{{.String}}' と同等です。

モジュールが置き換えられた場合、その Replace フィールドは置き換えモジュールを説明し、Dir フィールドは置き換えモジュールのソースコードが存在する場合はそれに設定されます。（つまり、Replace が非 nil の場合、Dir は Replace.Dir に設定され、置き換えられたソースコードにはアクセスできません。）

-u フラグは、利用可能なアップグレードに関する情報を追加します。特定のモジュールの最新バージョンが現在のバージョンより新しい場合、list -u はモジュールの Update フィールドに新しいモジュールに関する情報を設定します。list -u は、現在選択されているバージョンが 取り消された かどうか、またモジュールが 非推奨 かどうかも印刷します。モジュールの String メソッドは、現在のバージョンの後に新しいバージョンを角括弧でフォーマットすることによって、利用可能なアップグレードを示します。たとえば、go list -m -u all は次のように印刷されるかもしれません:

example.com/main/module
golang.org/x/old v1.9.9 (deprecated)
golang.org/x/net v0.1.0 (retracted) [v0.2.0]
golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 [v0.1.2]

（ツールの場合、go list -m -u -json all は解析するのにより便利かもしれません。）

-versions フラグは、list にモジュールの Versions フィールドを、そのモジュールのすべての既知のバージョンのリストに設定させ、セマンティックバージョニングに従って、最低から最高までの順に並べます。このフラグは、デフォルトの出力形式をモジュールパスの後にスペース区切りのバージョンリストを表示するように変更します。取り消されたバージョンは、このリストから省略されますが、-retracted フラグが指定されている場合は除外されません。

-retracted フラグは、list に -versions フラグで印刷されたリストに取り消されたバージョンを表示させ、バージョンクエリ を解決する際に取り消されたバージョンを考慮させます。たとえば、go list -m -retracted example.com/m@latest は、example.com/m モジュールの最高のリリースまたはプレリリースバージョンを表示します。たとえそのバージョンが取り消されていても、retract ディレクティブ と 非推奨 はこのバージョンの go.mod ファイルから読み込まれます。-retracted フラグは Go 1.16 で追加されました。

テンプレート関数 module は、モジュールパスまたはクエリでなければならない単一の文字列引数を受け取り、指定されたモジュールを Module 構造体として返します。エラーが発生した場合、結果は非 nil の Module フィールドを持つ Module 構造体になります。

go mod download

使用法:

go mod download [-x] [-json] [-reuse=old.json] [modules]

例:

$ go mod download
$ go mod download golang.org/x/mod@v0.2.0

go mod download コマンドは、指定されたモジュールを モジュールキャッシュ にダウンロードします。引数は、メインモジュールの依存関係を選択するモジュールパスまたはモジュールパターン、または path@version の形式のバージョンクエリであることができます。引数が指定されていない場合、download は メインモジュール のすべての依存関係に適用されます。

go コマンドは、通常の実行中に必要に応じてモジュールを自動的にダウンロードします。go mod download コマンドは、主にモジュールキャッシュを事前に埋めるためや、モジュールプロキシ によって提供されるデータを読み込むために便利です。

デフォルトでは、download は標準出力に何も書き込みません。進行状況メッセージとエラーは標準エラーに印刷されます。

-json フラグは、download にダウンロードされた各モジュール（または失敗）を説明する JSON オブジェクトのシーケンスを標準出力に印刷させます。これは次の Go 構造体に対応します:

type Module struct {
   Path     string // module path
   Query    string // version query corresponding to this version
   Version  string // module version
   Error    string // error loading module
   Info     string // absolute path to cached .info file
   GoMod    string // absolute path to cached .mod file
   Zip      string // absolute path to cached .zip file
   Dir      string // absolute path to cached source root directory
   Sum      string // checksum for path, version (as in go.sum)
   GoModSum string // checksum for go.mod (as in go.sum)
   Origin   any    // provenance of module
   Reuse    bool   // reuse of old module info is safe
}

-x フラグは、download に download が実行するコマンドを標準エラーに印刷させます。

-reuse フラグは、以前の ‘go mod download -json’ 呼び出しの JSON 出力を含むファイルの名前を受け入れます。go コマンドは、このファイルを使用して、モジュールが前回の呼び出し以来変更されていないことを判断し、再ダウンロードを避けることができます。再ダウンロードされないモジュールは、新しい出力で Reuse フィールドを true に設定することによってマークされます。通常、モジュールキャッシュはこの種の再利用を自動的に提供しますが、-reuse フラグはモジュールキャッシュを保持しないシステムで便利です。

go mod edit

使用法:

go mod edit [編集フラグ] [-fmt|-print|-json] [go.mod]

例:

# 置き換えディレクティブを追加します。
$ go mod edit -replace example.com/a@v1.0.0=./a
# 置き換えディレクティブを削除します。
$ go mod edit -dropreplace example.com/a@v1.0.0
# Go バージョンを設定し、要件を追加し、ファイルを印刷します。
# ディスクに書き込むのではなく。
$ go mod edit -go=1.14 -require=example.com/m@v1.0.0 -print
# go.mod ファイルをフォーマットします。
$ go mod edit -fmt
# 異なる .mod ファイルをフォーマットして印刷します。
$ go mod edit -print tools.mod
# go.mod ファイルの JSON 表現を印刷します。
$ go mod edit -json

go mod edit コマンドは、主にツールやスクリプトによって使用される go.mod ファイルを編集およびフォーマットするためのコマンドラインインターフェースを提供します。go mod edit は1つの go.mod ファイルのみを読み込み、他のモジュールに関する情報を調べません。デフォルトでは、go mod edit はメインモジュールの go.mod ファイルを読み書きしますが、編集フラグの後に異なるターゲットファイルを指定できます。

編集フラグは、一連の編集操作を指定します。

• -module フラグは、モジュールのパス（go.mod ファイルのモジュール行）を変更します。
• -go=version フラグは、期待される Go 言語のバージョンを設定します。
• -require=path@version および -droprequire=path フラグは、指定されたモジュールパスとバージョンに対する要件を追加および削除します。-require は、path に対する既存の要件を上書きします。これらのフラグは、モジュールグラフを理解するツール向けです。ユーザーは、他の go.mod 調整を必要に応じて行う go get path@version または go get path@none を優先すべきです。 go get を参照してください。
• -exclude=path@version および -dropexclude=path@version フラグは、指定されたモジュールパスとバージョンに対する除外を追加および削除します。-exclude=path@version は、すでにその除外が存在する場合は無視されます。
• -replace=old[@v]=new[@v] フラグは、指定されたモジュールパスとバージョンのペアの置き換えを追加します。@v が old@v に省略されている場合、左側にバージョンのない置き換えが追加され、古いモジュールパスのすべてのバージョンに適用されます。@v が new@v に省略されている場合、新しいパスはローカルモジュールのルートディレクトリでなければならず、モジュールパスではありません。-replace は、old[@v] に対する冗長な置き換えを上書きするため、@v を省略すると特定のバージョンの置き換えが削除されます。
• -dropreplace=old[@v] フラグは、指定されたモジュールパスとバージョンのペアの置き換えを削除します。@v が提供されている場合、指定されたバージョンの置き換えが削除されます。左側にバージョンのない既存の置き換えは、モジュールを置き換える可能性があります。@v が省略されている場合、バージョンのない置き換えが削除されます。
• -retract=version および -dropretract=version フラグは、指定されたバージョンに対する取り消しを追加および削除します。これは単一のバージョン（v1.2.3 のような）または範囲（[v1.1.0,v1.2.0] のような）である可能性があります。-retract フラグは、retract ディレクティブに対する理由コメントを追加することはできません。理由コメントは推奨されており、go list -m -u や他のコマンドによって表示される可能性があります。

編集フラグは繰り返し使用できます。変更は指定された順序で適用されます。

go mod edit には、出力を制御する追加のフラグがあります。

• -fmt フラグは、他の変更を行うことなく go.mod ファイルを再フォーマットします。この再フォーマットは、go.mod ファイルを使用または再書き込みする他の変更によっても暗黙的に行われます。このフラグが必要なのは、go mod edit -fmt のように他のフラグが指定されていない場合のみです。
• -print フラグは、最終的な go.mod をテキスト形式で印刷し、ディスクに書き戻すのではなくします。
• -json フラグは、最終的な go.mod を JSON 形式で印刷し、テキスト形式でディスクに書き戻すのではなくします。JSON 出力は次の Go 型に対応します:

type Module struct {
   Path    string
   Version string
}
type GoMod struct {
   Module  ModPath
   Go      string
   Require []Require
   Exclude []Module
   Replace []Replace
   Retract []Retract
}
type ModPath struct {
   Path       string
   Deprecated string
}
type Require struct {
   Path     string
   Version  string
   Indirect bool
}
type Replace struct {
   Old Module
   New Module
}
type Retract struct {
   Low       string
   High      string
   Rationale string
}

これは、go.mod ファイル自体を説明するものであり、間接的に参照される他のモジュールについては説明しません。ビルドに利用可能なモジュールの完全なセットについては、go list -m -json all を使用してください。go list -m を参照してください。

たとえば、ツールは go.mod ファイルをデータ構造として取得し、go mod edit -json の出力を解析して変更を加え、go mod edit を -require、-exclude などで呼び出すことができます。

ツールは、golang.org/x/mod/modfile パッケージを使用して、go.mod ファイルを解析、編集、フォーマットすることもできます。

go mod graph

使用法:

go mod graph [-go=version]

go mod graph コマンドは、モジュール要件グラフ（置き換えが適用されたもの）をテキスト形式で印刷します。たとえば:

example.com/main example.com/a@v1.1.0
example.com/main example.com/b@v1.2.0
example.com/a@v1.1.0 example.com/b@v1.1.1
example.com/a@v1.1.0 example.com/c@v1.3.0
example.com/b@v1.1.0 example.com/c@v1.1.0
example.com/b@v1.2.0 example.com/c@v1.2.0

モジュールグラフの各頂点は、モジュールの特定のバージョンを表します。グラフの各エッジは、依存関係の最小バージョンに対する要件を表します。

go mod graph は、グラフのエッジを1行ずつ印刷します。各行には、スペースで区切られた2つのフィールドがあります: モジュールバージョンとその依存関係の1つ。各モジュールバージョンは、path@version の形式の文字列として識別されます。メインモジュールには @version サフィックスはなく、バージョンはありません。

-go フラグは、go mod graph に指定された Go バージョンによって読み込まれたモジュールグラフを報告させます。go ディレクティブが go.mod ファイルに指定されているバージョンではなく、go mod graph に指定されたバージョンによって読み込まれたモジュールグラフを報告します。

最小バージョン選択 (MVS) についての詳細は、バージョンがどのように選択されるかを参照してください。選択されたバージョンを印刷するには go list -m を、モジュールがなぜ必要なのかを理解するには go mod why を参照してください。

go mod init

使用法:

go mod init [module-path]

例:

go mod init
go mod init example.com/m

go mod init コマンドは、現在のディレクトリに新しい go.mod ファイルを初期化して書き込み、実質的に現在のディレクトリにルートを持つ新しいモジュールを作成します。go.mod ファイルは既に存在してはいけません。

init は、オプションの引数として新しいモジュールの モジュールパス を受け取ります。モジュールパスの選択に関する指示については Module paths を参照してください。モジュールパス引数が省略された場合、init は .go ファイル、ベンダリングツールの設定ファイル、および現在のディレクトリ（GOPATH にいる場合）を使用してモジュールパスを推測しようとします。

ベンダリングツールの設定ファイルが存在する場合、init はそこからモジュール要件をインポートしようとします。init は次の設定ファイルをサポートしています。

• GLOCKFILE (Glock)
• Godeps/Godeps.json (Godeps)
• Gopkg.lock (dep)
• dependencies.tsv (godeps)
• glide.lock (glide)
• vendor.conf (trash)
• vendor.yml (govend)
• vendor/manifest (gvt)
• vendor/vendor.json (govendor)

ベンダリングツールの設定ファイルは、常に完全に翻訳できるわけではありません。たとえば、同じリポジトリ内の複数のパッケージが異なるバージョンでインポートされ、リポジトリにモジュールが1つしか含まれていない場合、インポートされた go.mod は1つのバージョンでのみモジュールを要求できます。すべてのバージョンを確認するには、go list -m all を実行し、build list を確認し、go mod tidy を実行して不足している要件を追加し、未使用の要件を削除することをお勧めします。

go mod tidy

使用法:

go mod tidy [-e] [-v] [-go=version] [-compat=version]

go mod tidy は、go.mod ファイルがモジュール内のソースコードと一致することを保証します。現在のモジュールのパッケージと依存関係をビルドするために必要な不足しているモジュール要件を追加し、関連するパッケージを提供しないモジュールの要件を削除します。また、go.sum に不足しているエントリを追加し、不必要なエントリを削除します。

-e フラグ（Go 1.16 で追加）は、go mod tidy がパッケージの読み込み中に発生したエラーにもかかわらず処理を続行しようとすることを引き起こします。

-v フラグは、go mod tidy が削除されたモジュールに関する情報を標準エラーに出力するようにします。

go mod tidy は、main module 内のすべてのパッケージと、それらがインポートするすべてのパッケージを再帰的に読み込むことによって機能します。これには、テストによってインポートされたパッケージ（他のモジュール内のテストを含む）が含まれます。go mod tidy は、すべてのビルドタグが有効であるかのように動作するため、プラットフォーム固有のソースファイルやカスタムビルドタグを必要とするファイルも考慮されます。通常はビルドされないソースファイルであってもです。ただし、1つの例外があります：ignore ビルドタグは有効になっていないため、ビルド制約 // +build ignore を持つファイルは考慮されません。go mod tidy は、testdata という名前のディレクトリや、. または _ で始まる名前のパッケージをメインモジュール内で考慮しません。これらのパッケージが他のパッケージによって明示的にインポートされている場合を除きます。

go mod tidy がこのパッケージセットを読み込んだ後、1つ以上のパッケージを提供する各モジュールが、メインモジュールの go.mod ファイルに require ディレクティブを持っているか、メインモジュールが go 1.16 またはそれ以下の場合は、他の必須モジュールによって要求されていることを確認します。go mod tidy は、各不足しているモジュールの最新バージョンに対する要件を追加します（latest バージョンの定義については Version queries を参照してください）。go mod tidy は、上記のセットでパッケージを提供しないモジュールの require ディレクティブを削除します。

go mod tidy は、// indirect ディレクティブに対して require コメントを追加または削除することもあります。// indirect コメントは、メインモジュール内のパッケージによってインポートされていないパッケージを提供しないモジュールを示します。（require ディレクティブについては、// indirect 依存関係とコメントが追加されるタイミングの詳細を参照してください。）

-go フラグが設定されている場合、go mod tidy は指定されたバージョンに go ディレクティブを更新し、module graph pruning と lazy module loading を有効または無効にします（必要に応じて間接的な要件を追加または削除します）。

デフォルトでは、go mod tidy は、go ディレクティブで示されたバージョンの直前の Go バージョンによってモジュールグラフが読み込まれたときに、モジュールの selected versions が変更されないことを確認します。互換性のためにチェックされるバージョンは、-compat フラグを介して明示的に指定することもできます。

go mod vendor

使用法:

go mod vendor [-e] [-v] [-o]

go mod vendor コマンドは、main module のルートディレクトリに vendor という名前のディレクトリを構築し、メインモジュール内のパッケージのビルドとテストをサポートするために必要なすべてのパッケージのコピーを含みます。メインモジュールの外部のパッケージのテストによってのみインポートされるパッケージは含まれません。go mod tidy や他のモジュールコマンドと同様に、ignore を除く build constraints は、vendor ディレクトリを構築する際には考慮されません。

ベンダリングが有効になっている場合、go コマンドは、モジュールキャッシュにモジュールをダウンロードするのではなく、vendor ディレクトリからパッケージを読み込みます。詳細については Vendoring を参照してください。

go mod vendor は、ベンダリングされたパッケージのリストと、それらがコピーされたモジュールのバージョンを含む vendor/modules.txt ファイルも作成します。ベンダリングが有効になっている場合、このマニフェストは、go list -m および go version -m によって報告されるモジュールバージョン情報のソースとして使用されます。go コマンドが vendor/modules.txt を読み込むと、モジュールバージョンが go.mod と一致していることを確認します。go.mod が vendor/modules.txt が生成された後に変更された場合、go mod vendor を再度実行する必要があります。

go mod vendor は、再構築する前に vendor ディレクトリが存在する場合は削除します。ローカルの変更はベンダリングされたパッケージに対して行うべきではありません。go コマンドは、vendor ディレクトリ内のパッケージが変更されていないことを確認しませんが、vendor ディレクトリの整合性を確認するには go mod vendor を実行し、変更が行われていないことを確認できます。

-e フラグ（Go 1.16 で追加）は、go mod vendor がパッケージの読み込み中に発生したエラーにもかかわらず処理を続行しようとします。

-v フラグは、go mod vendor がベンダリングされたモジュールとパッケージの名前を標準エラーに出力するようにします。

-o フラグ（Go 1.18 で追加）は、go mod vendor が指定されたディレクトリにベンダーツリーを出力するようにします。引数は絶対パスまたはモジュールルートに対する相対パスのいずれかです。

go mod verify

使用法:

go mod verify

go mod verify は、main module の依存関係が module cache に保存されている間に変更されていないことを確認します。このチェックを行うために、go mod verify は各ダウンロードされたモジュールの .zip ファイル と抽出されたディレクトリのハッシュを計算し、それらのハッシュをモジュールが最初にダウンロードされたときに記録されたハッシュと比較します。go mod verify は、build list 内の各モジュールをチェックします（これは go list -m all で印刷できます）。

すべてのモジュールが変更されていない場合、go mod verify は「すべてのモジュールが確認されました」と印刷します。そうでない場合、変更されたモジュールを報告し、非ゼロのステータスで終了します。

すべてのモジュール対応コマンドは、メインモジュールの go.sum ファイル内のハッシュが、モジュールキャッシュにダウンロードされたモジュールのために記録されたハッシュと一致することを確認します。go.sum からハッシュが欠落している場合（たとえば、モジュールが初めて使用されるため）、go コマンドは checksum database を使用してそのハッシュを確認します（ただし、モジュールパスが GOPRIVATE または GONOSUMDB に一致する場合を除きます）。Authenticating modules の詳細を参照してください。

対照的に、go mod verify は、モジュール .zip ファイルとその抽出されたディレクトリが、最初にダウンロードされたときにモジュールキャッシュに記録されたハッシュと一致するハッシュを持っていることを確認します。これは、モジュールがダウンロードされて確認された後に、モジュールキャッシュ内のファイルの変更を検出するのに役立ちます。go mod verify は、キャッシュにないモジュールのコンテンツをダウンロードせず、go.sum ファイルを使用してモジュールコンテンツを確認することもありません。ただし、go mod verify は、minimal version selection を実行するために go.mod ファイルをダウンロードする場合があります。これらのファイルを確認するために go.sum を使用し、欠落しているハッシュのために go.sum エントリを追加することがあります。

go mod why

使用法:

go mod why [-m] [-vendor] packages...

go mod why は、メインモジュールからリストされた各パッケージへのインポートグラフの最短経路を示します。

出力は、コマンドラインで指定された各パッケージまたはモジュールのためのスタンザのシーケンスであり、空白行で区切られています。各スタンザは、# で始まるコメント行で始まり、ターゲットパッケージまたはモジュールを示します。続く行は、インポートグラフを通るパスを示し、1行に1つのパッケージが表示されます。パッケージまたはモジュールがメインモジュールから参照されていない場合、スタンザはその事実を示す単一の括弧付きの注釈を表示します。

例えば:

$ go mod why golang.org/x/text/language golang.org/x/text/encoding
# golang.org/x/text/language
rsc.io/quote
rsc.io/sampler
golang.org/x/text/language
# golang.org/x/text/encoding
(main module does not need package golang.org/x/text/encoding)

-m フラグは、go mod why がその引数をモジュールのリストとして扱うようにします。go mod why は、各モジュール内の任意のパッケージへのパスを印刷します。-m が使用されている場合でも、go mod why はパッケージグラフをクエリし、go mod graph によって印刷されたモジュールグラフではありません。

-vendor フラグは、go mod why がメインモジュールの外部のパッケージのテスト内のインポートを無視するようにします（go mod vendor と同様です）。デフォルトでは、go mod why は all パターンに一致するパッケージのグラフを考慮します。このフラグは、go 1.16 以上を宣言するモジュールでは Go 1.16 以降に効果がありません（go ディレクティブを go.mod に使用している場合）、all の意味が go mod vendor に一致するパッケージのセットに変更されたためです。

go version -m

使用法:

go version [-m] [-v] [file ...]

例:

# Print Go version used to build go.
$ go version
# Print Go version used to build a specific executable.
$ go version ~/go/bin/gopls
# Print Go version and module versions used to build a specific executable.
$ go version -m ~/go/bin/gopls
# Print Go version and module versions used to build executables in a directory.
$ go version -m ~/go/bin/

go version は、コマンドラインで指定された各実行可能ファイルをビルドするために使用された Go バージョンを報告します。

コマンドラインでファイルが指定されていない場合、go version は自分自身のバージョン情報を印刷します。

ディレクトリが指定された場合、go version はそのディレクトリを再帰的に走査し、認識された Go バイナリを探してそのバージョンを報告します。デフォルトでは、go version はディレクトリスキャン中に見つかった未認識のファイルを報告しません。-v フラグは、未認識のファイルを報告するようにします。

-m フラグは、go version が各実行可能ファイルの埋め込まれたモジュールバージョン情報を印刷するようにします。各実行可能ファイルについて、go version -m は以下のようなタブ区切りの列を持つテーブルを印刷します。

$ go version -m ~/go/bin/goimports
/home/jrgopher/go/bin/goimports: go1.14.3
   path    golang.org/x/tools/cmd/goimports
   mod     golang.org/x/tools      v0.0.0-20200518203908-8018eb2c26ba      h1:0Lcy64USfQQL6GAJma8BdHCgeofcchQj+Z7j0SXYAzU=
   dep     golang.org/x/mod        v0.2.0          h1:KU7oHjnv3XNWfa5COkzUifxZmxp1TyI7ImMXqFxLwvQ=
   dep     golang.org/x/xerrors    v0.0.0-20191204190536-9bdfabe68543      h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=

テーブルの形式は将来的に変更される可能性があります。同じ情報は runtime/debug.ReadBuildInfo からも取得できます。

テーブルの各行の意味は、最初の列の単語によって決まります。

• path: 実行可能ファイルをビルドするために使用された main パッケージのパス。
• mod: main パッケージを含むモジュール。列はモジュールパス、バージョン、および合計です。 main module はバージョン (devel) を持ち、合計はありません。
• dep: 実行可能ファイルにリンクされた1つ以上のパッケージを提供するモジュール。mod と同じ形式です。
• =>: 前の行のモジュールの replacement です。置き換えがローカルディレクトリの場合、ディレクトリパスのみがリストされます（バージョンや合計はありません）。置き換えがモジュールバージョンの場合、mod および dep と同様に、パス、バージョン、および合計がリストされます。置き換えられたモジュールには合計はありません。
  

go clean -modcache

使用法:

go clean [-modcache]

-modcache フラグは、go clean がモジュールキャッシュ全体を削除するようにします。これには、バージョン付き依存関係の解凍されたソースコードが含まれます。

これは通常、モジュールキャッシュを削除する最良の方法です。デフォルトでは、モジュールキャッシュ内のほとんどのファイルとディレクトリは読み取り専用であり、テストやエディタが認証された後にファイルを意図せず変更するのを防ぎます。残念ながら、これにより、rm -r のようなコマンドが失敗します。ファイルは親ディレクトリを最初に書き込み可能にしない限り削除できません。

-modcacherw フラグ（go build および他のモジュール対応コマンドによって受け入れられる）は、モジュールキャッシュ内の新しいディレクトリを読み書き可能にします。-modcacherw をすべてのモジュール対応コマンドに渡すには、GOFLAGS 変数に追加します。GOFLAGS は環境内で設定するか、go env -w を使用して設定できます。たとえば、以下のコマンドはそれを永続的に設定します：

go env -w GOFLAGS=-modcacherw

-modcacherw は注意して使用する必要があります。開発者はモジュールキャッシュ内のファイルに変更を加えないように注意する必要があります。go mod verify を使用して、キャッシュ内のファイルがメインモジュールの go.sum ファイルのハッシュと一致することを確認できます。

Version queries

いくつかのコマンドでは、コマンドラインのモジュールまたはパッケージパスの後に @ 文字が続く バージョンクエリ を使用してモジュールのバージョンを指定できます。

例:

go get example.com/m@latest
go mod download example.com/m@master
go list -m -json example.com/m@e3702bed2

バージョンクエリは次のいずれかである可能性があります：

• v1.2.3 のような完全に指定されたセマンティックバージョンで、特定のバージョンを選択します。構文については Versions を参照してください。
• v1 または v1.2 のようなセマンティックバージョンプレフィックスで、そのプレフィックスを持つ最高の利用可能なバージョンを選択します。
• <v1.2.3 または >=v1.5.6 のようなセマンティックバージョン比較で、比較対象に最も近い利用可能なバージョンを選択します（> および >= の最低バージョン、< および <= の最高バージョン）。
• コミットハッシュプレフィックス、リビジョンタグ、またはブランチ名など、基盤となるソースリポジトリのリビジョン識別子。リビジョンがセマンティックバージョンでタグ付けされている場合、このクエリはそのバージョンを選択します。そうでない場合、このクエリは基盤となるコミットの 擬似バージョン を選択します。他のバージョンクエリによって一致する名前のブランチやタグは、この方法で選択できません。たとえば、v2 クエリは、v2 で始まる最新のバージョンを選択しますが、v2 という名前のブランチは選択しません。
• 最高の利用可能なリリースバージョンを選択する latest という文字列。リリースバージョンがない場合、latest は最高のプレリリースバージョンを選択します。タグ付けされたバージョンがない場合、latest はリポジトリのデフォルトブランチの先端にあるコミットの擬似バージョンを選択します。
• 現在のバージョンよりも高いバージョンが要求されている場合、upgrade が現在のバージョンを選択する upgrade という文字列。
• 現在要求されているバージョンと同じメジャーおよびマイナーバージョンを持つ最新の利用可能なバージョンを選択する patch という文字列。現在要求されているバージョンがない場合、patch は latest と同等です。Go 1.16 以降、go get は patch を使用する際に現在のバージョンを要求します（ただし、-u=patch フラグにはこの要件はありません）。

特定の名前付きバージョンやリビジョンのクエリを除いて、すべてのクエリは go list -m -versions によって報告された利用可能なバージョンを考慮します。このリストには、擬似バージョンではなくタグ付けされたバージョンのみが含まれます。メインモジュールの go.mod ファイル にある exclude ディレクティブ によって許可されていないモジュールバージョンは考慮されません。同じモジュールの go.mod ファイルにある retract ディレクティブ によってカバーされるバージョンも、[-retracted] フラグが go list -m と共に使用される場合や、retract ディレクティブを読み込む場合を除いて無視されます。

Release versions はプレリリースバージョンよりも優先されます。たとえば、v1.2.2 と v1.2.3-pre のバージョンが利用可能な場合、latest クエリは v1.2.2 を選択しますが、v1.2.3-pre はより高いです。<v1.2.4 クエリも v1.2.2 を選択しますが、v1.2.3-pre は v1.2.4 に近いです。リリースまたはプレリリースバージョンが利用できない場合、latest、upgrade、および patch クエリは、リポジトリのデフォルトブランチの先端にあるコミットの擬似バージョンを選択します。他のクエリはエラーを報告します。

Module commands outside a module

モジュール対応の Go コマンドは、通常、作業ディレクトリまたは親ディレクトリにある go.mod ファイルによって定義された main module のコンテキストで実行されます。一部のコマンドは go.mod ファイルなしでモジュール対応モードで実行できますが、ほとんどのコマンドは異なる動作をするか、go.mod ファイルが存在しない場合にエラーを報告します。

モジュール対応モードの有効化と無効化に関する情報は、Module-aware commands を参照してください。

go work init

使用法:

go work init [moddirs]

Init は、現在のディレクトリに新しい go.work ファイルを初期化して書き込み、実質的に現在のディレクトリに新しいワークスペースを作成します。

go work init は、ワークスペースモジュールへのパスをオプションの引数として受け取ります。引数が省略された場合、モジュールのない空のワークスペースが作成されます。

各引数パスは、go.work ファイルの使用ディレクティブに追加されます。現在の go バージョンも go.work ファイルにリストされます。

go work edit

使用法:

go work edit [editing flags] [go.work]

go work edit コマンドは、主にツールやスクリプトによる使用のために go.work を編集するためのコマンドラインインターフェースを提供します。go.work を読み取るだけで、関与するモジュールに関する情報を調べることはありません。ファイルが指定されていない場合、Edit は現在のディレクトリとその親ディレクトリに go.work ファイルを探します。

編集フラグは、一連の編集操作を指定します。

• -fmt フラグは、他の変更を加えずに go.work ファイルを再フォーマットします。この再フォーマットは、go.work ファイルを使用または書き換える他の変更によっても暗黙的に行われます。このフラグが必要なのは、他のフラグが指定されていない場合、つまり「go work edit -fmt」のような場合だけです。
• -use=path および -dropuse=path フラグは、go.work ファイルのモジュールディレクトリのセットから使用ディレクティブを追加および削除します。
• -replace=old[@v]=new[@v] フラグは、指定されたモジュールパスとバージョンペアの置き換えを追加します。@v が old@v に省略された場合、左側にバージョンのない置き換えが追加され、古いモジュールパスのすべてのバージョンに適用されます。@v が new@v に省略された場合、新しいパスはローカルモジュールルートディレクトリである必要があり、モジュールパスではありません。-replace は、old[@v] に対する冗長な置き換えを上書きするため、@v を省略すると特定のバージョンの既存の置き換えが削除されます。
• -dropreplace=old[@v] フラグは、指定されたモジュールパスとバージョンペアの置き換えを削除します。@v が省略された場合、左側にバージョンのない置き換えが削除されます。
• -go=version フラグは、期待される Go 言語のバージョンを設定します。

編集フラグは繰り返し使用できます。変更は指定された順序で適用されます。

go work edit には、出力を制御する追加のフラグがあります

• -print フラグは、最終的な go.work をテキスト形式で印刷し、go.mod に書き戻すのではなくします。
• -json フラグは、最終的な go.work ファイルを JSON 形式で印刷し、go.mod に書き戻すのではなくします。JSON 出力は、これらの Go タイプに対応しています：

type Module struct {
   Path    string
   Version string
}
type GoWork struct {
   Go        string
   Directory []Directory
   Replace   []Replace
}
type Use struct {
   Path       string
   ModulePath string
}
type Replace struct {
   Old Module
   New Module
}

go work use

使用法:

go work use [-r] [moddirs]

go work use コマンドは、ディレクトリを追加するためのコマンドラインインターフェースを提供します。オプションで再帰的に go.work ファイルに追加します。

コマンドラインでリストされた各引数ディレクトリに対して、use ディレクティブが go.work ファイルに追加され、ディスク上に存在する場合は go.work ファイルから削除されます。

-r フラグは、引数ディレクトリ内のモジュールを再帰的に検索し、使用コマンドは各ディレクトリが引数として指定されたかのように動作します。

go work sync

使用法:

go work sync

go work sync コマンドは、ワークスペースのビルドリストをワークスペースのモジュールに同期します。

ワークスペースのビルドリストは、ワークスペース内でビルドを行うために使用されるすべての（推移的）依存モジュールのバージョンのセットです。go work sync は、Minimal Version Selection (MVS) アルゴリズムを使用してそのビルドリストを生成し、次にそのバージョンをワークスペース内の各モジュール（use ディレクティブを持つ）に同期します。

ワークスペースビルドリストが計算されると、ワークスペース内の各モジュールの go.mod ファイルは、そのモジュールに関連する依存関係がワークスペースビルドリストに一致するように書き換えられます。 Minimal Version Selection は、ビルドリストの各モジュールのバージョンが、各ワークスペースモジュールのバージョンと常に同じかそれ以上であることを保証します。

Module proxies

GOPROXY プロトコル

モジュールプロキシは、以下に指定されたパスに対する GET リクエストに応答できる HTTP サーバーです。リクエストにはクエリパラメータはなく、特定のヘッダーは必要ないため、固定ファイルシステムから提供されるサイト（file:// URL を含む）でもモジュールプロキシとして機能できます。

成功した HTTP 応答は、ステータスコード 200 (OK) を持つ必要があります。リダイレクト (3xx) は追従されます。ステータスコード 4xx および 5xx の応答はエラーとして扱われます。エラーコード 404 (Not Found) および 410 (Gone) は、要求されたモジュールまたはバージョンがプロキシで利用できないことを示しますが、他の場所で見つかる可能性があります。エラー応答は、text/plain のコンテンツタイプを持ち、charset は utf-8 または us-ascii のいずれかである必要があります。

go コマンドは、GOPROXY 環境変数を使用してプロキシまたはソース管理サーバーに連絡するように構成できます。この環境変数は、プロキシ URL のリストを受け入れます。リストには、direct または off のキーワードを含めることができます（詳細については 環境変数 を参照してください）。リストの要素は、カンマ (,) またはパイプ (|) で区切ることができ、エラーフォールバックの動作を決定します。URL の後にカンマが続く場合、go コマンドは 404 (Not Found) または 410 (Gone) の応答の後にのみ後続のソースにフォールバックします。URL の後にパイプが続く場合、go コマンドは、タイムアウトなどの非 HTTP エラーを含む任意のエラーの後に後続のソースにフォールバックします。このエラーハンドリングの動作により、プロキシは不明なモジュールのゲートキーパーとして機能できます。たとえば、プロキシは、承認されたリストにないモジュールに対してエラー 403 (Forbidden) で応答することができます（詳細については プライベートモジュールのプライベートプロキシの提供 を参照してください）。

以下の表は、モジュールプロキシが応答する必要があるクエリを指定します。各パスについて、$base はプロキシ URL のパス部分、$module はモジュールパス、$version はバージョンです。たとえば、プロキシ URL が https://example.com/mod で、クライアントがバージョン v0.3.2 のモジュール golang.org/x/text の go.mod ファイルを要求している場合、クライアントは GET リクエストを https://example.com/mod/golang.org/x/text/@v/v0.3.2.mod に送信します。

大文字と小文字を区別しないファイルシステムから提供する際の曖昧さを避けるために、$module および $version 要素は、大文字の各文字を感嘆符と対応する小文字の文字に置き換えることでケースエンコードされます。これにより、モジュール example.com/M と example.com/m の両方をディスクに保存できるようになります。前者は example.com/!m としてエンコードされます。


| パス | 説明 |
| —- | —- |
| $base/$module/@v/list | 指定されたモジュールの既知のバージョンのリストをプレーンテキストで返します。1行ごとに1つのリストです。このリストには擬似バージョンを含めるべきではありません。 |
| $base/$module/@v/$version.info | モジュールの特定のバージョンに関する JSON 形式のメタデータを返します。
応答は、以下の Go データ構造に対応する JSON オブジェクトでなければなりません：

{$pre74}

Version フィールドは必須であり、有効な 標準バージョン を含む必要があります（詳細については バージョン を参照してください）。リクエストパスの $version は、同じバージョンである必要はなく、有効なバージョンである必要もありません。このエンドポイントは、ブランチ名やリビジョン識別子のバージョンを見つけるために使用できます。ただし、$version が $module と互換性のあるメジャーバージョンの標準バージョンである場合、成功した応答の Version フィールドは同じでなければなりません。

Time フィールドはオプションです。存在する場合は、RFC 3339 形式の文字列でなければなりません。これは、バージョンが作成された時刻を示します。

将来的に他のフィールドが追加される可能性があるため、他の名前は予約されています。 |
| $base/$module/@v/$version.mod | 特定のバージョンのモジュールの go.mod ファイルを返します。モジュールが要求されたバージョンで go.mod ファイルを持っていない場合、要求されたモジュールパスを含む module ステートメントのみを含むファイルを返す必要があります。そうでない場合、元の未修正の go.mod ファイルを返す必要があります。 |
| $base/$module/@v/$version.zip | 特定のバージョンのモジュールの内容を含む zip ファイルを返します。詳細については モジュール zip ファイル を参照してください。 |
| $base/$module/@latest | 最新の既知のバージョンのモジュールに関する JSON 形式のメタデータを $base/$module/@v/$version.info と同じ形式で返します。最新のバージョンは、go コマンドが $base/$module/@v/list が空であるか、リストされたバージョンが適切でない場合に使用すべきモジュールのバージョンである必要があります。このエンドポイントはオプションであり、モジュールプロキシは実装する必要はありません。 |

モジュールの最新バージョンを解決する際、go コマンドは $base/$module/@v/list をリクエストし、適切なバージョンが見つからない場合は $base/$module/@latest をリクエストします。go コマンドは、順に、意味的に最も高いリリースバージョン、意味的に最も高いプレリリースバージョン、そして時間的に最も最近の擬似バージョンを優先します。Go 1.12 およびそれ以前では、go コマンドは $base/$module/@v/list の擬似バージョンをプレリリースバージョンと見なしていましたが、Go 1.13 以降はこれが当てはまりません。

モジュールプロキシは、$base/$module/$version.mod および $base/$module/$version.zip クエリに対する成功した応答のために常に同じコンテンツを提供しなければなりません。このコンテンツは、go.sum ファイル を使用して 暗号的に認証 されており、デフォルトでは チェックサムデータベース を使用しています。

go コマンドは、$GOPATH/pkg/mod/cache/download のモジュールキャッシュにモジュールプロキシからダウンロードしたほとんどのコンテンツをキャッシュします。バージョン管理システムから直接ダウンロードする場合でも、go コマンドは明示的な info、mod、および zip ファイルを合成し、このディレクトリに保存します。これは、プロキシから直接ダウンロードした場合と同じです。キャッシュレイアウトはプロキシ URL スペースと同じであるため、$GOPATH/pkg/mod/cache/download を https://example.com/proxy に提供する（またはコピーする）ことで、ユーザーは GOPROXY を https://example.com/proxy に設定することによってキャッシュされたモジュールバージョンにアクセスできます。

プロキシとの通信

go コマンドは、モジュールプロキシ からモジュールのソースコードとメタデータをダウンロードできます。GOPROXY 環境変数 を使用して、go コマンドが接続できるプロキシを構成し、バージョン管理システム と直接通信できるかどうかを設定できます。ダウンロードされたモジュールデータは、モジュールキャッシュ に保存されます。go コマンドは、キャッシュにない情報が必要な場合にのみプロキシに連絡します。

GOPROXY プロトコル セクションでは、GOPROXY サーバーに送信される可能性のあるリクエストについて説明しています。ただし、go コマンドがこれらのリクエストを行うタイミングを理解することも役立ちます。たとえば、go build は以下の手順に従います：

• ビルドリスト を計算するために、go.mod ファイル を読み込み、最小バージョン選択 (MVS) を実行します。
• コマンドラインで指定されたパッケージと、それらがインポートするパッケージを読み込みます。
• ビルドリスト内のいずれのモジュールも提供していないパッケージがある場合、それを提供するモジュールを見つけます。その最新バージョンに対してモジュール要件を go.mod に追加し、最初からやり直します。
• すべてが読み込まれた後にパッケージをビルドします。

go コマンドがビルドリストを計算する際、モジュールグラフ 内の各モジュールの go.mod ファイルを読み込みます。キャッシュに go.mod ファイルがない場合、go コマンドは、$module/@v/$version.mod リクエストを使用してプロキシからそれをダウンロードします（ここで $module はモジュールパス、$version はバージョンです）。これらのリクエストは、curl のようなツールでテストできます。たとえば、以下のコマンドは、バージョン v0.2.0 の golang.org/x/mod の go.mod ファイルをダウンロードします：

$ curl https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.mod
module golang.org/x/mod
go 1.12
require (
   golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550
   golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e
   golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898
)

パッケージを読み込むには、go コマンドがそれを提供するモジュールのソースコードが必要です。モジュールのソースコードは、.zip ファイルに配布され、モジュールキャッシュに抽出されます。モジュール .zip がキャッシュにない場合、go コマンドは $module/@v/$version.zip リクエストを使用してそれをダウンロードします。

$ curl -O https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.zip
$ unzip -l v0.2.0.zip | head
Archive:  v0.2.0.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
   1479  00-00-1980 00:00   golang.org/x/mod@v0.2.0/LICENSE
   1303  00-00-1980 00:00   golang.org/x/mod@v0.2.0/PATENTS
   559  00-00-1980 00:00   golang.org/x/mod@v0.2.0/README
   21  00-00-1980 00:00   golang.org/x/mod@v0.2.0/codereview.cfg
   214  00-00-1980 00:00   golang.org/x/mod@v0.2.0/go.mod
   1476  00-00-1980 00:00   golang.org/x/mod@v0.2.0/go.sum
   5224  00-00-1980 00:00   golang.org/x/mod@v0.2.0/gosumcheck/main.go

.mod および .zip リクエストは別々であることに注意してください。go.mod ファイルは通常 .zip ファイルに含まれていますが、go コマンドは多くの異なるモジュールの go.mod ファイルをダウンロードする必要があり、.mod ファイルは .zip ファイルよりもはるかに小さいです。さらに、Go プロジェクトに go.mod ファイルがない場合、プロキシは module ディレクティブ のみを含む合成 go.mod ファイルを提供します。合成 go.mod ファイルは、バージョン管理システム からダウンロードする際に go コマンドによって生成されます。

go コマンドがビルドリスト内のいずれのモジュールも提供していないパッケージを読み込む必要がある場合、新しいモジュールを見つけることを試みます。セクション パッケージをモジュールに解決する では、このプロセスについて説明しています。要約すると、go コマンドは、パッケージを含む可能性のある各モジュールパスの最新バージョンに関する情報をリクエストします。たとえば、パッケージ golang.org/x/net/html の場合、go コマンドは golang.org/x/net/html、golang.org/x/net、golang.org/x/、および golang.org のモジュールの最新バージョンを見つけようとします。golang.org/x/net のみが実際に存在し、そのパッケージを提供しているため、go コマンドはそのモジュールの最新バージョンを使用します。複数のモジュールがパッケージを提供している場合、go コマンドは最も長いパスを持つモジュールを使用します。

go コマンドがモジュールの最新バージョンをリクエストする際、最初に $module/@v/list のリクエストを送信します。リストが空であるか、返されたバージョンのいずれも使用できない場合、$module/@latest のリクエストを送信します。バージョンが選択されると、go コマンドはメタデータのために $module/@v/$version.info リクエストを送信します。その後、$module/@v/$version.mod および $module/@v/$version.zip リクエストを送信して go.mod ファイルとソースコードを読み込みます。

$ curl https://proxy.golang.org/golang.org/x/mod/@v/list
v0.1.0
v0.2.0
$ curl https://proxy.golang.org/golang.org/x/mod/@v/v0.2.0.info
{"Version":"v0.2.0","Time":"2020-01-02T17:33:45Z"}

.mod または .zip ファイルをダウンロードした後、go コマンドは暗号ハッシュを計算し、それがメインモジュールの go.sum ファイルのハッシュと一致するかどうかを確認します。ハッシュが go.sum に存在しない場合、デフォルトでは go コマンドが チェックサムデータベース から取得します。計算されたハッシュが一致しない場合、go コマンドはセキュリティエラーを報告し、モジュールキャッシュにファイルをインストールしません。GOPRIVATE および GONOSUMDB 環境変数 を使用して、特定のモジュールに対するチェックサムデータベースへのリクエストを無効にすることができます。GOSUMDB 環境変数を off に設定して、チェックサムデータベースへのリクエストを完全に無効にすることもできます。詳細については モジュールの認証 を参照してください。.info リクエストに対して返されるバージョンリストおよびバージョンメタデータは認証されておらず、時間とともに変更される可能性があることに注意してください。

プロキシからのモジュールの直接提供

ほとんどのモジュールは、バージョン管理リポジトリから開発および提供されます。直接モード では、go コマンドがバージョン管理ツールを使用してそのようなモジュールをダウンロードします（バージョン管理システム を参照）。モジュールプロキシから直接モジュールを提供することも可能です。これは、バージョン管理サーバーを公開せずにモジュールを提供したい組織や、go コマンドがサポートしていないバージョン管理ツールを使用している組織にとって便利です。

go コマンドが直接モードでモジュールをダウンロードする際、最初にモジュールパスに基づいて HTTP GET リクエストでモジュールサーバーの URL を検索します。HTML 応答内で <meta> タグを go-import という名前で探します。タグの内容には、リポジトリのルートパス、バージョン管理システム、および URL がスペースで区切られて含まれている必要があります。モジュールパスのリポジトリを見つける詳細については、モジュールパスのリポジトリを見つける を参照してください。

バージョン管理システムが mod の場合、go コマンドは、GOPROXY プロトコル を使用して指定された URL からモジュールをダウンロードします。

たとえば、go コマンドがバージョン v1.0.0 のモジュール example.com/gopher をダウンロードしようとしているとします。https://example.com/gopher?go-get=1 にリクエストを送信します。サーバーは、次のタグを含む HTML ドキュメントで応答します：

<meta name="go-import" content="example.com/gopher mod https://modproxy.example.com">

この応答に基づいて、go コマンドは https://modproxy.example.com/example.com/gopher/@v/v1.0.0.info、v1.0.0.mod、および v1.0.0.zip のリクエストを送信してモジュールをダウンロードします。

プロキシから直接提供されるモジュールは、GOPATH モードで go get でダウンロードできないことに注意してください。

バージョン管理システム

go コマンドは、バージョン管理リポジトリから直接モジュールのソースコードとメタデータをダウンロードできます。プロキシからモジュールをダウンロードする方が通常は速いですが、プロキシが利用できない場合や、モジュールのリポジトリがプロキシにアクセスできない場合（プライベートリポジトリに多い）には、リポジトリに直接接続する必要があります。Git、Subversion、Mercurial、Bazaar、および Fossil がサポートされています。PATH にディレクトリにバージョン管理ツールがインストールされている必要があります。そうしないと、go コマンドはそれを使用できません。

特定のモジュールをプロキシではなくソースリポジトリからダウンロードするには、GOPRIVATE または GONOPROXY 環境変数を設定します。go コマンドをすべてのモジュールをソースリポジトリから直接ダウンロードするように構成するには、GOPROXY を direct に設定します。詳細については 環境変数 を参照してください。

モジュールパスのリポジトリを見つける

go コマンドが direct モードでモジュールをダウンロードする際、最初にモジュールを含むリポジトリを特定します。

モジュールパスの末尾に VCS 修飾子（.bzr、.fossil、.git、.hg、.svn のいずれか）がある場合、go コマンドは、そのパス修飾子までのすべてをリポジトリ URL として使用します。たとえば、モジュール example.com/foo.git/bar の場合、go コマンドは git を使用して example.com/foo.git でリポジトリをダウンロードし、bar サブディレクトリにモジュールがあることを期待します。go コマンドは、バージョン管理ツールによってサポートされているプロトコルに基づいて使用するプロトコルを推測します。

モジュールパスに修飾子がない場合、go コマンドは、モジュールパスから導出された URL に GET クエリ文字列を付けて HTTP ?go-get=1 リクエストを送信します。たとえば、モジュール golang.org/x/mod の場合、go コマンドは次のリクエストを送信する可能性があります：

https://golang.org/x/mod?go-get=1 (preferred)
http://golang.org/x/mod?go-get=1  (fallback, only with GOINSECURE)

go コマンドはリダイレクトに従いますが、その他の応答ステータスコードは無視します。したがって、サーバーは 404 または他のエラーステータスで応答する可能性があります。GOINSECURE 環境変数を設定して、特定のモジュールに対する暗号化されていない HTTP へのフォールバックとリダイレクトを許可できます。

サーバーは、ドキュメントの <head> に <meta> タグを含む HTML ドキュメントで応答する必要があります。<meta> タグは、go コマンドの制限されたパーサーを混乱させないように、ドキュメントの早い段階で表示される必要があります。特に、生の JavaScript や CSS の前に表示されるべきです。<meta> タグは次の形式でなければなりません：

<meta name="go-import" content="root-path vcs repo-url">

root-path はリポジトリのルートパスであり、モジュールパスのリポジトリのルートディレクトリに対応する部分です。これは、要求されたモジュールパスのプレフィックスまたは完全一致でなければなりません。完全一致でない場合、<meta> タグが一致することを確認するために、プレフィックスの別のリクエストが行われます。

vcs はバージョン管理システムです。これは、以下の表にリストされているツールのいずれか、または mod キーワードでなければなりません。これは、go コマンドに、GOPROXY プロトコル を使用して指定された URL からモジュールをダウンロードするよう指示します。詳細については プロキシからのモジュールの直接提供 を参照してください。

repo-url はリポジトリの URL です。URL にスキームが含まれていない場合（モジュールパスに VCS 修飾子がある場合や、<meta> タグにスキームがない場合）、go コマンドは、バージョン管理システムによってサポートされている各プロトコルを試みます。たとえば、Git では、go コマンドは https:// を試み、その後 git+ssh:// を試みます。安全でないプロトコル（http:// や git:// など）は、モジュールパスが GOINSECURE 環境変数によって一致する場合にのみ使用できます。

golang.org/x/mod を再度考慮すると、go コマンドは https://golang.org/x/mod?go-get=1 にリクエストを送信します。サーバーは、次のタグを含む HTML ドキュメントで応答します：

<meta name="go-import" content="golang.org/x/mod git https://go.googlesource.com/mod">

この応答から、go コマンドはリモート URL https://go.googlesource.com/mod の Git リポジトリを使用します。

GitHub やその他の人気のあるホスティングサービスは、すべてのリポジトリに対して ?go-get=1 クエリに応答するため、通常はこれらのサイトでホストされているモジュールに対してサーバーの構成は必要ありません。

リポジトリの URL が見つかった後、go コマンドはリポジトリをモジュールキャッシュにクローンします。一般的に、go コマンドはリポジトリから不要なデータを取得しないように努めます。ただし、実際に使用されるコマンドはバージョン管理システムによって異なり、時間とともに変更される可能性があります。Git の場合、go コマンドは、コミットをダウンロードせずに利用可能なバージョンのほとんどをリストできます。通常、先祖コミットをダウンロードせずにコミットを取得しますが、そうする必要がある場合もあります。

バージョンをコミットにマッピングする

go コマンドは、v1.2.3、v2.4.0-beta、または v3.0.0+incompatible のような特定の 標準バージョン でリポジトリ内のモジュールをチェックアウトできます。各モジュールバージョンは、特定のバージョンのためにチェックアウトすべきリビジョンを示す セマンティックバージョンタグ をリポジトリ内に持つべきです。

モジュールがリポジトリのルートディレクトリまたはルートディレクトリのメジャーバージョンサブディレクトリに定義されている場合、各バージョンタグ名は対応するバージョンと等しくなります。たとえば、モジュール golang.org/x/text はそのリポジトリのルートディレクトリに定義されているため、バージョン v0.3.2 はそのリポジトリ内で v0.3.2 タグを持っています。これはほとんどのモジュールに当てはまります。

モジュールがリポジトリ内のサブディレクトリに定義されている場合、すなわち、モジュールパスの モジュールサブディレクトリ 部分が空でない場合、各タグ名はモジュールサブディレクトリでプレフィックスされ、スラッシュが続きます。たとえば、モジュール golang.org/x/tools/gopls は、ルートパス golang.org/x/tools のリポジトリの gopls サブディレクトリに定義されています。そのモジュールのバージョン v0.4.0 は、そのリポジトリ内で gopls/v0.4.0 という名前のタグを持たなければなりません。

セマンティックバージョンタグのメジャーバージョン番号は、モジュールパスのメジャーバージョンサフィックス（ある場合）と一致している必要があります。たとえば、タグ v1.0.0 はモジュール example.com/mod に属する可能性がありますが、example.com/mod/v2 には属しません。example.com/mod/v2 には v2.0.0 のようなタグがあります。

メジャーバージョン v2 以上のタグは、go.mod ファイルが存在しない場合、メジャーバージョンサフィックスのないモジュールに属する可能性があります。この種のバージョンは、+incompatible サフィックスで示されます。バージョンタグ自体にはサフィックスを持たない必要があります。詳細については、非モジュールリポジトリとの互換性 を参照してください。

タグが作成されると、それは削除されたり、別のリビジョンに変更されたりしてはなりません。バージョンは、認証 されて、安全で再現可能なビルドを保証します。タグが変更されると、クライアントはそれをダウンロードする際にセキュリティエラーを見る可能性があります。タグが削除された後でも、その内容は モジュールプロキシ で利用可能なままである可能性があります。

擬似バージョンをコミットにマッピングする

go コマンドは、v1.3.2-0.20191109021931-daa7c04131f5 のような特定のリビジョンでリポジトリ内のモジュールをチェックアウトできます。

擬似バージョンの最後の 12 文字（上記の daa7c04131f5）は、チェックアウトするリポジションを示します。これは、バージョン管理システムによって異なります。Git および Mercurial では、これはコミットハッシュのプレフィックスです。Subversion では、これはゼロパディングされたリビジョン番号です。

コミットをチェックアウトする前に、go コマンドは、タイムスタンプ（上記の 20191109021931）がコミット日付と一致することを確認します。また、ベースバージョン（上記の v1.3.1、v1.3.2 の前のバージョン）がコミットの先祖であるセマンティックバージョンタグに対応していることも確認します。これらのチェックにより、モジュールの著者は擬似バージョンが他のリリースバージョンとどのように比較されるかを完全に制御できます。

詳細については、擬似バージョン を参照してください。

ブランチとコミットをバージョンにマッピングする

モジュールは、バージョンクエリ を使用して特定のブランチ、タグ、またはリビジョンでチェックアウトできます。

go get example.com/mod@master

go コマンドは、これらの名前を 標準バージョン に変換します。これは、最小バージョン選択 (MVS) に使用できます。MVS は、バージョンを明確に順序付ける能力に依存します。ブランチ名やリビジョンは、リポジトリ構造に依存するため、時間の経過とともに信頼性を持って比較することはできません。

リビジョンが v1.2.3 のような 1 つ以上のセマンティックバージョンタグでタグ付けされている場合、最も高い有効バージョンのタグが使用されます。go コマンドは、ターゲットモジュールに属する可能性のあるセマンティックバージョンタグのみを考慮します。たとえば、タグ v1.5.2 は、メジャーバージョンがモジュールパスのサフィックスと一致しないため、example.com/mod/v2 には考慮されません。

リビジョンが有効なセマンティックバージョンタグでタグ付けされていない場合、go コマンドは 擬似バージョン を生成します。リビジョンに有効なセマンティックバージョンタグを持つ先祖がいる場合、最も高い先祖バージョンが擬似バージョンのベースとして使用されます。詳細については、擬似バージョン を参照してください。

リポジトリ内のモジュールディレクトリ

モジュールのリポジトリが特定のリビジョンでチェックアウトされると、go コマンドはモジュールの go.mod ファイル（モジュールのルートディレクトリ）を含むディレクトリを特定する必要があります。

モジュールパスは、リポジトリのルートパス（リポジトリのルートディレクトリに対応）、モジュールのサブディレクトリ、およびメジャーバージョンサフィックス（v2 以上でリリースされたモジュールのみ）の3つの部分で構成されることを思い出してください。

ほとんどのモジュールでは、モジュールパスはリポジトリのルートパスと等しいため、モジュールのルートディレクトリはリポジトリのルートディレクトリになります。

モジュールは時々リポジトリのサブディレクトリで定義されます。これは、複数のコンポーネントを持つ大規模なリポジトリが独立してリリースおよびバージョン管理される必要がある場合に一般的です。そのようなモジュールは、リポジトリのルートパスの後のモジュールパスの部分に一致するサブディレクトリで見つかることが期待されます。たとえば、モジュール example.com/monorepo/foo/bar がルートパス example.com/monorepo のリポジトリにあると仮定します。その go.mod ファイルは foo/bar サブディレクトリに存在する必要があります。

モジュールがメジャーバージョン v2 以上でリリースされている場合、そのパスには メジャーバージョンサフィックス が必要です。メジャーバージョンサフィックスを持つモジュールは、サフィックスのあるサブディレクトリとサフィックスのないサブディレクトリのいずれかで定義される可能性があります。たとえば、上記のモジュールの新しいバージョンがパス example.com/monorepo/foo/bar/v2 でリリースされると仮定します。その go.mod ファイルは foo/bar または foo/bar/v2 のいずれかに存在する可能性があります。

メジャーバージョンサフィックスを持つサブディレクトリは メジャーバージョンサブディレクトリ です。これらは、単一のブランチでモジュールの複数のメジャーバージョンを開発するために使用される場合があります。複数のメジャーバージョンの開発が別々のブランチで進行する場合、これは不要かもしれません。しかし、メジャーバージョンサブディレクトリには重要な特性があります：GOPATH モードでは、パッケージインポートパスが GOPATH/src の下のディレクトリと正確に一致します。go コマンドは GOPATH モードで最小限のモジュール互換性を提供します（非モジュールリポジトリとの互換性を参照）、したがって、GOPATH モードで構築されたプロジェクトとの互換性のためにメジャーバージョンサブディレクトリが常に必要というわけではありません。ただし、最小限のモジュール互換性をサポートしていない古いツールは問題を抱える可能性があります。

go コマンドがモジュールのルートディレクトリを見つけると、ディレクトリの内容の .zip ファイルを作成し、その後 .zip ファイルをモジュールキャッシュに抽出します。.zip ファイルに含まれる可能性のあるファイルの詳細については、ファイルパスとサイズの制約を参照してください。.zip ファイルの内容は、.zip ファイルがプロキシからダウンロードされた場合と同じ方法で、モジュールキャッシュに抽出される前に 認証されます。

モジュールの zip ファイルには vendor ディレクトリの内容や、go.mod ファイルを含むネストされたモジュールは含まれません。これは、モジュールが自分のディレクトリ外や他のモジュールのファイルを参照しないように注意する必要があることを意味します。たとえば、//go:embed パターンはネストされたモジュールのファイルと一致してはなりません。この動作は、ファイルがモジュールに含まれないべき状況で便利な回避策として機能する場合があります。たとえば、リポジトリに testdata ディレクトリに大きなファイルがチェックインされている場合、モジュールの著者は go.mod ファイルを testdata に追加して、ユーザーがそれらのファイルをダウンロードする必要がないようにすることができます。もちろん、これは依存関係をテストしているユーザーのカバレッジを減少させる可能性があります。

LICENSE ファイルの特別なケース

go コマンドがリポジトリのルートディレクトリにないモジュールの .zip ファイルを作成する場合、モジュールのルートディレクトリに LICENSE という名前のファイルが存在しない場合（go.mod と同じ場所に）、go コマンドは、同じリビジョンに存在する場合、リポジトリのルートディレクトリから LICENSE という名前のファイルをコピーします。

この特別なケースにより、同じ LICENSE ファイルがリポジトリ内のすべてのモジュールに適用されることができます。これは、LICENSE という名前のファイルに特に適用され、.txt のような拡張子は含まれません。残念ながら、これは既存のモジュールの暗号的合計を壊さずに拡張することはできません。 モジュールの認証を参照してください。他のツールやウェブサイト（https://pkg.go.devなど）は、他の名前のファイルを認識する場合があります。

go コマンドは、モジュール .zip ファイルを作成する際にシンボリックリンクを含めないことにも注意してください。 ファイルパスとサイズの制約を参照してください。したがって、リポジトリのルートディレクトリに LICENSE ファイルがない場合、著者は代わりにサブディレクトリで定義されたモジュールにライセンスファイルのコピーを作成して、それらのファイルがモジュール .zip ファイルに含まれることを確認できます。

GOVCS でのバージョン管理ツールの制御

go コマンドの、git のようなバージョン管理コマンドを使用してモジュールをダウンロードする能力は、コードが任意のサーバーからインポートできる分散型パッケージエコシステムにとって重要です。また、悪意のあるサーバーが呼び出されたバージョン管理コマンドを実行して意図しないコードを実行させる方法を見つけた場合、潜在的なセキュリティ問題にもなります。

機能とセキュリティの懸念のバランスを取るために、go コマンドはデフォルトで git と hg のみを使用して、パブリックサーバーからコードをダウンロードします。プライベートサーバーからコードをダウンロードするために、GOPRIVATE 環境変数 に一致するパッケージをホストしているサーバーを定義します。Git と Mercurial のみを許可する理由は、これらの2つのシステムが信頼できないサーバーのクライアントとして実行される問題に最も注意を払ってきたからです。対照的に、Bazaar、Fossil、Subversion は主に信頼された認証環境で使用されており、攻撃面としての精査があまり行われていません。

バージョン管理コマンドの制限は、コードをダウンロードするために直接バージョン管理アクセスを使用する場合にのみ適用されます。プロキシからモジュールをダウンロードする際、go コマンドは、常に許可されている GOPROXY プロトコル を使用します。デフォルトでは、go コマンドは、パブリックモジュールに対して Go モジュールミラー（https://proxy.golang.org）を使用し、プライベートモジュールまたはミラーがパブリックパッケージを提供することを拒否した場合（通常は法的理由による）にのみバージョン管理にフォールバックします。したがって、クライアントはデフォルトで Bazaar、Fossil、Subversion リポジトリから提供されるパブリックコードにアクセスできます。これらのダウンロードは Go モジュールミラーを使用し、カスタムサンドボックスを使用してバージョン管理コマンドを実行するセキュリティリスクを引き受けます。

GOVCS 変数は、特定のモジュールに対して許可されるバージョン管理システムを変更するために使用できます。GOVCS 変数は、モジュール対応モードと GOPATH モードの両方でパッケージをビルドする際に適用されます。モジュールを使用する場合、パターンはモジュールパスに対して一致します。GOPATH を使用する場合、パターンはバージョン管理リポジトリのルートに対応するインポートパスに対して一致します。

GOVCS 変数の一般的な形式は、カンマ区切りの pattern:vcslist ルールのリストです。パターンは、モジュールまたはインポートパスの先頭の1つ以上の要素に一致する グロブパターン でなければなりません。vcslist は、許可されたバージョン管理コマンドのパイプ区切りリスト、または all で任意の既知のコマンドの使用を許可するか、off で何も許可しないことを示します。モジュールが vcslist off でパターンに一致する場合でも、オリジンサーバーが mod スキームを使用している場合は、GOPROXY プロトコルを使用してモジュールをダウンロードするように go コマンドに指示します。リスト内の最初の一致するパターンが適用され、後のパターンも一致する可能性があっても適用されます。

たとえば、次のように考えてみてください：

GOVCS=github.com:git,evil.com:off,*:git|hg

この設定では、github.com/ で始まるモジュールまたはインポートパスを持つコードは git のみを使用でき、evil.com のパスはバージョン管理コマンドを使用できず、他のすべてのパス（* はすべてに一致）は git または hg のみを使用できます。

特別なパターン public と private は、パブリックおよびプライベートのモジュールまたはインポートパスに一致します。パスは GOPRIVATE 変数に一致する場合はプライベートであり、それ以外はパブリックです。

GOVCS 変数のルールに一致しない特定のモジュールまたはインポートパスがない場合、go コマンドはデフォルトルールを適用し、GOVCS 表記で public:git|hg,private:all と要約できます。

任意のパッケージに対して任意のバージョン管理システムの自由な使用を許可するには、次のようにします：

GOVCS=*:all

すべてのバージョン管理の使用を無効にするには、次のようにします：

GOVCS=*:off

go env -w コマンド を使用して、将来の go コマンドの呼び出しのために GOVCS 変数を設定できます。

GOVCS は Go 1.16 で導入されました。以前のバージョンの Go では、任意のモジュールに対して任意の既知のバージョン管理ツールを使用できます。

モジュール zip ファイル

モジュールのバージョンは .zip ファイルとして配布されます。これらのファイルと直接やり取りする必要はほとんどありません。go コマンドは、モジュールプロキシ とバージョン管理リポジトリから自動的に作成、ダウンロード、および抽出します。ただし、クロスプラットフォームの互換性制約を理解したり、モジュールプロキシを実装したりする際に、これらのファイルについて知っておくことは依然として有用です。

go mod download コマンドは、1つ以上のモジュールの zip ファイルをダウンロードし、その後それらのファイルを モジュールキャッシュ に抽出します。GOPROXY および他の 環境変数 に応じて、go コマンドはプロキシから zip ファイルをダウンロードするか、ソース管理リポジトリをクローンしてそこから zip ファイルを作成します。-json フラグを使用して、モジュールキャッシュ内のダウンロード zip ファイルとその抽出された内容の場所を見つけることができます。

golang.org/x/mod/zip パッケージを使用して、プログラム的に zip ファイルを作成、抽出、または内容を確認できます。

ファイルパスとサイズの制約

モジュール zip ファイルの内容にはいくつかの制約があります。これらの制約は、zip ファイルが広範なプラットフォームで安全かつ一貫して抽出できることを保証します。

• モジュール zip ファイルのサイズは最大 500 MiB です。ファイルの合計未圧縮サイズも 500 MiB に制限されています。go.mod ファイルは 16 MiB に制限されています。LICENSE ファイルも 16 MiB に制限されています。これらの制限は、ユーザー、プロキシ、およびモジュールエコシステムの他の部分に対するサービス拒否攻撃を軽減するために存在します。モジュールディレクトリツリー内に 500 MiB を超えるファイルが含まれているリポジトリは、モジュールのパッケージをビルドするために必要なファイルのみを含むコミットでモジュールバージョンにタグを付けるべきです。ビデオ、モデル、その他の大きなアセットは通常、ビルドには必要ありません。
• モジュール zip ファイル内の各ファイルは、$module@$version/ で始まるプレフィックスを持たなければなりません。ここで、$module はモジュールパス、$version はバージョンです。たとえば、golang.org/x/[email protected]/ のようになります。モジュールパスは有効でなければならず、バージョンは有効かつ標準的であり、バージョンはモジュールパスのメジャーバージョンサフィックスと一致しなければなりません。具体的な定義と制約については、モジュールパスとバージョンを参照してください。
• ファイルモード、タイムスタンプ、およびその他のメタデータは無視されます。
• 空のディレクトリ（スラッシュで終わるパスのエントリ）はモジュール zip ファイルに含めることができますが、抽出されません。go コマンドは、作成する zip ファイルに空のディレクトリを含めません。
• シンボリックリンクやその他の不規則なファイルは、zip ファイルを作成する際に無視されます。これらはオペレーティングシステムやファイルシステム間でポータブルではなく、zip ファイル形式で表現するポータブルな方法がありません。
• vendor という名前のディレクトリ内のファイルは、zip ファイルを作成する際に無視されます。vendor ディレクトリはメインモジュールの外では決して使用されません。
• モジュールのルートディレクトリ以外の go.mod ファイルを含むディレクトリ内のファイルは、zip ファイルを作成する際に無視されます。go コマンドは、zip ファイルを抽出する際に go.mod ファイルを含むサブディレクトリを無視します。
• zip ファイル内の2つのファイルは、Unicode のケースフォールディングの下でパスが等しくなってはなりません（strings.EqualFoldを参照）。これにより、zip ファイルは大文字と小文字を区別しないファイルシステムで衝突なく抽出できることが保証されます。
• go.mod ファイルは、トップレベルディレクトリ（$module@$version/go.mod）に存在する場合があります。存在する場合は、go.mod という名前でなければなりません（すべて小文字）。go.mod という名前のファイルは他のディレクトリには許可されていません。
• モジュール内のファイルおよびディレクトリ名は、Unicode 文字、ASCII 数字、ASCII スペース文字 (U+0020)、および ASCII 句読点 !#$%&()+,-.=@[]^_{}~ で構成できます。パッケージパスにはこれらのすべての文字を含めることはできません。module.CheckFilePath と module.CheckImportPath の違いを参照してください。
• 最初のドットまでのファイルまたびディレクトリ名は、Windows で予約されたファイル名であってはなりません（CON、com1、NuL など）。
  

プライベートモジュール

Go モジュールは、公共インターネットで利用できないバージョン管理サーバーやモジュールプロキシで頻繁に開発および配布されます。go コマンドはプライベートソースからモジュールをダウンロードしてビルドできますが、通常は何らかの設定が必要です。

以下の環境変数を使用して、プライベートモジュールへのアクセスを構成できます。詳細については、環境変数を参照してください。また、プライバシーを参照して、公共サーバーに送信される情報を制御する方法についての情報を確認してください。

• GOPROXY — モジュールプロキシの URL のリスト。go コマンドは、各サーバーから順番にモジュールをダウンロードしようとします。キーワード direct は、go コマンドに、プロキシを使用するのではなく、開発されているバージョン管理リポジトリからモジュールをダウンロードするよう指示します。
• GOPRIVATE — プライベートと見なされるべきモジュールパスプレフィックスのグロブパターンのリスト。GONOPROXY および GONOSUMDB のデフォルト値として機能します。
• GONOPROXY — プロキシからダウンロードされるべきでないモジュールパスプレフィックスのグロブパターンのリスト。go コマンドは、GOPROXY に関係なく、開発されているバージョン管理リポジトリから一致するモジュールをダウンロードします。
• GONOSUMDB — 公共のチェックサムデータベース sum.golang.org を使用してチェックされるべきでないモジュールパスプレフィックスのグロブパターンのリスト。
• GOINSECURE — HTTP およびその他の安全でないプロトコルを介して取得できるモジュールパスプレフィックスのグロブパターンのリスト。

これらの変数は、開発環境（たとえば、.profile ファイル内）で設定するか、go env -w を使用して永続的に設定できます。

このセクションの残りの部分では、プライベートモジュールプロキシおよびバージョン管理リポジトリへのアクセスを提供するための一般的なパターンについて説明します。

すべてのモジュールを提供するプライベートプロキシ

すべてのモジュール（公開およびプライベート）を提供する中央のプライベートプロキシサーバーは、管理者に最も多くの制御を提供し、個々の開発者にとって最も少ない設定を必要とします。

go コマンドをそのようなサーバーを使用するように構成するには、次の環境変数を設定し、https://proxy.corp.example.com をプロキシの URL に、corp.example.com をモジュールプレフィックスに置き換えます：

GOPROXY=https://proxy.corp.example.com
GONOSUMDB=corp.example.com

GOPROXY 設定は、go コマンドに https://proxy.corp.example.com からのみモジュールをダウンロードするよう指示します。go コマンドは他のプロキシやバージョン管理リポジトリに接続しません。

GONOSUMDB 設定は、go コマンドに corp.example.com で始まるパスのモジュールを認証するために公共のチェックサムデータベースを使用しないよう指示します。

この構成で実行されるプロキシは、プライベートバージョン管理サーバーへの読み取りアクセスが必要になる可能性があります。また、公共モジュールの新しいバージョンをダウンロードするために公共インターネットへのアクセスも必要です。

この方法で使用できる既存の GOPROXY サーバーの実装がいくつかあります。最小限の実装は、モジュールキャッシュ ディレクトリからファイルを提供し、go mod download（適切な設定を使用）を使用して不足しているモジュールを取得します。

プライベートモジュールを提供するプライベートプロキシ

プライベートプロキシサーバーは、公開利用可能なモジュールを提供せずにプライベートモジュールを提供できます。go コマンドは、プライベートサーバーで利用できないモジュールのために公共ソースにフォールバックするように構成できます。

go コマンドをこのように機能するように構成するには、次の環境変数を設定し、https://proxy.corp.example.com をプロキシの URL に、corp.example.com をモジュールプレフィックスに置き換えます：

GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct
GONOSUMDB=corp.example.com

GOPROXY 設定は、go コマンドに https://proxy.corp.example.com から最初にモジュールをダウンロードしようとするよう指示します。そのサーバーが 404 (Not Found) または 410 (Gone) で応答した場合、go コマンドは https://proxy.golang.org にフォールバックし、その後リポジトリへの直接接続にフォールバックします。

GONOSUMDB 設定は、go コマンドに corp.example.com で始まるパスのモジュールを認証するために公共のチェックサムデータベースを使用しないよう指示します。

この構成で使用されるプロキシは、公開モジュールへのアクセスを制御することができる場合がありますが、それらを提供しません。プロキシが 404 または 410 以外のエラーステータスでリクエストに応答した場合、go コマンドは GOPROXY リストの後のエントリにフォールバックしません。たとえば、プロキシは不適切なライセンスや既知のセキュリティ脆弱性を持つモジュールに対して 403 (Forbidden) で応答する可能性があります。

プライベートモジュールへの直接アクセス

go コマンドは、公共プロキシをバイパスして、バージョン管理サーバーからプライベートモジュールを直接ダウンロードするように構成できます。これは、プライベートプロキシサーバーを実行することが不可能な場合に便利です。

go コマンドをこのように機能するように構成するには、GOPRIVATE を設定し、corp.example.com プライベートモジュールプレフィックスを置き換えます：

GOPRIVATE=corp.example.com

GOPROXY 変数はこの状況で変更する必要はありません。デフォルトでは https://proxy.golang.org,direct で、go コマンドに https://proxy.golang.org から最初にモジュールをダウンロードし、その後そのプロキシが 404 (Not Found) または 410 (Gone) で応答した場合に直接接続にフォールバックするよう指示します。

GOPRIVATE 設定は、go コマンドに corp.example.com で始まるモジュールのためにプロキシやチェックサムデータベースに接続しないよう指示します。

モジュールパスをリポジトリの URL に解決するために内部 HTTP サーバーが必要になる場合があります。たとえば、go コマンドがモジュール corp.example.com/mod をダウンロードするとき、https://corp.example.com/mod?go-get=1 に GET リクエストを送信し、応答内でリポジトリの URL を探します。この要件を回避するには、各プライベートモジュールパスにリポジトリルートプレフィックスを示す VCS サフィックス（.git など）を持たせる必要があります。たとえば、go コマンドがモジュール corp.example.com/repo.git/mod をダウンロードするとき、https://corp.example.com/repo.git または ssh://corp.example.com/repo.git で Git リポジトリをクローンし、追加のリクエストを行う必要はありません。

開発者はプライベートモジュールを含むリポジトリへの読み取りアクセスが必要です。これは、.gitconfig のようなグローバル VCS 設定ファイルで構成できます。VCS ツールが対話的な認証プロンプトを必要としないように設定されているのが最善です。デフォルトでは、Git を呼び出すとき、go コマンドは GIT_TERMINAL_PROMPT=0 を設定することで対話的プロンプトを無効にしますが、明示的な設定は尊重されます。

プライベートプロキシへの資格情報の渡し方

go コマンドは、プロキシサーバーとの通信時に HTTP 基本認証 をサポートしています。

資格情報は、.netrc ファイル に指定できます。たとえば、以下の行を含む .netrc ファイルは、go コマンドが指定されたユーザー名とパスワードで proxy.corp.example.com マシンに接続するように構成します。

machine proxy.corp.example.com
login jrgopher
password hunter2

ファイルの場所は NETRC 環境変数で設定できます。NETRC が設定されていない場合、go コマンドは UNIX 系プラットフォームでは $HOME/.netrc を、Windows では %USERPROFILE%\_netrc を読み取ります。

.netrc のフィールドは、スペース、タブ、および改行で区切られています。残念ながら、これらの文字はユーザー名やパスワードに使用できません。また、マシン名は完全な URL であってはならず、同じマシンの異なるパスに対して異なるユーザー名やパスワードを指定することはできません。

また、資格情報を GOPROXY URL に直接指定することもできます。たとえば：

GOPROXY=https://jrgopher:hunter2@proxy.corp.example.com

このアプローチを取る際は注意が必要です：環境変数はシェルの履歴やログに表示される可能性があります。

イントロダクション

モジュールは、Goが依存関係を管理する方法です。

この文書は、Goのモジュールシステムに関する詳細なリファレンスマニュアルです。Goプロジェクトの作成に関する紹介については、Goコードの書き方を参照してください。モジュールの使用、プロジェクトのモジュールへの移行、その他のトピックに関する情報については、Goモジュールの使用から始まるブログシリーズを参照してください。

プライバシー

go コマンドは、モジュールプロキシサーバーおよびバージョン管理システムからモジュールとメタデータをダウンロードできます。環境変数 GOPROXY は、使用されるサーバーを制御します。環境変数 GOPRIVATE および GONOPROXY は、プロキシから取得されるモジュールを制御します。

GOPROXY のデフォルト値は次のとおりです：

https://proxy.golang.org,direct

この設定では、go コマンドがモジュールまたはモジュールメタデータをダウンロードする際、最初に proxy.golang.org にリクエストを送信します。これは、Google が運営する公共のモジュールプロキシです（プライバシーポリシー）。GOPROXY プロトコルの詳細については、各リクエストで送信される情報を参照してください。go コマンドは個人を特定できる情報を送信しませんが、要求されている完全なモジュールパスは送信します。プロキシが 404 (Not Found) または 410 (Gone) ステータスで応答した場合、go コマンドはモジュールを提供するバージョン管理システムに直接接続しようとします。詳細については、バージョン管理システムを参照してください。

``````bash
GOPRIVATE=*.corp.example.com,*.research.example.com
`

GOPRIVATE は、GONOPROXY および GONOSUMDB のデフォルトとして機能するため、GONOPROXY を設定する必要はありません。GONOSUMDB が異なる値を持つべきでない限り、GONOPROXY に一致するモジュールパスがある場合、go コマンドはそのモジュールに対して GOPROXY を無視し、バージョン管理リポジトリから直接取得します。これは、プロキシがプライベートモジュールを提供しない場合に便利です。プライベートモジュールへの直接アクセスを参照してください。

すべてのモジュールを提供する信頼できるプロキシがある場合、GONOPROXY を設定するべきではありません。たとえば、GOPROXY が1つのソースに設定されている場合、go コマンドは他のソースからモジュールをダウンロードしません。この状況でも GONOSUMDB は設定する必要があります。

GOPROXY=https://proxy.corp.example.com
GONOSUMDB=*.corp.example.com,*.research.example.com

公開モジュールのみを提供する信頼できるプロキシがある場合、GONOPROXY を設定するべきではありませんが、プロキシが正しいステータスコードで応答することを確認する必要があります。たとえば、次の構成を考えてみてください：

GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org
GONOSUMDB=*.corp.example.com,*.research.example.com

タイプミスのために、開発者が存在しないモジュールをダウンロードしようとしたとします。

go mod download corp.example.com/secret-product/typo@latest

go コマンドは最初に proxy.corp.example.com からこのモジュールをリクエストします。プロキシが 404 (Not Found) または 410 (Gone) で応答した場合、go コマンドは proxy.golang.org にフォールバックし、リクエスト URL に secret-product パスを送信します。プライベートプロキシが他のエラーコードで応答した場合、go コマンドはエラーを印刷し、他のソースにフォールバックしません。

プロキシに加えて、go コマンドは、go.sum にリストされていないモジュールの暗号ハッシュを検証するためにチェックサムデータベースに接続することがあります。GOSUMDB 環境変数は、チェックサムデータベースの名前、URL、および公開鍵を設定します。GOSUMDB のデフォルト値は sum.golang.org で、Google が運営する公共のチェックサムデータベースです（プライバシーポリシー）。チェックサムデータベースの詳細については、各リクエストで送信される情報を参照してください。プロキシと同様に、go コマンドは個人を特定できる情報を送信しませんが、要求されている完全なモジュールパスは送信され、チェックサムデータベースは非公開モジュールのチェックサムを計算できません。

GONOSUMDB 環境変数は、プライベートであり、チェックサムデータベースからリクエストされるべきでないモジュールを示すパターンに設定できます。GOPRIVATE は GONOSUMDB および GONOPROXY のデフォルトとして機能するため、GONOSUMDB を設定する必要はありません。GONOPROXY が異なる値を持つべきでない限り。

プロキシはチェックサムデータベースをミラーリングすることができます。GOPROXY でこれを行うプロキシがある場合、go コマンドはチェックサムデータベースに直接接続しません。

GOSUMDB は off に設定して、チェックサムデータベースの使用を完全に無効にすることができます。この設定では、go コマンドは、go.sum に既に存在しない限り、ダウンロードされたモジュールを認証しません。 モジュールの認証を参照してください。

モジュールキャッシュ

モジュールキャッシュは、go コマンドがダウンロードしたモジュールファイルを保存するディレクトリです。モジュールキャッシュは、コンパイルされたパッケージやその他のビルドアーティファクトを含むビルドキャッシュとは異なります。

モジュールキャッシュのデフォルトの場所は $GOPATH/pkg/mod です。別の場所を使用するには、GOMODCACHE 環境変数 を設定します。

モジュールキャッシュには最大サイズがなく、go コマンドはその内容を自動的に削除しません。

キャッシュは、同じマシン上で開発された複数の Go プロジェクトによって共有される場合があります。go コマンドは、メインモジュールの場所に関係なく、同じキャッシュを使用します。go コマンドの複数のインスタンスは、安全に同時に同じモジュールキャッシュにアクセスできます。

go コマンドは、ダウンロード後にモジュールに対する偶発的な変更を防ぐために、キャッシュ内に読み取り専用のモジュールソースファイルとディレクトリを作成します。これにより、rm -rf のようなコマンドでキャッシュを削除するのが難しくなるという不幸な副作用があります。代わりに、キャッシュは go clean -modcache で削除できます。あるいは、-modcacherw フラグを使用すると、go コマンドは読み書き権限のある新しいディレクトリを作成します。これにより、エディタ、テスト、およびその他のプログラムがモジュールキャッシュ内のファイルを変更するリスクが高まります。go mod verify コマンドを使用して、メインモジュールの依存関係の変更を検出できます。これは、各モジュール依存関係の抽出された内容をスキャンし、go.sum の期待されるハッシュと一致することを確認します。

以下の表は、モジュールキャッシュ内のほとんどのファイルの目的を説明しています。一部の一時ファイル（ロックファイル、一時ディレクトリ）は省略されています。各パスに対して、$module はモジュールパスで、$version はバージョンです。スラッシュで終わるパス（/）はディレクトリです。モジュールパスとバージョンの大文字は、感度のないファイルシステムでの競合を避けるために感嘆符でエスケープされます（Azure は !azure としてエスケープされます）。

モジュールの認証

go コマンドがモジュール ZIP ファイル または go.mod ファイル を モジュールキャッシュ にダウンロードすると、暗号ハッシュを計算し、既知の値と比較してファイルが最初にダウンロードされて以来変更されていないことを確認します。go コマンドは、ダウンロードされたファイルに正しいハッシュがない場合、セキュリティエラーを報告します。

go.mod ファイルの場合、go コマンドはファイルの内容からハッシュを計算します。モジュール ZIP ファイルの場合、go コマンドはアーカイブ内のファイルの名前と内容から決定論的な順序でハッシュを計算します。ハッシュはファイルの順序、圧縮、整列、およびその他のメタデータの影響を受けません。ハッシュの実装の詳細については、golang.org/x/mod/sumdb/dirhash を参照してください。

go コマンドは、各ハッシュをメインモジュールの go.sum ファイル の対応する行と比較します。ハッシュが go.sum のハッシュと異なる場合、go コマンドはセキュリティエラーを報告し、ダウンロードされたファイルをモジュールキャッシュに追加せずに削除します。

go.sum ファイルが存在しない場合、またはダウンロードされたファイルのハッシュが含まれていない場合、go コマンドは チェックサムデータベース を使用してハッシュを検証することがあります。これは、公開されているモジュールのハッシュのグローバルソースです。ハッシュが検証されると、go コマンドはそれを go.sum に追加し、ダウンロードされたファイルをモジュールキャッシュに追加します。モジュールがプライベートである場合（GOPRIVATE または GONOSUMDB 環境変数によって一致する）か、チェックサムデータベースが無効になっている場合（GOSUMDB=off を設定することによって）、go コマンドはハッシュを受け入れ、検証せずにファイルをモジュールキャッシュに追加します。

モジュールキャッシュは通常、システム上のすべての Go プロジェクトによって共有され、各モジュールは異なるハッシュを持つ go.sum ファイルを持つ可能性があります。他のモジュールを信頼する必要がないようにするために、go コマンドは、モジュールキャッシュ内のファイルにアクセスするたびにメインモジュールの go.sum を使用してハッシュを検証します。ZIP ファイルのハッシュは計算が高価であるため、go コマンドは、ファイルを再ハッシュするのではなく、ZIP ファイルと一緒に保存された事前計算されたハッシュをチェックします。go mod verify コマンドを使用して、ZIP ファイルと抽出されたディレクトリがモジュールキャッシュに追加されて以来変更されていないことを確認できます。

go.sum ファイル

モジュールは、ルートディレクトリに go.sum という名前のテキストファイルを持つことがあります。これは go.mod ファイルと並んでいます。go.sum ファイルには、モジュールの直接および間接の依存関係の暗号ハッシュが含まれています。go コマンドがモジュール .mod または .zip ファイルを モジュールキャッシュ にダウンロードすると、ハッシュを計算し、そのハッシュがメインモジュールの go.sum ファイルの対応するハッシュと一致することを確認します。go.sum は、モジュールに依存関係がない場合や、すべての依存関係が replace 指示 を使用してローカルディレクトリに置き換えられている場合、空または存在しない場合があります。

go.sum の各行には、スペースで区切られた 3 つのフィールドがあります：モジュールパス、バージョン（/go.mod で終わる可能性があります）、およびハッシュ。

• モジュールパスは、ハッシュが属するモジュールの名前です。
• バージョンは、ハッシュが属するモジュールのバージョンです。バージョンが /go.mod で終わる場合、ハッシュはモジュールの go.mod ファイルのみに対応します。それ以外の場合、ハッシュはモジュールの .zip ファイル内のファイルに対応します。
• ハッシュ列は、アルゴリズム名（h1 のような）とコロン（:）で区切られた base64 エンコードされた暗号ハッシュで構成されています。現在、SHA-256（h1）が唯一サポートされているハッシュアルゴリズムです。将来的に SHA-256 に脆弱性が発見された場合、別のアルゴリズム（h2 など）がサポートされるようになります。

go.sum ファイルには、モジュールの複数のバージョンのハッシュが含まれている場合があります。go コマンドは、最小バージョン選択 を実行するために、依存関係の複数のバージョンから go.mod ファイルを読み込む必要がある場合があります。go.sum には、もはや必要ないモジュールバージョンのハッシュが含まれている場合もあります（たとえば、アップグレード後）。go mod tidy は、欠落しているハッシュを追加し、go.sum から不要なハッシュを削除します。

チェックサムデータベース

チェックサムデータベースは、go.sum 行のグローバルソースです。go コマンドは、プロキシやオリジンサーバーの不正行為を検出するために、さまざまな状況でこれを使用できます。

チェックサムデータベースは、すべての公開モジュールバージョンのグローバルな一貫性と信頼性を提供します。これにより、信頼できないプロキシが可能になり、間違ったコードを提供しても気づかれないことはありません。また、特定のバージョンに関連付けられたビットが、モジュールの著者がリポジトリ内のタグを変更した場合でも、1 日から次の日にかけて変更されないことを保証します。

チェックサムデータベースは、sum.golang.org によって提供され、Google によって運営されています。これは、go.sum 行のハッシュの 透明ログ（または「マークルツリー」）であり、Trillian によってバックアップされています。マークルツリーの主な利点は、独立した監査人が改ざんされていないことを確認できるため、単純なデータベースよりも信頼性が高いことです。

go コマンドは、提案: 公共の Go モジュールエコシステムを保護する で最初に概説されたプロトコルを使用して、チェックサムデータベースと対話します。

以下の表は、チェックサムデータベースが応答する必要があるクエリを指定します。各パスに対して、$base はチェックサムデータベース URL のパス部分、$module はモジュールパス、$version はバージョンです。たとえば、チェックサムデータベース URL が https://sum.golang.org で、クライアントがバージョン v0.3.2 のモジュール golang.org/x/text のレコードを要求している場合、クライアントは GET リクエストを https://sum.golang.org/lookup/golang.org/x/[email protected] に送信します。

大文字と小文字を区別しないファイルシステムから提供する際の曖昧さを避けるために、$module および $version 要素は、すべての大文字を感嘆符と対応する小文字に置き換えることによって ケースエンコード されています。これにより、モジュール example.com/M と example.com/m の両方をディスクに保存できるようになります。前者は example.com/!m としてエンコードされます。

角括弧で囲まれたパスの一部は、[.p/$W] のようにオプションの値を示します。

go コマンドがチェックサムデータベースに相談する場合、最初のステップは /lookup エンドポイントを介してレコードデータを取得することです。モジュールバージョンがまだログに記録されていない場合、チェックサムデータベースは応答する前にオリジンサーバーから取得しようとします。この /lookup データは、このモジュールバージョンの合計とログ内の位置を提供し、クライアントにどのタイルを取得する必要があるかを通知します。go コマンドは、「包含」証明（特定のレコードがログに存在すること）と「一貫性」証明（ツリーが改ざんされていないこと）を実行してから、メインモジュールの go.sum ファイルに新しい go.sum 行を追加します。/lookup からのデータは、署名されたツリーハッシュに対して認証され、署名されたツリーハッシュはクライアントの署名されたツリーハッシュのタイムラインに対して認証されるまで使用されるべきではないことが重要です。

署名されたツリーハッシュとチェックサムデータベースによって提供される新しいタイルはモジュールキャッシュに保存されるため、go コマンドは欠落しているタイルのみを取得する必要があります。

go コマンドは、チェックサムデータベースに直接接続する必要はありません。モジュールプロキシを介してモジュールの合計を要求でき、これは チェックサムデータベースをミラーリング し、上記のプロトコルをサポートします。これは、組織外のリクエストをブロックするプライベートな企業プロキシに特に役立ちます。

GOSUMDB 環境変数は、使用するチェックサムデータベースの名前を識別し、オプションでその公開鍵と URL を指定します。たとえば：

GOSUMDB="sum.golang.org"
GOSUMDB="sum.golang.org+<publickey>"
GOSUMDB="sum.golang.org+<publickey> https://sum.golang.org"

go コマンドは sum.golang.org の公開鍵を知っており、sum.golang.google.cn（中国本土内で利用可能）が sum.golang.org チェックサムデータベースに接続することも知っています。他のデータベースを使用するには、公開鍵を明示的に指定する必要があります。URL は https:// にデータベース名が続くことがデフォルトです。

GOSUMDB は sum.golang.org にデフォルトで、Google によって運営される Go チェックサムデータベースです。サービスのプライバシーポリシーについては、https://sum.golang.org/privacy を参照してください。

GOSUMDB が off に設定されている場合、または go get が -insecure フラグで呼び出される場合、チェックサムデータベースは参照されず、すべての未認識モジュールが受け入れられ、すべてのモジュールの検証可能な再現可能なダウンロードのセキュリティ保証が放棄されます。特定のモジュールに対してチェックサムデータベースをバイパスするより良い方法は、GOPRIVATE または GONOSUMDB 環境変数を使用することです。詳細については、プライベートモジュール を参照してください。

go env -w コマンドは、将来の go コマンドの呼び出しのために これらの変数を設定する ために使用できます。

環境変数

go コマンドのモジュールの動作は、以下に示す環境変数を使用して構成できます。このリストには、モジュールに関連する環境変数のみが含まれています。go help environment [https://golang.org/cmd/go/#hdr-Environment_variables] のリストを参照して、go コマンドによって認識されるすべての環境変数を確認してください。