Git Tools - Submodules
Submodules allow you to keep a Git repository as a subdirectory of another Git repository. This lets you clone another repository into your project and keep your commits separate. Click here to view detailed document.
Add a submodule
Add a DbConnector repository as a submodule to current project:
1 2 3 4 5 6 7 | $ git submodule add https://github.com/chaconinc/DbConnector [path/to/submodule] Cloning into 'DbConnector'... remote: Counting objects: 11, done. remote: Compressing objects: 100% (10/10), done. remote: Total 11 (delta 0), reused 11 (delta 0) Unpacking objects: 100% (11/11), done. Checking connectivity... done. |
This will add a .gitmodules and a sub directory to current project. If you run git status, you'll get following:
1 2 3 4 5 6 7 8 9 | $ git status On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: .gitmodules new file: DbConnector |
The .gitmodules stores the mapping between sub project URL and local directory:
1 2 3 | [submodule "DbConnector"] path = DbConnector url = https://github.com/chaconinc/DbConnector |
Git sees it as a submodule and doesn’t track its contents when you’re not in that directory. Instead, Git sees it as a particular commit from that repository.
Cloning a Project with Submodules
Clone a repository with submodules:
1 2 3 4 5 6 7 | $ git clone https://github.com/chaconinc/MainProject Cloning into 'MainProject'... remote: Counting objects: 14, done. remote: Compressing objects: 100% (13/13), done. remote: Total 14 (delta 1), reused 13 (delta 0) Unpacking objects: 100% (14/14), done. Checking connectivity... done. |
The DbConnector directory is there, but empty. Run git submodule init to initialize your local configuration file:
1 2 | $ git submodule init Submodule 'DbConnector' (https://github.com/chaconinc/DbConnector) registered for path 'DbConnector' |
To fetch all the data from sub project and check out the appropriate commit:
1 2 3 4 5 6 7 8 | $ git submodule update Cloning into 'DbConnector'... remote: Counting objects: 11, done. remote: Compressing objects: 100% (10/10), done. remote: Total 11 (delta 0), reused 11 (delta 0) Unpacking objects: 100% (11/11), done. Checking connectivity... done. Submodule path 'DbConnector': checked out 'c3f01dc8862123d317dd46284b05b6892c7b29bc' |
If the sub module has been recently updated, run update with --remote option:
1 2 3 4 5 6 7 8 | $ git submodule update --remote remote: Counting objects: 4, done. remote: Compressing objects: 100% (2/2), done. remote: Total 4 (delta 2), reused 4 (delta 2) Unpacking objects: 100% (4/4), done. From https://github.com/chaconinc/DbConnector 3f19983..d0354fc master -> origin/master Submodule path 'DbConnector': checked out 'd0354fc054692d3906c85c3af05ddce39a1c0644' |
The submodule will be checked out as a detached state. If you want to work within a submodule checkout any appropriate branch first.
Remove submodules
A few steps to remove submodules manually:
1 2 3 4 | git submodule deinit <path_to_submodule>
git rm <path_to_submodule>
git commit -m "Removed submodule"
rm -rf .git/modules/<path_to_submodule>
|