Adding a New Subproject

Submodule

git submodule add https://github.com/githubtraining/example-submodule

git commit -m "adding new submodule"

The submodule add command adds a new file called .gitmodules along with a subdirectory containing the files from example-submodule. Both are added to your index (staging area) and you simply need to commit them. The submodule’s history remains independent of the parent project.

Subtree

git subtree add --prefix=example-submodule https://github.com/githubtraining/example-submodule main --squash

The subtree command adds a subdirectory containing the files from example-submodule. The most common practice is to use the --squash option to combine the subproject’s history into a single commit, which is then grafted onto the existing tree of the parent project. You can omit the --squash option to maintain all of the history from the designated branch of the subproject.

Viewing a Diff of the Subproject

Submodule

To view a diff of the submodule:

# show changes to the submodule commit
git diff example-submodule
# show oneline log of new commits in the submodule
git diff --submodule example-submodule
# show changes to the files in the submodule
git diff --submodule=diff

Subtree

No special command required

Cloning a Repository with a Subproject

Submodule

To clone a repository along with its submodules:

git clone --recurse-submodules URL

If you forgot --recurse-submodules, you can clone and initialize all submodules:

git submodule update --init --recursive

Adding --recursive is only required if any submodule itself has submodules.

Subtree

No special command required

Pulling in Superproject Updates

Submodule

By default, the submodule repository is fetched, but not updated when you run git pull in the superproject. You need to use git submodule update, or add the --recurse-submodules flag to pull :

git pull
git submodule update --init --recursive
# or, in one step (Git >= 2.14)
git pull --recurse-submodules

--init is required if the superproject added new submodules, and --recursive is needed if any submodule itself has submodules.

If ever the superproject changes the URL of the submodule, a separate command is required:

# copy the new URL to your local config
git submodule sync --recursive
# update the submodule from the new URL
git submodule update --init --recursive

--recursive is only needed if any submodule itself has submodules.

Subtree

No special command required

Changing branches

Submodule

By default, the submodule working tree is not updated to match the commit recorded in the superproject when changing branches. You need to use git submodule update, or add the --recurse-submodules flag to switch :

git switch <branch>
git submodule update --recursive
# or, in one step (Git >= 2.13)
git switch --recurse-submodules <branch>

Subtree

No special command required

Pulling in Subproject Updates

Submodule

# Update the submodule repository
git submodule update --remote
# Record the changes in the superproject
git commit -am "Update submodule"

If you have more than one submodule, you can add the path to the submodule at the end of the git submodule update --remote command to specify which subproject to update.

By default, git submodule update --remote will update the submodule to the latest commit on the main branch of the submodule remote.

You can change the default branch for future calls with:

# Git >= 2.22
git submodule set-branch other-branch
# or
git config -f .gitmodules submodule.example-submodule.branch other-branch

Subtree

git subtree pull --prefix=example-submodule https://github.com/githubtraining/example-submodule main --squash

You can shorten the command by adding the subtree URL as a remote:

git remote add sub-remote https://github.com/githubtraining/example-submodule.git

You can add/pull from other refs by replacing main with the desired ref (e.g. stable, v1.0).

Making Changes to a Subproject

Submodule

Access the submodule directory and create a branch:

cd example-submodule
git switch -c branch-name main

Changes require two commits, one in the subproject repository and one in the parent repository. Don’t forget to push in both the submodule and the superproject!

Subtree

No special command required, changes will be committed on the parent project branch.

It is possible to create commits mixing changes to the subproject and the parent project, but this is generally discouraged.

Pushing Changes to the Subproject Repository

Submodule

While in the submodule directory:

git push

Or while in the parent directory:

git push --recurse-submodules=on-demand

Subtree

git subtree push --prefix=example-submodule https://github.com/githubtraining/example-submodule main

Helpful Configs for Submodules

Always show the submodule log when you diff:

git config --global diff.submodule log

Show a short summary of submodule changes in your git status message:

git config --global status.submoduleSummary true

Make push default to --recurse-submodules=on-demand:

git config --global push.recurseSubmodules on-demand

Make all commands (except clone) default to --recurse-submodules if they support the flag (this works for git pull since Git 2.15):

git config --global submodule.recurse true