Git
日本語 ▾ トピック ▾ 最新バージョン ▾ git-submodule は 2.47.0 で最終更新

名前

git-submodule - サブモジュールの初期化、更新、検査

概要

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…​]
git submodule [--quiet] init [--] [<path>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>…​)
git submodule [--quiet] update [<options>] [--] [<path>…​]
git submodule [--quiet] set-branch [<options>] [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
git submodule [--quiet] summary [<options>] [--] [<path>…​]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>…​]
git submodule [--quiet] absorbgitdirs [--] [<path>…​]

説明

サブモジュールの検査、更新、管理を行います。

サブモジュールに関する詳細については、gitsubmodules[7] を参照してください。

コマンド

引数なしで実行すると、既存のサブモジュールの状態が表示されます。サブモジュールに対する操作を実行するためのいくつかのサブコマンドが利用可能です。

add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

指定されたリポジトリを、次のコミット対象の変更セットに、指定されたパスのサブモジュールとして現在のプロジェクト（「スーパープロジェクト」と呼ばれる）に追加します。

<repository> は、新しいサブモジュールのオリジンリポジトリの URL です。これは絶対 URL でも、(./ または ../ で始まる場合は) スーパープロジェクトのデフォルトのリモートリポジトリに対する相対的な場所でもかまいません (相対 URL の規則に従うと予想されるかもしれませんが、スーパープロジェクト *bar.git* のすぐ隣にあるリポジトリ *foo.git* を指定するには、`./foo.git` ではなく `../foo.git` を使用する必要があることに注意してください。これは、Git における相対 URL の評価が相対ディレクトリの評価と同じであるためです)。

デフォルトのリモートは、現在のブランチのリモート追跡ブランチのリモートです。そのようなリモート追跡ブランチが存在しない場合、または HEAD が切り離されている場合は、"origin" がデフォルトのリモートとみなされます。スーパープロジェクトにデフォルトのリモートが設定されていない場合、スーパープロジェクト自体が認証されたアップストリームとなり、代わりに現在の作業ディレクトリが使用されます。

オプションの引数 <path> は、クローンされたサブモジュールがスーパープロジェクト内に存在する相対的な場所です。<path> が指定されていない場合、ソースリポジトリの正規部分が使用されます ("/path/to/repo.git" の場合は "repo"、"host.xz:foo/.git" の場合は "foo")。<path> が存在し、既に有効な Git リポジトリである場合、クローンせずにコミットのためにステージングされます。また、`--name` を使用して論理名を指定しない限り、<path> は構成エントリのサブモジュールの論理名としても使用されます。

指定された URL は、スーパープロジェクトをクローンする後続のユーザーが使用できるように、`.gitmodules` に記録されます。URL がスーパープロジェクトのリポジトリに対して相対的に指定されている場合、スーパープロジェクトとサブモジュールリポジトリは同じ相対的な場所にまとめて保管されると推定され、スーパープロジェクトの URL のみを提供する必要があります。git-submodule は、`.gitmodules` の相対 URL を使用してサブモジュールを正しく検出します。

`--ref-format <format>` が指定されている場合、新しくクローンされたサブモジュールの ref ストレージ形式がそれに応じて設定されます。

status [--cached] [--recursive] [--] [<path>…​]

サブモジュールの状態を表示します。これにより、各サブモジュールの現在チェックアウトされているコミットの SHA-1、サブモジュールのパス、および SHA-1 の *git describe* の出力が表示されます。各 SHA-1 は、サブモジュールが初期化されていない場合は `-`、現在チェックアウトされているサブモジュールコミットが包含リポジトリのインデックスにある SHA-1 と一致しない場合は `+`、サブモジュールにマージ競合がある場合は `U` が接頭辞として付く場合があります。

`--cached` が指定されている場合、このコマンドは代わりに各サブモジュールのスーパープロジェクトに記録されている SHA-1 を出力します。

`--recursive` が指定されている場合、このコマンドは入れ子になったサブモジュールに再帰し、その状態も表示します。

インデックスまたは HEAD に記録されたコミットに対する現在初期化されているサブモジュールの変更のみに関心がある場合は、git-status[1] および git-diff[1] もその情報を提供します (また、サブモジュールの作業ツリーへの変更も報告できます)。

