This page is work in progress. It should describe the layout of pkg-boinc's Git repositories.

Once you have cloned the repository, as describe below, a list of branches available on the server is made visible with

git branch -r


Accessing repositories

Check out the source of package <package> with:

git clone ssh://<alioth-login>@git.debian.org/git/pkg-boinc/<package>.git
cd *boinc*

where <package> is one of 'boinc', 'boinc-app-seti' and 'kboincspy' as inspectable via http://git.debian.org.

If you do not have an Alioth account, you can check out the repositories read-only:

git clone git://git.debian.org/git/pkg-boinc/<package>.git
cd *boinc*

That directory includes all the source code already, and it even shows a debian directory, all information seems available:

$ ls                                 
api                     checkin_notes_samples  db           
apps                    client                 debian     
_autosetup              clientctrl             depcomp    
bolt_checkin_notes.txt  clientgui              doc
[...]

However, we are interested in the differences between that "everything we need locally" master and the original upstream version. git is very good at determine such differences, i.e. we just need another branch, upstream to keep the original. And when the original updates, one can just merge the master branch with it.

Regenerating upstream tarballs

Upstream .orig.tar.gz tarballs can be regenerated with the pristine-tar tool directly from the repositories. To do so create a local pristine-tar branch from the remote origin/pristine-tar branch first:

git checkout -b pristine-tar origin/pristine-tar

As a clarification to those new to git, when cloning, the source of our clone is referred to as "origin". The "checkout" when given the "-b" option creates a new branch, which happens to have the same as the branch on the git server. Normally, one would branch from the local msater, i.e. one adds or changes a series of files relative to what is already available. The "origin/" prefix above informs git to branch from the remote side, i.e. a completely new environment is established that is independent from the previously checked out code:

$ ls
boinc_6.2.14.orig.tar.gz.delta  boinc_6.2.18.orig.tar.gz.id    boinc_6.6.10.orig.tar.gz.delta
boinc_6.2.14.orig.tar.gz.id     boinc_6.4.5.orig.tar.gz.delta  boinc_6.6.10.orig.tar.gz.id
boinc_6.2.18.orig.tar.gz.delta  boinc_6.4.5.orig.tar.gz.id

All other files disappear. The new branch will is listed next to the previously cloned master branch:

git branch

Now to regenerate for example the boinc_6.2.18.orig.tar.gz tarball from the boinc repository run:

pristine-tar checkout boinc_6.2.18.orig.tar.gz

This pristine-tar is some magic on its own. The idea is to share upstream's resources and have them nicely integrated with the git and git-buildpackage functionalities. See this link http://www.eyrie.org/~eagle/notes/debian/git.html for a nice summary on what is going on.

To find out which tarballs can be regenerated with the tool pristine-tar, check out what files there are in the branch with the same name:

git ls-tree pristine-tar

To switch back to the master branch, we now check out our own local master branch:

git checkout master

There will now many file be appearing that will no longer be seen when you checkout the pristine-tar branch again. The concept is that git shows only those files that are assigned to the current branch, that have been already present when the branch was created, or that are assigned to no branch at all. Thus, once you compile the code, all the object files belong to no branch and will stay even when you go to the pristine-tar branch again. This is somewhat annoying at times.

Building packages

Building packages with git-buildpackage is now as easy as running:

git buildpackage --git-pristine-tar

or if you already have the .orig.tar.gz tarball in <path/to/tarballs/>:

git buildpackage --git-tarball-dir=<path/to/tarballs/>

Uploading local changes to the servers

Every new idea worked at under git is prepared as a separate branch. This may for instance be a bug that is fixed. The branches currently existing on the servers seem sufficient. If you are a not a regular contributor, and even if you are, please consider to discuss the preparation of new branches with Rene and/or possibly Thomas. The idea previously prepared is then merged with the local representation of the server's branches.

git checkout master
# checking out the server's branch. Make sure the names are identical
git checkout -b debian/topic/boinc-server origin/debian/topic/boinc-server
# now start following your idea
git branch myIdeaToTest
# perform some wild editing
git add <i>files edited</i>
git commit -m "some summary"
# you possibly want to have several rounds of editing/adding/commits
git checkout debian/topic/boinc-server
git merge -m "bringing idea to life" myIdeaToTest
# uploading to upstream branch with the same name as the local one
git push origin

If you don't need your branch any more then you can delete it with

git branch -D myIdeaToTest

This way, the changes are done to the respective branch, not to the master. Changes to the latter would impose their applicability across all possible versions of boinc. If the idea of yours that is represented by the branch would be applicable, then merge it from multiple branches, i.e. from debian/etch and debian/sarge, prior to deleting it.

Tracking upstream development

With git-svn upstream development can be directly tracked in your Git repository. For example if you are in the boinc repository, run the following command to clone BOINC's trunk from upstream's Subversion repository into your Git repository:

git svn clone --trunk=trunk/boinc --prefix=git-svn/upstream/ http://boinc.berkeley.edu/svn/ .

This creates a new remote branch git-svn/upstream/trunk which contains BOINC's complete trunk.

Misc

It is at times confusing with all those many branches. To show that info directly on the shell, consider to add the following to the .profile or .bashrc (found at http://techblog.floorplanner.com/2008/12/14/working-with-git-branches/):

parse_git_branch() {
  git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ \[\1\]/'
}
export PS1="\[\033[01;37m\]${debian_chroot:+($debian_chroot)}\u@\h:\w\[\033[00;35m\]$(parse_git_branch)\[\033[00m\] \$"