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

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

<repository> は、新しいサブモジュールの元リポジトリのURLです。これは、絶対URLまたは、( ./ または ../ で始まる場合、)スーパープロジェクトのデフォルトのリモートリポジトリに相対的な場所のいずれかです(スーパープロジェクト bar.git のすぐ隣にあるリポジトリ foo.git を指定するには、 ./foo.git の代わりに ../foo.git を使用する必要があることに注意してください — 相対 URL の規則に従っていれば、期待通りになるでしょう — 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を使用してサブモジュールを正しく検索します。

If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.

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

Initialize the submodules recorded in the index (which were added and committed elsewhere) by setting submodule.$name.url in .git/config, using the same setting from .gitmodules as a template. If the URL is relative, it will be resolved using the default remote. If there is no default remote, the current repository will be assumed to be upstream.

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

It will also copy the value of submodule.$name.update, if present in the .gitmodules file, to .git/config, but (1) this command does not alter existing information in .git/config, and (2) submodule.$name.update that is set to a custom command is not copied for security reasons.

You can then customize the submodule clone URLs in .git/config for your local setup and proceed to git submodule update; you can also just use git submodule update --init without the explicit init step if you do not intend to customize any submodule locations.

デフォルトのリモートの定義については、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>…]

Update the registered submodules to match what the superproject expects by cloning missing submodules, fetching missing commits in submodules and updating the working tree of the submodules. The "updating" can be done in several ways depending on command line options and the value of submodule.<name>.update configuration variable. The command line option takes precedence over the configuration variable. If neither is given, a checkout is performed. (note: what is in .gitmodules file is irrelevant at this point; see git submodule init above for how .gitmodules is used). The update procedures supported both from the command line as well as through the submodule.<name>.update configuration are:

checkout

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

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

rebase

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

merge

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

The following update procedures have additional limitations:

custom command

mechanism for running arbitrary commands with the commit ID as an argument. Specifically, if the submodule.<name>.update configuration variable is set to !custom command, the object name of the commit recorded in the superproject for the submodule is appended to the custom command string and executed. Note that this mechanism is not supported in the .gitmodules file or on the command line.

none

the submodule is not updated. This update procedure is not allowed on the command line.

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

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

If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.

If --filter <filter-spec> is specified, the given partial clone filter will be applied to the submodule. See git-rev-list(1) for details on filter specifications.

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

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

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

OPTIONS

-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 ですが、ブランチ名は、 .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 オプションに関するNOTEを注意深く読んでいない限り、 このオプションを使用しないでください。

--dissociate

このオプションは、addとupdateコマンドにのみ有効です。これらのコマンドでは、リモートリポジトリのクローンを作成する必要がある場合があります。その場合、このオプションを git-clone(1) コマンドに渡します。

注意: --reference オプションについては NOTE を参照してください。

--recursive

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

--depth

このオプションは、addとupdateコマンドに有効です。 指定のリビジョン数に切り捨てられた履歴を持つ「浅い」クローン(shallow clone)を作成します。 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では必須です)。

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