init [--] [<path>…​]

`.gitmodules` からの同じ設定をテンプレートとして使用して、`.git/config` に `submodule.$name.url` を設定することにより、(別の場所で追加およびコミットされた) インデックスに記録されたサブモジュールを初期化します。URL が相対的な場合、デフォルトのリモートを使用して解決されます。デフォルトのリモートがない場合、現在のリポジトリがアップストリームであると想定されます。

オプションの <path> 引数は、初期化されるサブモジュールを制限します。パスが指定されておらず、submodule.active が設定されている場合、アクティブになるように設定されたサブモジュールが初期化されます。それ以外の場合は、すべてのサブモジュールが初期化されます。

また、`.gitmodules` ファイルに存在する場合は、`submodule.$name.update` の値が `.git/config` にコピーされますが、(1) このコマンドは `.git/config` の既存の情報を変更せず、(2) カスタムコマンドに設定されている `submodule.$name.update` はセキュリティ上の理由からコピー**されません**。

その後、ローカル設定用に `.git/config` のサブモジュールクローン URL をカスタマイズし、`git submodule update` に進むことができます。サブモジュールの場所をカスタマイズする予定がない場合は、明示的な *init* ステップなしで `git submodule update --init` を使用することもできます。

デフォルトのリモートの定義については、add サブコマンドを参照してください。

deinit [-f|--force] (--all|[--] <path>…​)

指定されたサブモジュールを登録解除します。つまり、`.git/config` から `submodule.$name` セクション全体を、その作業ツリーとともに削除します。`git submodule update`、`git submodule foreach`、および `git submodule sync` の後続の呼び出しは、再び初期化されるまで、登録解除されたサブモジュールをスキップするため、作業ツリーにサブモジュールのローカルチェックアウトをもう必要としない場合は、このコマンドを使用します。

このコマンドが pathspec なしで実行されると、すべてを登録解除する代わりにエラーが発生し、誤りを防ぎます。

`--force` が指定されている場合、サブモジュールの作業ツリーにローカルな変更が含まれている場合でも削除されます。

リポジトリからサブモジュールを実際に削除してコミットする場合は、代わりに git-rm[1] を使用してください。削除オプションについては、gitsubmodules[7] を参照してください。

update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]

不足しているサブモジュールをクローンし、サブモジュールで不足しているコミットをフェッチし、サブモジュールの作業ツリーを更新することにより、スーパープロジェクトが期待するものと一致するように、登録されたサブモジュールを更新します。「更新」は、コマンドラインオプションと `submodule.<name>.update` 設定変数の値に応じて、いくつかの方法で実行できます。コマンドラインオプションは設定変数よりも優先されます。どちらも指定されていない場合は、*checkout* が実行されます。(注: `.gitmodules` ファイルの内容は、この時点では無関係です。`.gitmodules` の使用方法については、上記の `git submodule init` を参照してください)。コマンドラインと `submodule.<name>.update` 設定の両方でサポートされている *update* 手順は次のとおりです。

checkout

スーパープロジェクトに記録されたコミットが、切り離された HEAD 上のサブモジュールでチェックアウトされます。

`--force` が指定されている場合、包含リポジトリのインデックスで指定されたコミットがサブモジュールでチェックアウトされたコミットと既に一致している場合でも、サブモジュールが ( `git checkout --force` を使用して) チェックアウトされます。

rebase

サブモジュールの現在のブランチが、スーパープロジェクトに記録されたコミットにリベースされます。

merge

スーパープロジェクトに記録されたコミットが、サブモジュールの現在のブランチにマージされます。

次の更新手順には、追加の制限があります

カスタムコマンド

コミットIDを引数として任意のコマンドを実行するメカニズムです。具体的には、submodule.<name>.update 設定変数が !custom command に設定されている場合、サブモジュール用にスーパープロジェクトに記録されたコミットのオブジェクト名が custom command 文字列に追加され、実行されます。このメカニズムは、.gitmodules ファイルやコマンドラインではサポートされていないことに注意してください。

なし

サブモジュールは更新されません。この更新手順はコマンドラインでは許可されていません。

サブモジュールがまだ初期化されておらず、.gitmodules に保存されている設定をそのまま使用したい場合は、--init オプションを使用するとサブモジュールを自動的に初期化できます。

