Working with Submodules

Retrieving

If this guide doesn't satisfy your curiosity fully, try the man page for git submodule.

Git does not automatically retrieve the repositories linked to by submodules. This is actually a good thing, since submodules might be quite large and you may not need the data a particular submodule holds.

Retrieving submodules is straightforward:

For everything (from the MonoGame root):

git submodule init
git submodule update

For a specific submodule (from the MonoGame root):

git submodule init Tests
git submodule update Tests

Calling git submodule init should only be needed once (after the inital checkout of the core repository). git submodule update should be run any time the latest data from a submodule is desired (git status will show out-of-date submodules as modified).

When things go wrong

Very occasionally, the foreign repository that a submodule points to may be changed. In these cases, it is possible for git submodule update to fail with a terrifying error message. If this happens, try:

git submodule sync
git submdoule update

For committers

Be aware that submodule update will often check out a detached head, which you should not make commits to.

If you want to commit to a submodule, there are a few steps.

1. Fork the repository represented by the submodule to your own GitHub account. (Inspect .gitmodules in the MonoGame repository root for information on what to fork.)
2. Add your GitHub repository as a remote for the submodule.
3. Check out master (or create a feature branch and check that out) within the submodule.
4. Make your changes, if you have not already done so.
5. Commit your changes.
6. Push your changes to your forked repository on GitHub.
7. Submit a pull request from your fork to the original repository.

For example (from the MonoGame root):

cd Samples

# 2
git remote add your_remote_name [email protected]...(your writeable repo url)
git remote update

# 3 A feature branch is created, but this is only a matter of style.  You
#   could just as easily check out master.
git checkout -b feature_branch
# 4
# Make some changes here, then add them.
git add -A
# 5
git commit -m "Your lovely commit message here"
# 6
git push your_remote_name feature_branch

After your pull request has been accepted, the submodule reference in the parent repository (MonoGame in this case) must be updated with the new commits.

1. In the submodule directory, update to the latest revision from origin.
2. In the parent repository root, add the updated submodule directory.
3. Commit this change as you would commit any other change to the core repository.
4. Push your changes, as usual.
5. Submit a pull request.

For example (again, from the MonoGame root):

# 1
cd Samples
# 'master' here would be whatever branch your pull request was against
# in part 1, step 7.
git checkout master
git pull origin master
cd ..

At this stage, the Samples directory should refer to the commit that resulted from your pull request in part 1, step 7. git diff can be used to verify this.

Finally (from the MonoGame root):

# 2
git add Samples
# 3
git commit -m "Updates the Samples submodule with my fancy changes"
# 4 'develop' here could be a feature branch you've created.
git push origin develop