Description
Gerrit supports a custom git superproject feature for tracking submodules. This feature is useful for automatic updates on superprojects whenever a change is merged on tracked submodules. To take advantage of this feature, one should add submodule(s) to a local working copy of a superproject, edit the created .gitmodules configuration file to have a branch field on each submodule section with the value of the submodule branch it is subscribing to, commit the changes, push and merge the commit.
When a commit is merged to a project, the commit content is scanned to identify if it registers git submodules (if the commit registers any gitlinks and .gitmodules file with required info) and if so, a new submodule subscription is registered.
When a new commit of a registered submodule is merged, Gerrit automatically updates the subscribers to the submodule with a new commit having the updated gitlinks.
Git Submodules Overview
It is a git feature that allows an external repository to be attached inside a repository at a specific path. The objective here is to provide a brief overview, further details can be found in the official git submodule command documentation.
Imagine a repository called super and another one called a. Also consider a available in a running Gerrit instance on "server". With this feature, one could attach a inside of super repository at path a by executing the following command when being inside super:
git submodule add ssh://server/a a
Still considering the above example, after its execution notice that inside the local repository super the a folder is considered a gitlink to the external repository a. Also notice a file called .gitmodules is created (it is a config file containing the subscription of a). To provide the sha-1 each gitlink points to in the external repository, one should use the command:
git submodule status
In the example provided, if a is updated and super is supposed to see the latest sha-1 (considering here a has only the master branch), one should then commit the modified gitlink for a in the super project. Actually it would not even need to be an external update, one could move to a folder (insider super), modify its content, commit, then move back to super and commit the modified gitlink for a.
Creating a New Subscription
Defining the Submodule Branch
This is required because Submodule subscription is actually the subscription of a submodule project and one of its branches for a branch of a super project.
Since it manages subscriptions in the branch scope, we could have a scenario having a project called super having a branch integration subscribed to a project called a in branch integration, and also having the same super project but in branch dev subscribed to the a project in a branch called local-dev.
After adding the git submodule to a super project, one should edit the .gitmodules file to add a branch field to each submodule section which is supposed to be subscribed.
The branch field is not filled by the git submodule command. Its value should indicate the branch of a submodule project that when updated will trigger automatic update of its registered gitlink.
The branch value could be . if the submodule project branch has the same name as the destination branch of the commit having gitlinks/.gitmodules file.
The branch field of a submodule section is a custom git submodule feature for Gerrit use. One should always be sure to fill it in editing .gitmodules file after adding submodules to a super project, if it is the intention to make use of the Gerrit feature introduced here.
Any git submodules which are added and not have the branch field available in the .gitmodules file will not be subscribed by Gerrit to automatically update the superproject.
Detecting and Subscribing Submodules
Whenever a commit is merged to a project, its content is scanned to identify if it registers any submodules (if the commit contains new gitlinks and a .gitmodules file with all required info) and if so, a new submodule subscription is registered.
Automatic Update of Superprojects
After a superproject is subscribed to a submodule, it is not required to push/merge commits to this superproject to update the gitlink to the submodule.
Whenever a commit is merged in a submodule, its subscribed superproject is updated.
Imagine a superproject called super having a branch called dev having subscribed to a submodule a on a branch dev-of-a. When a commit is merged in branch dev-of-a of a project, Gerrit automatically creates a new commit on branch dev of super updating the gitlink to point to the just merged commit.
Canonical Web Url
Gerrit will automatically update only the superprojects that added the submodules of urls of the running server (the one described in the canonical web url value in Gerrit configuration file).
The Gerrit instance administrator group should always certify to provide the canonical web url value in its configuration file. Users should certify to use the url value of the running Gerrit instance to add/subscribe submodules.
Removing Subscriptions
If one has added a submodule subscription and drops it, it is required to merge a commit updating the subscribed super project/branch to remove the gitlink and the submodule section of the .gitmodules file.
Part of Gerrit Code Review