--recursive が指定されている場合、このコマンドは登録されたサブモジュールを再帰的に処理し、内部のネストされたサブモジュールもすべて更新します。

`--ref-format <format>` が指定されている場合、新しくクローンされたサブモジュールの ref ストレージ形式がそれに応じて設定されます。

--filter <filter-spec> が指定された場合、指定された部分クローンフィルターがサブモジュールに適用されます。フィルター仕様の詳細については、git-rev-list[1]を参照してください。

set-branch (-b|--branch) <branch> [--] <path>
set-branch (-d|--default) [--] <path>

サブモジュールのデフォルトのリモート追跡ブランチを設定します。--branch オプションを使用すると、リモートブランチを指定できます。--default オプションは、submodule.<name>.branch 設定キーを削除します。これにより、追跡ブランチはリモートの *HEAD* がデフォルトになります。

set-url [--] <path> <newurl>

指定されたサブモジュールのURLを <newurl> に設定します。その後、サブモジュールの新しいリモートURL設定を自動的に同期します。

summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>…​]

指定されたコミット（デフォルトはHEAD）と作業ツリー/インデックスの間のコミットの概要を表示します。問題のサブモジュールについては、指定されたスーパープロジェクトのコミットとインデックスまたは作業ツリー（--cached で切り替え）の間のサブモジュール内のコミットのシリーズが表示されます。--files オプションが指定されている場合、スーパープロジェクトのインデックスとサブモジュールの作業ツリーの間のサブモジュール内のコミットのシリーズが表示されます（このオプションでは、--cached オプションを使用したり、明示的なコミットを指定したりすることはできません）。

git-diff[1] で --submodule=log オプションを使用すると、その情報も提供されます。

foreach [--recursive] <command>

チェックアウトされた各サブモジュールで任意のシェルコマンドを評価します。コマンドは、変数 $name、$sm_path、$displaypath、$sha1、および $toplevel にアクセスできます。$name は .gitmodules 内の関連するサブモジュールセクションの名前、$sm_path は直近のスーパープロジェクトに記録されているサブモジュールのパス、$displaypath は現在の作業ディレクトリからサブモジュールのルートディレクトリへの相対パス、$sha1 は直近のスーパープロジェクトに記録されているコミット、$toplevel は直近のスーパープロジェクトの最上位への絶対パスです。Windows での *\$PATH* との競合を避けるために、*\$path* 変数は非推奨となり、*\$sm_path* 変数のシノニムになりました。スーパープロジェクトで定義されているがチェックアウトされていないサブモジュールは、このコマンドでは無視されます。--quiet が指定されていない限り、foreach はコマンドを評価する前に各サブモジュールの名前を出力します。--recursive が指定されている場合、サブモジュールは再帰的にトラバースされます（つまり、指定されたシェルコマンドはネストされたサブモジュールでも評価されます）。いずれかのサブモジュールでコマンドがゼロ以外の値を返すと、処理が終了します。これは、コマンドの最後に *|| :* を追加することで上書きできます。

例として、以下のコマンドは、各サブモジュールのパスと現在チェックアウトされているコミットを表示します。

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<path>…​]

サブモジュールのリモートURL設定を、.gitmodules で指定された値に同期します。これは、.git/config にURLエントリが既にあるサブモジュール（初期化された場合、または新しく追加された場合）にのみ影響します。これは、サブモジュールのURLが上流で変更された場合や、それに応じてローカルリポジトリを更新する必要がある場合に役立ちます。

git submodule sync はすべてのサブモジュールを同期しますが、git submodule sync -- A はサブモジュール "A" のみを同期します。

--recursive が指定されている場合、このコマンドは登録されたサブモジュールを再帰的に処理し、内部のネストされたサブモジュールもすべて同期します。

absorbgitdirs

サブモジュールのgitディレクトリがサブモジュール内にある場合、サブモジュールのgitディレクトリをスーパープロジェクトの $GIT_DIR/modules パスに移動し、core.worktree を設定し、スーパープロジェクトのgitディレクトリに埋め込まれたgitディレクトリを指す .git ファイルを追加して、gitディレクトリとその作業ディレクトリを接続します。

