Latest revision as of 00:33, 10 January 2011

[edit] Intro

At PKP we make use of git sub-modules to integrate our cross-application PKP library into applications like OMP. If you follow the steps in this tutorial you'll have some of the most important situations covered that occur when developing PKP applications with git.

This is not a practical "how-to" guide. It is an abstract tutorial that helps you understand sub-modules in a safe playing ground before you use them in practice. This is also not a beginners' tutorial for git. You should already know how to pull and push from/to remote repositories and you should have a good idea of branching and committing changes.

To start, please create a directory somewhere that you can use to generate your test repositories in. You'll need various repositories so make sure that your working directory is initially empty.

We use the following repositories:

• We maintain one public "official" git repository per PKP application and one for the PKP library on github to track changes to our official stable and development releases.
• Every PKP developer maintains personal public forks of these repositories on github.com
• Every PKP developer maintains local repository clones of his public repositories on his own computer for development

Developers use the master branch to track changes to the "official" repositories. They use "topic branches" for their own development and for communication with each other. Developers will only publish changes to their master branches if they meant to go into the next official release.

In our example we create all repositories locally so that you can easily see what happens to them. We assume that you want to work with the OMP application. That is why we call our main repository "omp". The repository for the PKP library which we will integrate as a sub-module into OMP is called "pkp". The "topic branch" will be named "modal" as an example. You'll call your own topic branches depending on the contents of the change-set you wish to implement.

In our example Mary and Juan are two developers that want to exchange code via their repositories. Please exchange the names for your own!

[edit] Create an "official" OMP application repository

First we will create a repository that represents our "official" application repository and we insert some initial test content:

mkdir omp
cd omp
git init
echo "official omp project a-content" >omp-a.txt
echo "official omp project b-content" >omp-b.txt
git add .
git commit -m "commit initial official omp project content" .
cd ..

[edit] Create pkp library repository

In this step we'll create a second repository that represents the official version of the PKP library.

mkdir pkp-lib
cd pkp-lib
git init
echo "official pkp-lib project a-content" >pkp-lib-a.txt
echo "official pkp-lib project b-content" >pkp-lib-b.txt
git add .
git commit -m "commit initial official pkp-lib project content" .
cd ..

[edit] Add the pkp-lib as a sub-module to the omp project

Please make sure that in the code below you change "/absolute/path/to" to your absolute working directory path.

cd omp
git submodule add "/absolute/path/to/pkp-lib" pkp-lib
git commit -a -m "added pkp-lib as sub-module to omp application"
cd ..

Now you have two repositories that represent the "official" repositories PKP maintains at gitub.com. Next we'll switch to the perspective of Juan who wants to develop code in OMP and the PKP library.

[edit] Clone (fork) "official" projects

Juan bare clones both official projects. These repositories represent Juan's personal public remote repositories that he'll usually maintain on github to share his code with other PKP developers.

git clone --bare omp juan.public.omp.git
git clone --bare pkp-lib juan.public.pkp-lib.git

[edit] Create local development repositories

Juan now creates a local copy of his public omp repository to develop in. He points his sub-module to his public pkp-lib repository so that his changes don't get pushed to the official pkp-lib repository.

git clone juan.public.omp.git/ juan
cd juan
git submodule init

The submodule init command will create a .git folder within the pkp-lib folder. But it will not yet pull contents from the remote repository. Before Juan can do this he has to point his sub-module to his own fork of the official PKP library.

Juan now edits .git/config and changes the submodule url to

/absolute/path/to/juan.public.pkp-lib.git

Then he'll download the contents of his public repository to his local repository and create his topical development branches. We use "modal" as a development branch. You may use any other expression that indicates what you're currently developing.

git submodule update
git branch modal
git checkout modal
cd pkp-lib
git checkout master
git branch modal
git checkout modal
cd ..
git commit -a -m "commit switch to new topical development branch in sub-module"
cd ..

[edit] Start to develop locally

Juan starts to develop in his local repository, then he publishes his changes

cd juan
echo "line inserted in omp project by juan" >>omp-a.txt
git commit -a -m "juan edited file in omp project"
cd pkp-lib
echo "line inserted in pkp-lib by juan" >>pkp-lib-a.txt
git commit -a -m "juan edited file in pkp-lib"
git push origin modal # always commit sub-module first! See pitfalls below.
cd ..
git push origin modal
cd ..

You can check that the change in the sub-module has been published to Juan's remote repository and not to the official one although .gitmodules still points to the official repository.

[edit] Another developer joins the team

Now Mary joins the development team, repeats the setup steps and makes changes to other files (otherwise we get trivial merge conflicts which have nothing to do with our sub-module tutorial).

git clone --bare omp mary.public.omp.git
git clone --bare pkp-lib mary.public.pkp-lib.git

git clone mary.public.omp.git/ mary
cd mary
git submodule init

Mary now edits .git/config and changes the submodule url to

/absolute/path/to/mary.public.pkp-lib.git

Then she pulls the library and makes her own changes:

git submodule update
git branch modal
git checkout modal
cd pkp-lib
git checkout master
git branch modal
git checkout modal
cd ..
git commit -a -m "commit switch to new topical development branch in sub-module"
cd ..

cd mary
echo "line inserted in omp project by mary" >>omp-b.txt
git commit -a -m "mary edited file in omp project"
cd pkp-lib
echo "line inserted in pkp-lib by mary" >>pkp-lib-b.txt
git commit -a -m "mary edited file in pkp-lib"
git push origin modal
cd ..
git push origin modal
cd ..

So far so good - now comes the interesting part: Juan and Mary start to share change-sets between themselves.

[edit] Interact with other developers

Mary pulls changes published by Juan

cd mary
git pull ../juan.public.omp.git modal

cd pkp-lib
git pull ../../juan.public.pkp-lib.git modal
cd ..
git commit -a -m "need to commit the changed sub-module ref"
cd ..

Mary publishes the changes received from Juan to her personal online repository

cd mary/pkp-lib
git push origin modal
cd ..
git push origin modal
cd ..

Mary makes another change to the file Juan changed and publishes her change

cd mary
echo "line by mary in omp on top of juan's change" >>omp-a.txt
git commit -a -m "mary's change in omp project"
cd pkp-lib
echo "line by mary in pkp-lib on top of juan's change" >>pkp-lib-a.txt
git commit -a -m "mary's change in pkp-lib"
git push origin modal
cd ..
git push origin modal
cd ..

Juan pulls everything that Mary has changed (original change + change on top of Juan's change)

cd juan
git pull ../mary.public.omp.git modal
cd pkp-lib
git pull ../../mary.public.pkp-lib.git modal
cd ..
git commit -a -m "need to commit the changed sub-module ref again"
cd ..

Now Juan pushes all consolidated changes to his own repository.

cd juan/pkp-lib
git push
cd ..
git push
cd ..

That's it for a start with sub-modules. Hope you enjoyed our tutorial. You may now move on to HOW-TO check out PKP applications from git.

See: Please see the articles "Pitfalls with Sub-modules" and "Git Submodule Tutorial" for for pitfalls to avoid when working with sub-modules. There are some situations in which you may loose local changes from sub-modules or make your remote repository unusable.