Working with Submodules

Retrieving

To get everything:

git submodule init
git submodule update

To get a specific submodule:

git submodule init Tests
git submodule update Tests

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. Clone the repository represented by the submodule to your own GitHub account. (Inspect .gitmodules in the MonoGame repository root for information on what to clone.)
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 cloned repository on GitHub.
7. Submit a pull request from your clone to the original repository.

For example (from the MonoGame root):

cd Samples

# 2
git remote add your_remote_name git@github.com...(your writeable repo url)
git remote update

git checkout -b feature_branch
git add -A
git commit -m "Your lovely commit message here"

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. Submit a pull request.

For example (again, from the MonoGame root):

# 1
cd Samples
git checkout master
git pull origin master

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.

# 2
cd ..
git add Samples
git commit -m "Updates the Samples submodule with my fancy changes"
git push origin develop