diff options
Diffstat (limited to 'Documentation/user-submodules.txt')
-rw-r--r-- | Documentation/user-submodules.txt | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/Documentation/user-submodules.txt b/Documentation/user-submodules.txt new file mode 100644 index 0000000000..3d14437add --- /dev/null +++ b/Documentation/user-submodules.txt @@ -0,0 +1,143 @@ +Gerrit Code Review - Superprojects subscribed to submodules updates +=================================================================== + +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. + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] |