独立してクローンされ、後でサブモジュールとして追加されたリポジトリ、または古い設定では、サブモジュールのgitディレクトリがスーパープロジェクトのgitディレクトリに埋め込まれるのではなく、サブモジュール内にあります。

このコマンドはデフォルトで再帰的です。

オプション

-q
--quiet

エラーメッセージのみを出力します。

--progress

このオプションは、addおよびupdateコマンドでのみ有効です。デフォルトでは、標準エラーストリームがターミナルに接続されている場合、-qが指定されていない限り、進行状況が報告されます。このフラグは、標準エラーストリームがターミナルにリダイレクトされていない場合でも、進行状況を強制します。

--all

このオプションは、deinitコマンドでのみ有効です。ワーキングツリー内のすべてのサブモジュールの登録を解除します。

-b <branch>
--branch <branch>

サブモジュールとして追加するリポジトリのブランチ。ブランチの名前は、update --remote 用に .gitmodules に submodule.<name>.branch として記録されます。特別な値の . は、サブモジュール内のブランチの名前が、現在のリポジトリの現在のブランチと同じ名前である必要があることを示すために使用されます。このオプションが指定されていない場合は、リモートの *HEAD* がデフォルトになります。

-f
--force

このオプションは、add、deinit、およびupdateコマンドでのみ有効です。addを実行する場合、それ以外の場合は無視されるサブモジュールパスの追加を許可します。deinitを実行する場合、ローカルの変更が含まれていてもサブモジュールのワーキングツリーは削除されます。updateを実行する場合（チェックアウト手順でのみ有効）、別のコミットに切り替えるときにサブモジュール内のローカルの変更を破棄します。また、包含リポジトリのインデックスにリストされているコミットがサブモジュールでチェックアウトされたコミットと一致する場合でも、常にサブモジュールでチェックアウト操作を実行します。

--cached

このオプションは、statusおよびsummaryコマンドでのみ有効です。これらのコマンドは通常、サブモジュールHEADにあるコミットを使用しますが、このオプションを指定すると、インデックスに保存されているコミットが代わりに使用されます。

--files

このオプションは、summaryコマンドでのみ有効です。このオプションを使用すると、このコマンドはインデックス内のコミットとサブモジュールHEAD内のコミットを比較します。

-n
--summary-limit

このオプションは、summaryコマンドでのみ有効です。概要サイズ（合計で表示されるコミット数）を制限します。0を指定すると概要が無効になり、負の数を指定すると無制限（デフォルト）になります。この制限は、変更されたサブモジュールにのみ適用されます。サイズは、追加/削除/タイプ変更されたサブモジュールの場合、常に1に制限されます。

--remote

このオプションは、updateコマンドでのみ有効です。サブモジュールを更新するためにスーパープロジェクトの記録されたSHA-1を使用する代わりに、サブモジュールのリモート追跡ブランチのステータスを使用します。使用されるリモートはブランチのリモート (branch.<name>.remote) で、デフォルトは origin です。使用されるリモートブランチのデフォルトはリモート HEAD ですが、ブランチ名は .gitmodules または .git/config のいずれかで submodule.<name>.branch オプションを設定することでオーバーライドできます (.git/config が優先されます)。

これは、サポートされている任意の更新手順 (--checkout、--rebase など) で機能します。唯一の変更点は、ターゲットSHA-1のソースです。たとえば、submodule update --remote --merge は、上流のサブモジュールの変更をサブモジュールにマージしますが、submodule update --merge は、スーパープロジェクトのgitlinkの変更をサブモジュールにマージします。

現在の追跡ブランチの状態を確実にするために、update --remote は、SHA-1を計算する前にサブモジュールのリモートリポジトリをフェッチします。フェッチしたくない場合は、submodule update --remote --no-fetch を使用する必要があります。

このオプションを使用して、上流のサブプロジェクトからの変更をサブモジュールの現在のHEADに統合します。または、サブモジュールから git pull を実行することもできます。これはリモートブランチ名を除いて同じです。update --remote は、デフォルトの上流リポジトリと submodule.<name>.branch を使用しますが、git pull はサブモジュールの branch.<name>.merge を使用します。スーパープロジェクトでデフォルトの上流ブランチを配布する場合は submodule.<name>.branch を優先し、サブモジュール自体で作業中にさらにネイティブな感じを求める場合は branch.<name>.merge を優先します。

