Dealing with submodules
Heavy usage of submodules
The Unvanquished repository makes heavy usage of submodules, and submodules having submodules.
Most of the time, developers don't have to commit the submodules themselves. A submodule change that doesn't break compatibility does not strictly require to be committed.
Please don't commit submodules in pull requests, as the submodules references may not exist after the pull requests are rebased and merged.
When a feature is split across more than one repository, submodules are expected to be committed after each pull requests have been merged.
This happens for example if a pull request is split between
daemon/ submodule is committed after pull-requests for both repositories are merged.
For a method of working that prevents to mistakenly commits submodule changes, follow those instructions.
Ignoring submodules by default when diffing and committing
If you're contributing to the Unvanquished game, the parent repository is
Unvanquished/. If you only contribute to the the Dæmon engine and the Dæmon repository is not a submodule, the parent repository is
In parent repository type this command:
git config diff.ignoreSubmodules all
This will remove all submodule changes from
git diff and never commit any submodule change when doing
git commit -am “message”.
Purposedly diffing and committing submodule changes
To explicitly list submodule changes and commit them you can then do:
git -c diff.ignoreSubmodules=none diff git -c diff.ignoreSubmodules=none commit -am ”message”
Doing a splitted pull-request
You need to do a splitted pull-request if you have changes in multiples repositories and requiring each others.
You will have to be a developer with repository write access, and you will have to push your branches using the exact same branch name, with
/sync suffix. For example the branch would be named like
The CI automatically fetches submodule
<something>/sync branch when building parent
For example if you modify both
Unvanquished/daemon/ and the changes in
Unvanquished/ requires changes from
Unvanquished/daemon/ to build, you need to do a splitted pull request. You would push both your Unvanquished and Dæmon changes to upstream with a branch name like
username/feature/sync. And the CI will automatically fetch the
username/feature/sync branches of both
Bisecting a tree with submodules
When bisecting the history, you may have to run
git submodule update --init --recursive on every step.
While a submodule change that doesn't break compatibility does not strictly requires to be committed, frequent submodule commits makes easier to bisect the tree in the following time.
That's why from time to time we commit the submodules so we can bisect the commits committing the submodules. Such commits, only meant for making bisecting easier, are never done within a pull-requests.