サブモジュール
ドキュメント：
git submodule コマンド
参考：
git-submodule | Git Documentation [Official]
導入
参考：
サブモジュール機能を使ってプロジェクトを管理してみよう | vdeep
サブモジュールとは何か？メリットや注意点／使い方やオプションを実例で解説 | Proぐらし
サブモジュールを使ってみる | CUBE SUGAR CONTAINER
サブモジュールは癖がすごいとの噂だったが素直につきあっていけそうという話 | deadwood
チームで運用する際の不安と対策 pre-commit 編 | sun-yryr
使い方
サブモジュールを含むリポジトリを再帰的にクローン／取得する。
$ git clone --recursive https://github.com/user_name/repo_name
プロジェクトをクローン後にサブモジュールを初期化／取得する。
$ git submodule update --init
外部リポジトリをプロジェクトにサブモジュールとして追加する。
$ cd path/to/project $ git submodule add https://github.com/user_name/repo_name path/to/submodule
参考：
git submodule – 使い方 | transitive.info
サブモジュールをチェックアウトする
サブモジュールのディレクトリ内でチェックアウトした後、プロジェクトで git add してコミットする。
$ cd path/to/project $ pushd path/to/submodule $ git checkout v1.2.3 $ popd $ git add path/to/submodule $ git commit -m 'Bump up submodule to v1.2.3' $ git push
参考：
git submodule でブランチ／タグをチェックアウトする – Qiita
サブモジュールにて特定のブランチやコミットを使用する | ハックノート
How can I specify a branch / tag when adding a submodule? – Stack Overflow
How to update git submodule to a specific commit? – Stack Overflow
更新を反映させる (update)
リモートの変更を反映させる。
$ git pull $ git submodule update
特定のサブモジュールをリモートに追従させる。
$ git submodule update --remote path/to/submodule $ cd path/to/submodule $ git switch master $ git reset --hard origin/master
参考：
サブモジュールの更新方法を勘違いしていた | rochefort’s blog
サブモジュール内のリポジトリをリモートの master の最新版に追従する – Qiita
Pull latest changes for all submodules – Stack Overflow
ハッシュを確認する (status)
各サブモジュールで現在チェックアウトされているコミットハッシュを確認する。
$ git submodule status
参考：
status – git-submodule | Git Documentation [Official]
履歴を確認する (log)
プロジェクトでサブモジュールを更新したコミットの履歴を確認する。
$ git log --patch --submodule=log -- path/to/submodule
サブモジュールの履歴を全て表示する。
$ git submodule summary $(git rev-list --max-parents=0 HEAD)
参考：
サブモジュールのログを親リポジトリから見る | Hail2u
Display Submodule History (lifuzu) – GitHub Gist
summary – git-submodule | Git Documentation [Official]
History including / interleave submodule commits – Stack Overflow
サブモジュールの更新を取り込む
サブモジュールが参照しているリポジトリに新しいコミットあった場合に、プロジェクトに取り込む。
$ cd path/to/project $ git submodule update --remote $ git add -- path/to/submodule $ git commit -m 'Update the submodule'
参考：
サブモジュールでリモートリポジトリの mainブランチの最新版に反映させる – Qiita
プッシュする
前提
サブモジュールをリモートにプッシュするためには、サブモジュールの作業ツリーにプッシュできるリモートが設定されている必要がある。
HTTPS でサブモジュールを追加した場合は、SSH によるアクセスを設定する。
$ cd path/to/submodule $ git remote set-url origin git@github.com:user_name/repo_name.git
ローカルからサブモジュールを追加した場合は、プッシュ先リポジトリをリモートとして追加する。
$ cd path/to/submodule $ git add remote origin git@github.com:user_name/repo_name.git
使い方
上流ブランチを設定してプッシュする。
$ cd path/to/submodule $ git add . $ git commit -m 'Commit on the submodule' $ git push -u origin master
参考：
これならわかる！ git submodule でサブモジュールを追加する方法 | 侍エンジニアブログ
How to push submodule to a remote repository? – Stack Overflow
サブモジュールの変更を巻き戻す
参考：
連動してコミットとプッシュを行う
参考：
サブモジュールを親のリポジトリと同時にコミット、プッシュしたい – スタック・オーバーフロー
リポジトリを変更する
.gitmodules ファイルを編集して、git submodule sync コマンドを実行する。
参考：
How to change the remote repository for a submodule? – Stack Overflow
サブモジュール内の変更を無視する
--ignore-submodulesオプションを使うsubmodule.<name>.ignoreを設定する
参考：
サブモジュールで発生した変更を親リポジトリで無視する2つの方法 | DevelopersIO
submodule.<name>.ignore – gitmodules | Git Documentation [Official]
サブモジュールの登録を削除する
サブモジュールの登録を削除するには、git submodule deinit コマンドを使う。
$ git submodule deinit path/to/submodule_dir
ファイルは残るので、不要であれば削除する。
$ git rm path/to/submodule_dir
参考：
deinit – git-submodule | Git Documentation [Official]
入れ子
参考：
multiple .gitmodules files – Stack Overflow
再作成する
--force オプション
同じリポジトリを再度サブモジュールとして登録する場合、--force オプションを指定して上書きする。
$ git submodule add --force https://github.com/user_name/repo_name path/to/submodule
--name オプション
別のリポジトリを以前存在した場所にサブモジュールとして登録する場合、--name オプションを指定して別名で登録する。
$ git submodule add --name another_name --force https://github.com/user_name/repo_name path/to/submodule
参考：
ローカルのみでサブモジュールを作成する
参考：
Nested Git repositories without remotes (a.k.a. git submodule without remotes) – Stack Overflow
シンボリックリンクを使う
参考：
git submodule to reference files – Stack Overflow
外部のディレクトリを使う
Linux の場合
プロジェクト内に外部ディレクトリへのマウントを作成する。
$ cd path/to/project $ sudo mount --bind /path/to/module_repo path/to/submodule
Windows の場合
プロジェクト内に外部ディレクトリへのジャンクションを作成する。
> cd Path\to\Project > mklink /J Path\to\Submodule C:\Path\to\Module_Repo
参考：
How to use submodules publicly, but symlinks to a single clone locally? – Stack Overflow
Keep submodule outside working tree – Stack Overflow
更新範囲を制御したい
参考：
Does updating a submodule also update the symlink that points to it? – Stack Overflow
作業ツリーを共有する
使い方
テキストファイル形式の .git を使用して外部ディレクトリの作業ツリーを参照する。
$ cd path/to/project $ echo gitdir: path/to/module_repo/.git > path/to/submodule/.git
参照先を確認する。
$ git --git-dir=path/to/submodule/.git rev-parse --git-dir --show-toplevel
注意事項
- 作業ツリーが共有されるため、どこかで作業ツリーを変更すると参照されている範囲全てに影響する。
- 複数人での作業や、複雑または大規模なプロジェクトには向かない。
- 小規模なプロジェクトの初期にのみ適用する。
参考：
Possible to use same submodule working copy by multiple projects? – Stack Overflow
設定
ドキュメント：
gitmodules | Git Documentation [Official]
参考：
仕組み
add
.gitmodulesにサブモジュールが登録される.git/configにサブモジュールの設定が追加される.git/modules/...にサブモジュールのリポジトリを管理する情報が配置される- リポジトリがプロジェクト内の指定したパスにクローンされる
deinit
.gitmodulesからサブモジュールの登録が削除される.git/configからサブモジュールの設定が削除される- プロジェクト内のクローンされたディレクトリは残っているので、任意に
git rmコマンドで削除する
参考：
gitlink エントリー
参考：
Where is the gitlink entry located for submodules? – Stack Overflow
How to track untracked content? – Stack Overflow
作業ツリーを移動する
参考：
What goes wrong when using git worktree with git submodules – Stack Overflow
multiple configurations 警告
現象：
複数のサブモジュール構成が含まれている旨の警告が表示される。
warning: abcd12345xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:.gitmodules, multiple configurations found for 'submodule.path/to/submodule'. Skipping second one!
参考：
submodule warning ‘multiple configurations found’ – Stack Overflow
ドキュメント
git-submodule (1) | Git Documentation [Official]
gitsubmodules (7) | Git Documentation [Official]
gitmodules (5) | Git Documentation [Official]
まとめ／Tips
サブモジュールの押さえておきたい理解ポイントのまとめ – Qiita
git submodule はトモダチ！怖くないよ！ | エムスリーテックブログ
フェイクサブモジュール (Subtree)
プロジェクト内に外部リポジトリをクローンし、フェイクサブモジュールとして追加してコミットする。
$ cd path/to/project $ git clone https://github.com/user_name/repo_name path/to/submodule $ git add path/to/submodule/ $ git commit -m 'Add a fake submodule'
フェイクサブモジュールで更新を取り込む。
$ cd path/to/submodule $ git pull
参考：