Git - Submodule (modules)

About

Submodules allow you to keep a Git repository as a subdirectory of another Git repository.

If you don't want to modify the code, use a package manager instead (such as Maven or Rubygems) to declare your dependency.

A submodule is materialzied as:

  • a subdirectory in your working directory.
  • with its metadata into the gitmodules file.

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.

Example

Used by arrow:

git submodule update --init --recursive # Needed for flight

Management

Create

git submodule add <url> <path>
# if your repository is empty
# cd submodule 
# git init
# ...

This command create:

  • a new directory at path
  • a directory in git_dir/modules/path
  • a path/.git file that points the git_dir of the submodules to git_dir/modules/path
gitdir: ../.git/modules/path

[submodule "path_to_submodule"]
        url = https://github.com/path_to_submodule

Update Submodule to a new Version

git -C <path> checkout <new version>
git add <path>
git commit -m "update submodule to new version"

where:

List

To list the submodules, use the status command

git submodule status

Repository

The repository location of the module is defined in the .git file

gitdir: ../.git/modules/path

Commit

After a commit of the first submodule, we see a:

2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 elastic

Clone

git clone --recurse-submodules https://github.com/username/project

Without the –recurse-submodules option, you get the directories that contain submodules, but none of the files within them. The submodule directories are there, but empty. You must run two commands to get the files:

  • git submodule init to initialize your local configuration file,
  • and git submodule update to fetch all the data from that project and check out the appropriate commit listed in your superproject.

.gitmodules

The .gitmodules file stores the configuration such as:

  • the mapping between the project’s URL and the local subdirectory.
  • the active status
[submodule "subModuleName"]
        path = targetSubDirectoryName
        url = https://github.com/username/repositoryname
[submodule "foo"]
  active = false
  url = https://example.org/foo
[submodule "bar"]
  active = true
  url = https://example.org/bar
[submodule "baz"]
  url = https://example.org/baz

Relocate

???

git config submodule.subModuleName.url YOUR_URL

Diff

Before commit

git diff --cached --submodule

Changes

Pulling in Upstream Changes

  • For all module:
cd parentDirectory
git submodule update --remote # By default from the master branch 

# Modifying the branch 
# Track the change for the subModule not on master but on the branchv1
# -f .gitmodules add the config to the gitmodule file (for everybody then)
git config -f .gitmodules submodule.SubModuleName.branch branchv1 
  • For one module:
cd subdirectoryModule
git fetch
git merge

Verification:

git config --global diff.submodule log #  setting the otuput default format of diff by setting the diff.submodule config value to “log”.
cd parentDirectory
git diff

Applying its own changes

By default, submodule are running in a detached HEAD state.

It means that there is no local working branch (like “master”, for example) tracking changes. With no working branch tracking changes, even if you commit changes to the submodule, those changes will be lost the next time you run git submodule update. To track its own change, we need to create a branch.

cd subModuleDir
git checkout myBranch 
git submodule update --remote --merge

Documentation / Reference

git submodule --help





Discover More
Death Stars Architecture Diagram
Code Shipping - Dependency (Coupling)

in code. A (module|package|library) often requires other (packages|module) to be installed to function correctly. Such a relation is called a dependency. Coupling or dependency is the degree to which...
Git - SubProject

How to integrate subproject into a main project. (ie code dependency) sub-module creates a link to a repository (no file, no commit, no history is saved within the main project repository) sub-tree...
Card Puncher Data Processing
MonoRepo (vs ManyRepos)

MonoRepo is a single repository where all code resides. It's also called a multi-package / multi app repositories. Single lint, build, test and release process. Easy to coordinate changes across...
Git - Repository (Directory)

This page is the notion of repository and how it's implemented in Git. The git repository is a subdirectory named .git that contains all repository files. It contains : commit log configuration,...



Share this page:
Follow us:
Task Runner