SYNOPSIS

'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>...]

DESCRIPTION

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

サブモジュールの詳細については、 gitsubmodules(7) を参照してください。

COMMANDS

引数なしで、既存のサブモジュールのステータスを示します。 サブモジュールで操作を実行するために、いくつかのサブコマンドを使用できます。

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

指定のリポジトリーを、 指定のパスでサブモジュール(submodule)として現在のプロジェクトに追加し、 次にコミットされるチェンジセットに含めます。 現在のプロジェクトは「スーパープロジェクト」(superproject)と呼ばれます。

<repository> は、新しいサブモジュールの元リポジトリーのURLです。 これは、絶対URLまたは、( ./ や ../ で始まる場合)スーパープロジェクトのデフォルトのリモート・リポジトリーに対する相対的な場所を指定します。 (なお、 スーパープロジェクト bar.git のすぐ隣に位置するリポジトリ foo.git を指定する場合、 相対 URL の規則に従って ./foo.git としてしまいがちですが、 実際には ../foo.git を使用する必要があります。 これは、Git における相対 URL の評価が相対ディレクトリの評価と同じだからです)。

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

オプションの引数 <path> は、複製されたサブモジュールがスーパープロジェクト内で存在するための相対的な場所です。 <path> が指定されていない場合、ソースリポジトリの正規部分(canonical part)が使用されます(/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> が指定された場合、 新しくクローンされたサブモジュールの 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 設定を通じてサポートされる更新手順は以下の通りです:

checkout

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

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

rebase

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

merge

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

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

custom command

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

none

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

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

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

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

--filter <filter-spec> が指定されている場合、 指定の部分(partial)クローン・フィルタがサブモジュールに適用されます。 フィルター仕様の詳細については、 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 は、直接のスーパープロジェクト(immediate superproject)に記録されているサブモジュールのパスで、 $displaypath には、現在の作業ディレクトリからサブモジュールのルートディレクトリへの相対パスが含まれ、 $sha1 は、直接のスーパープロジェクト(immediate superproject)に記録されているコミットで、 $toplevel は、直接のスーパープロジェクト(immediate superproject)のトップレベルへの絶対パスです。Windowsでの $PATH との競合を避けるために、 $path 変数は $sm_path 変数の非推奨の同義語になっていることに注意してください。スーパープロジェクトで定義されているがチェックアウトされていないサブモジュールは、このコマンドでは無視されます。--quiet が指定されていない限り、foreachはコマンドを評価する前に各サブモジュールの名前を出力します。 --recursive が指定されている場合、サブモジュールは再帰的にトラバースされます(つまり、指定のシェルコマンドはネストされたサブモジュールでも評価されます)。 サブモジュールのコマンドからゼロ以外の値が返されると、処理が終了(terminate)します。これは、コマンドの最後に || : を追加することでオーバーライドできます。

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

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 ファイルを追加します。

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

このコマンドはデフォルトで再帰的に実行されます。

OPTIONS

-q
--quiet

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

--progress

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

--all

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

-b <branch>
--branch <branch>

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

-f
--force

This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. This option is also used to bypass a check that the submodule’s name is not already in use. By default, git submodule add will fail if the proposed name (which is derived from the path) is already registered for another submodule in the repository. Using --force allows the command to proceed by automatically generating a unique name by appending a number to the conflicting name (e.g., if a submodule named child exists, it will try child1, and so on). When running deinit the submodule working trees will be removed even if they contain local changes. When running update (only effective with the checkout procedure), throw away local changes in submodules when switching to a different commit; and always run a checkout operation in the submodule, even if the commit listed in the index of the containing repository matches the commit checked out in the submodule.

--cached

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

--files

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

-n
--summary-limit

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

--remote

このオプションは、updateコマンドに対してのみ有効です。 スーパープロジェクトの記録されたSHA-1を使用してサブモジュールを更新する代わりに、サブモジュールのリモート追跡ブランチのステータスを使用します。 使用されるリモートはブランチのリモート(branch.<name>.remote)で、デフォルトは origin です。 使用されるリモートブランチのデフォルトはリモートの HEAD ですが、ブランチ名は、 .git / config または .gitmodules のいずれかで 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(detached HEAD)のスーパープロジェクトに記録されたコミットをチェックアウトします。これはデフォルトの動作です。このオプションの主な用途は、 checkout 以外の値に設定されたときに submodule.$name.update をオーバーライドすることです。 キー 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コマンドに有効です。 指定のリビジョン数に切り捨てられた履歴を持つ「浅い」クローン(shallow clone)を作成します。 git-clone(1) を参照してください。

--recommend-shallow
--no-recommend-shallow

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

-j <n>
--jobs <n>

このオプションは、updateコマンドに対してのみ有効です。多くのジョブと並行して新しいサブモジュールのクローンを作成します。デフォルトは submodule.fetchJobs オプションです。

--single-branch
--no-single-branch

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

<path>…

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

FILES

サブモジュールを初期化するとき、含まれているリポジトリの最上位ディレクトリにある .gitmodules ファイルを使用して、各サブモジュールのURLを検索します。 このファイルは、 $GIT_DIR/config と同じ方法でフォーマットする必要があります。各サブモジュールURLのキーは、「submodule.$name.url」です。 詳細については、 gitmodules(5) を参照してください。

SEE ALSO

gitsubmodules(7), gitmodules(5).

GIT

Part of the git(1) suite