日本語 ▾ トピック ▾ 最新バージョン ▾ 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` ではなく、`../foo.git` を使用する必要があることに注意してください。これは Git での相対 URL の評価が相対ディレクトリの評価と同じであるためです)。

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

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

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

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

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

サブモジュールのステータスを表示します。これは、各サブモジュールの現在チェックアウトされているコミットの SHA-1 と、サブモジュールのパス、およびその SHA-1 の git describe の出力も表示します。サブモジュールが初期化されていない場合は -、現在チェックアウトされているサブモジュールのコミットがコンテナリポジトリのインデックスにある SHA-1 と一致しない場合は +、サブモジュールにマージの競合がある場合は U が各 SHA-1 の前に付く可能性があります。

--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>…​)

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

このコマンドをパス指定なしで実行すると、すべての登録解除を防ぐためにエラーが発生します。

--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

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

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

rebase

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

merge

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

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

カスタムコマンド

コミット 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 を実行する場合 (checkout 手順でのみ有効)、別のコミットに切り替えるときにサブモジュール内のローカルな変更を破棄します。また、コンテナリポジトリのインデックスにリストされているコミットがサブモジュールにチェックアウトされているコミットと一致する場合でも、常にサブモジュールでチェックアウト操作を実行します。

--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 コマンドで有効です。指定されたリビジョン数に履歴を切り詰めた shallow クローンを作成します。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 コマンドでのみ有効です。更新時に HEAD または --branch で指定されたブランチのいずれか1つのブランチのみをクローンします。

<path>…​

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

ファイル

サブモジュールを初期化する場合、コンテナリポジトリのトップレベルディレクトリにある .gitmodules ファイルが各サブモジュールの URL を見つけるために使用されます。このファイルは $GIT_DIR/config と同じ方法でフォーマットされている必要があります。各サブモジュール URL のキーは "submodule.$name.url" です。詳細については gitmodules[5] を参照してください。

関連項目

gitsubmodules[7], gitmodules[5].

GIT

git[1]スイートの一部

scroll-to-top