-N
--no-fetch

このオプションは、updateコマンドでのみ有効です。リモートサイトから新しいオブジェクトをフェッチしないでください。

--checkout

このオプションは、updateコマンドでのみ有効です。サブモジュール内のデタッチされたHEADでスーパープロジェクトに記録されたコミットをチェックアウトします。これがデフォルトの動作であり、このオプションの主な用途は、submodule.$name.update が checkout 以外の値に設定されている場合にそれをオーバーライドすることです。キー submodule.$name.update が明示的に設定されていないか、checkout に設定されている場合、このオプションは暗黙的です。

--merge

このオプションは、updateコマンドでのみ有効です。スーパープロジェクトに記録されたコミットをサブモジュールの現在のブランチにマージします。このオプションが指定されている場合、サブモジュールのHEADはデタッチされません。マージの失敗によりこのプロセスが妨げられた場合、通常のマージ競合解決ツールを使用してサブモジュール内の競合を解決する必要があります。キー submodule.$name.update が merge に設定されている場合、このオプションは暗黙的です。

--rebase

このオプションは、updateコマンドでのみ有効です。現在のブランチを、スーパープロジェクトに記録されたコミットにリベースします。このオプションが指定されている場合、サブモジュールのHEADはデタッチされません。マージの失敗によりこのプロセスが妨げられた場合、git-rebase[1] を使用してこれらの失敗を解決する必要があります。キー submodule.$name.update が rebase に設定されている場合、このオプションは暗黙的です。

--init

このオプションは、updateコマンドでのみ有効です。「git submodule init」がまだ呼び出されていないすべてのサブモジュールを、更新前に初期化します。

--name

このオプションは、addコマンドでのみ有効です。サブモジュールの名前をデフォルトのパスではなく、指定された文字列に設定します。名前はディレクトリ名として有効である必要があり、*/ で終わることはできません。

--reference <repository>

このオプションは、add および update コマンドでのみ有効です。これらのコマンドは、リモートリポジトリをクローンする必要がある場合があります。この場合、このオプションは git-clone[1] コマンドに渡されます。

注意: git-clone[1] の --reference、--shared、および --dissociate オプションに関する注意を注意深く読んだ場合を除き、このオプションを使用しないでください。

--dissociate

このオプションは、add および update コマンドでのみ有効です。これらのコマンドは、リモートリポジトリをクローンする必要がある場合があります。この場合、このオプションは git-clone[1] コマンドに渡されます。

注意: --reference オプションに関する注意を参照してください。

--recursive

このオプションは、foreach、update、status、および sync コマンドでのみ有効です。サブモジュールを再帰的にトラバースします。操作は、現在のリポジトリのサブモジュールだけでなく、それらのサブモジュール内のネストされたサブモジュール (など) でも実行されます。

--depth

このオプションは、add および update コマンドで有効です。指定されたリビジョン数に切り捨てられた履歴を持つ浅いクローンを作成します。git-clone[1] を参照してください。

--[no-]recommend-shallow

このオプションは、update コマンドでのみ有効です。サブモジュールの初期クローンは、デフォルトで .gitmodules ファイルによって提供される推奨の submodule.<name>.shallow を使用します。提案を無視するには、--no-recommend-shallow を使用します。

-j <n>
--jobs <n>

このオプションは、update コマンドでのみ有効です。新しいサブモジュールを、指定された数のジョブを使用して並行してクローンします。デフォルトは submodule.fetchJobs オプションです。

--[no-]single-branch

このオプションは、update コマンドでのみ有効です。更新中に 1 つのブランチのみをクローンします: HEAD または --branch で指定されたブランチ。

<path>…​

サブモジュールへのパス。指定すると、コマンドは指定されたパスにあるサブモジュールでのみ操作を制限します。(この引数は add で必須です)。

ファイル

サブモジュールを初期化する場合、包含リポジトリの最上位ディレクトリにある .gitmodules ファイルを使用して、各サブモジュールの URL を検索します。このファイルは $GIT_DIR/config と同じ形式である必要があります。各サブモジュール URL のキーは "submodule.$name.url" です。詳細については、gitmodules[5] を参照してください。

参考

gitsubmodules[7], gitmodules[5]。

GIT

git[1] スイートの一部

scroll-to-top