opendev/gerrit
Code Issues Proposed changes

Improve submodule subscription documentation

Browse Source 
Current documentation does not cover some limitations in the
implementation. This might cause a Gerrit user to spend valuable time
trying to troubleshoot why a submodule subscription is not working as
expected. Examples of this are:

 * Not possible to use the feature with SSH hostname different from
   canonical web URL hostname
 * Relative submodules must contain the full Gerrit project name

Change-Id: I5acf608b366f3f64047730c2b691b1e6bf62a2ea
This commit is contained in:
Peter Jönsson
2013-05-02 20:42:29 +02:00
parent 7759586450
commit f6488f79cf
1 changed files with 74 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
Documentation/user-submodules.txt
View File

@@ -1,5 +1,5 @@
Gerrit Code Review - Superprojects subscribed to submodules updates Gerrit Code Review - Superproject subscription to submodules updates
=================================================================== ====================================================================
Description Description
----------- -----------
@@ -25,7 +25,7 @@ commit having the updated gitlinks.
Git Submodules Overview Git Submodules Overview
----------------------- -----------------------
It is a git feature that allows an external repository to be Submodules are a git feature that allows an external repository to be
attached inside a repository at a specific path. The objective here attached inside a repository at a specific path. The objective here
is to provide a brief overview, further details can be found is to provide a brief overview, further details can be found
in the official git submodule command documentation. in the official git submodule command documentation.
@@ -37,20 +37,20 @@ at path 'a' by executing the following command when being inside
'super': 'super':
===== =====
git submodule add ssh://server/a a git submodule add ssh://server/a a
==== =====
Still considering the above example, after its execution notice that Still considering the above example, after its execution notice that
inside the local repository 'super' the 'a' folder is considered a inside the local repository 'super' the 'a' folder is considered a
gitlink to the external repository 'a'. Also notice a file called gitlink to the external repository 'a'. Also notice a file called
.gitmodules is created (it is a config file containing the .gitmodules is created (it is a configuration file containing the
subscription of 'a'). To provide the sha-1 each gitlink points to in subscription of 'a'). To provide the SHA-1 each gitlink points to in
the external repository, one should use the command: the external repository, one should use the command:
==== ====
git submodule status git submodule status
==== ====
In the example provided, if 'a' is updated and 'super' is supposed 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 to see the latest SHA-1 (considering here 'a' has only the master
branch), one should then commit the modified gitlink for 'a' in branch), one should then commit the modified gitlink for 'a' in
the 'super' project. Actually it would not even need to be an the 'super' project. Actually it would not even need to be an
external update, one could move to 'a' folder (insider 'super'), external update, one could move to 'a' folder (insider 'super'),
@@ -63,11 +63,11 @@ Creating a New Subscription
Defining the Submodule Branch Defining the Submodule Branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is required because Submodule subscription is actually the This is required because submodule subscription is actually the
subscription of a submodule project and one of its branches for subscription of a submodule project and one of its branches for
a branch of a super project. a branch of a super project.
Since it manages subscriptions in the branch scope, we could have Since Gerrit manages subscriptions in the branch scope, we could have
a scenario having a project called 'super' having a branch 'integration' a scenario having a project called 'super' having a branch 'integration'
subscribed to a project called 'a' in branch 'integration', and also subscribed to a project called 'a' in branch 'integration', and also
having the same 'super' project but in branch 'dev' subscribed to the 'a' having the same 'super' project but in branch 'dev' subscribed to the 'a'
@@ -77,22 +77,23 @@ After adding the git submodule to a super project, one should edit
the .gitmodules file to add a branch field to each submodule the .gitmodules file to add a branch field to each submodule
section which is supposed to be subscribed. section which is supposed to be subscribed.
The branch field is not filled by the git submodule command. Its value As the branch field is a Gerrit specific field it will not be filled
should indicate the branch of a submodule project that when updated automatically by the git submodule command, so one needs to edit it
will trigger automatic update of its registered gitlink. manually. 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 The branch value could be "'.'" if the submodule project branch
has the same name as the destination branch of the commit having has the same name as the destination branch of the commit having
gitlinks/.gitmodules file. gitlinks/.gitmodules file.
The branch field of a submodule section is a custom git submodule If the intention is to make use of the Gerrit feature described
feature for Gerrit use. One should always be sure to fill it in here, one should always be sure to update the .gitmodules file after
editing .gitmodules file after adding submodules to a super project, 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 If a git submodule is added but the branch field is not added to the
available in the .gitmodules file will not be subscribed by Gerrit .gitmodules file, Gerrit will not create a subscription for the
to automatically update the superproject. submodule and there will be no automatic updates to the superproject.
Detecting and Subscribing Submodules Detecting and Subscribing Submodules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -118,17 +119,62 @@ is merged in branch 'dev-of-a' of 'a' project, Gerrit automatically
creates a new commit on branch 'dev' of 'super' updating the gitlink creates a new commit on branch 'dev' of 'super' updating the gitlink
to point to the just merged commit. to point to the just merged commit.
Canonical Web Url Subscription Limitations
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
Gerrit will automatically update only the superprojects that added Gerrit will only automatically update superprojects where the
the submodules of urls of the running server (the one described in submodules are hosted on the same Gerrit instance as the
the canonical web url value in Gerrit configuration file). superproject. Gerrit determines this by checking the hostname of the
submodule specified in the .gitmodules file and comparing it to the
hostname from the canonical web URL.
It is currently not possible to use the submodule subscription feature
with a canonical web URL hostname that differs from the hostname of
the submodule. Instead relative submodules should be used.
The Gerrit instance administrator group should always certify to The Gerrit instance administrator group should always certify to
provide the canonical web url value in its configuration file. Users provide the canonical web URL value in its configuration file. Users
should certify to use the url value of the running Gerrit instance to should certify to use the correct hostname of the running Gerrit
add/subscribe submodules. instance to add/subscribe submodules.
Relative submodules
~~~~~~~~~~~~~~~~~~~
To enable easier usage of Gerrit mirrors and/or distribution over
several protocols, such as plain git and HTTP(S) as well as SSH, one
can use relative submodules. This means that instead of providing the
entire URL to the submodule a relative path is stated in the
.gitmodules file.
Gerrit will try to match the entire project name of the submodule
including directories. Therefore it is important to supply the full
path name of the Gerrit project, not only relative to the super
repository. See the following example:
We have a super repository placed under a sub directory.
product/super_repository.git
To this repository we wish add a submodule "deeper" into the directory
structure.
product/framework/subcomponent.git
Now we need to edit the .gitmodules to include the complete path to
the Gerrit project. Observe that we need to use two "../" to include
the complete Gerrit project path.
path = subcomponent.git
url = ../../product/framework/subcomponent.git
branch = master
In contrast the following will not setup proper submodule
subscription, even if the submodule will be successfully cloned by git
from Gerrit.
path = subcomponent.git
url = ../framework/subcomponent.git
branch = master
Removing Subscriptions Removing Subscriptions
---------------------- ----------------------