日本語 ▾ トピック ▾ 最新版 ▾ 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でも、(./ または ../ で始まる場合) スーパープロジェクトのデフォルトのリモートリポジトリからの相対位置でも構いません（スーパープロジェクト bar.git のすぐ隣にあるリポジトリ foo.git を指定するには、相対URLの規則に従うと ./foo.git を期待するかもしれませんが、Gitでの相対URLの評価は相対ディレクトリの評価と同じであるため、../foo.git を使用する必要があることに注意してください）。

デフォルトのリモートは、現在のブランチのリモート追跡ブランチのリモートです。そのようなリモート追跡ブランチが存在しないか、HEADが detached されている場合、「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> が指定された場合、新しくクローンされたサブモジュールの参照ストレージフォーマットがそれに応じて設定されます。

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 の呼び出しは、再初期化されるまで未登録のサブモジュールをスキップします。したがって、ワーキングツリーにサブモジュールのローカルチェックアウトが不要になった場合は、このコマンドを使用してください。

パス指定なしでコマンドが実行された場合、すべてを deinit するのではなく、間違いを防ぐためにエラーとなります。

--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 設定の両方でサポートされている更新手順は次のとおりです。

checkout

スーパープロジェクトに記録されたコミットが、サブモジュール内で detached HEAD としてチェックアウトされます。

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

rebase

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

merge

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

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

custom command

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

none

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

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

--recursive が指定された場合、このコマンドは登録されたサブモジュールに再帰的に入り込み、その中のネストされたサブモジュールも更新します。

--ref-format <format> が指定された場合、新しくクローンされたサブモジュールの参照ストレージフォーマットがそれに応じて設定されます。

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

--merge

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

--rebase

このオプションは update コマンドでのみ有効です。現在のブランチをスーパープロジェクトに記録されたコミットにリベースします。このオプションが指定された場合、サブモジュールのHEADは detached されません。マージの失敗がこのプロセスを妨げる場合、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