Working with Supermodules and Submodules
 |
The examples below assume that Codebeamer is running on localhost using port 8080.
|
First we need to create:
1. A new Codebeamer project called my project.
2. Two initially empty managed Git repositories in this project, called main and xml library, respectively.
Adding submodules to your project
1. Create a working directory:
$ mkdir $HOME/work
$ cd $HOME/work
$ cd $HOME/work
2. Initialize the xmllibrary repository (the module used by the main project) by importing a new file to it:
$ git clone http://localhost:8080/cb/git/xmllibrary
$ cd xmllibrary
$ echo Hello > xml-readme.txt
$ git add xml-readme.txt
$ git commit -m "New readme file of xmllibrary"
$ git push origin master
$ cd xmllibrary
$ echo Hello > xml-readme.txt
$ git add xml-readme.txt
$ git commit -m "New readme file of xmllibrary"
$ git push origin master
3. We initialize the main repository similarly:
$ cd $HOME/work
$ git clone http://localhost:8080/cb/git/main
$ cd main
$ echo World > main-readme.txt
$ git add main-readme.txt
$ git clone http://localhost:8080/cb/git/main
$ cd main
$ echo World > main-readme.txt
$ git add main-readme.txt
4. Add the xmllibrary repository to main as submodule, using the master branch of the submodule.
$ git submodule add -b master http://localhost:8080/cb/git/xmllibrary
5. Finally we commit and push all changes:
$ git commit -m "Added a new file and a submodule"
$ git push origin master
$ git push origin master
The screenshot below shows that now the master branch of main repository uses (depends on) the master branch of the xmllibrary repository.
Now if you click on link xmllibrary the new page will show now that the master branch of xmllibrary repository is used by master branch of supermodule main.
Adding tags to supermodules and submodules
Now we create tags x_v1 in the xmllibrary repository and m_v1 in main, and push them:
$ cd $HOME/work/main/xmllibrary
$ git tag x_v1
$ git push --tags
$ git tag x_v1
$ git push --tags
$ cd $HOME/work/main
$ git tag m_v1
$ git push --tags
$ git tag m_v1
$ git push --tags
The screenshot below shows that both the main/m_v1 tag and the main/master branch depend on the xmllibrary/x_v1 tag and the xmllibrary/master branch.
Working on the supermodule
Now we make a change in the file main-readme.txt of main, and tag the new state with m_v2:
$ cd $HOME/work/main
$ echo World2 > main-readme.txt
$ git commit -a -m "A change in main"
$ git tag m_v2
$ git push --tags
$ echo World2 > main-readme.txt
$ git commit -a -m "A change in main"
$ git tag m_v2
$ git push --tags
The screenshot below shows that the main/m_v2 tag still depends on the xmllibrary/x_v1 tag, as we made changes only in main and not in xmllibrary.
Updating submodules
Let's assume that a new version of the xml library has been released in the meanwhile. We want to update our project to use this latest version, without loosing the previous history.
First we go back to the xmllibrary repository cloned at the beginning of the examples, and pull the new version into the clone (should be up-to-date):
$ cd $HOME/work/xmllibrary
$ git pull
$ git pull
Please note that the xmllibrary repository was cloned outside of main, and can be used totally independently of main. This is how normally third party libraries are developed.
Now we add a new file to the update xmllibrary repository and create the tag x_v2 to reflect that it now contains the new version of the library:
$ echo Simple > INSTALL.txt
$ git add INSTALL.txt
$ git commit -m "New installation document"
$ git tag x_v2
$ git push --tags
$ git add INSTALL.txt
$ git commit -m "New installation document"
$ git tag x_v2
$ git push --tags
The screenshot below shows that no super module depends on x_v2 tag of xmllibrary.
Analyzing the impact of changes in modules
While working with modules, the most frequent question you are going to ask yourself is: I have this change here (and I know that it introduced a new bug), but what does this impact in this repository, and in its super repositories? More accurately, what tags and branches contain this change in the current repository and its super repositories (supermodules)?
First, navigate to the Changeset Details screen by clicking on the link with the SHA code of the change either in the Changes tab of the repository, or in the Changes tab of an affected issue.
Which tags and branches of the enclosing repository and superrepositories are impacted by a change?
It is important understanding on which tags and branches a changeset appears in the repository and which superrepositories (supermodules) and on which tags and branches are impacted.
This is what the next screen shows:
