next up previous contents index
Next: Developing Bacula Up: Bacula Developer Notes Previous: Bacula Git repositories   Contents   Index

Subsections


Git Usage

Please note that if you are familiar with SVN, Git is similar, (and better), but there can be a few surprising differences that can lead to damaging the history of the repository (repo) if you attempt to force pushing data into the Git repo.

The Bacula Git repo contains the subdirectories bacula, gui, and regress. With Git it is not possible to pull only a single directory, because of the hash code nature of Git, you must take all or nothing.

For developers, the most important thing to remember about Git and the Source Forge repository is not to "force" a push to the repository, and not to use the rebase command on the master branch of the repository. Doing so, will possibly rewrite the Git repository history and cause a lot of problems for the project.

You may and should use rebase on your own branches that you want to synchronize with the master branch, but please do not use rebase on the master branch. The proper way of merging changes will be discussed below.

You can get a full copy of the Source Forge Bacula Git repository with the following command:

git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk

This will put a read-only copy into the directory trunk in your current directory, and trunk will contain the subdirectories: bacula, gui, and regress.

If you have write permission, you can get a copy of the Git repo with:

git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk

where you replace <userid> with your Source Forge login userid, and you must have previously uploaded your public ssh key to Source Forge.

The above command needs to be done only once. Thereafter, you can:

cd trunk
git pull

As of August 2009, the size of the repository (trunk in the above example) will be approximately 55 Megabytes. However, if you build from source in this directory and do a lot of updates and regression testing, the directory could become several hundred megabytes.


Learning Git

If you want to learn more about Git, we recommend that you visit:
http://book.git-scm.com/http://book.git-scm.com/.

Some of the differences between Git and SVN are:

If you want to understand why it is not a good idea to force a push to the repository, look at the following picture:

\includegraphics[width=0.85\textwidth]{git-edit-commit.eps}

The above graphic has three lines of circles. Each circle represents a commit, and time runs from the left to the right. The top line shows the repository just before you are going to do a push. Note the point at which you pulled is the circle on the left, your changes are represented by the circle labeled Your mods. It is shown below to indicate that the changes are only in your local repository. Finally, there are pushes A and B that came after the time at which you pulled.

If you were to force your changes into the repository, Git would place them immediately after the point at which you pulled them, so they would go before the pushes A and B. However, doing so would rewrite the history of the repository and make it very difficult for other users to synchronize since they would have to somehow wedge their changes at some point before the current HEAD of the repository. This situation is shown by the second line of pushes.

What you really want to do is to put your changes after Push B (the current HEAD). This is shown in the third line of pushes. The best way to accomplish this is to work in a branch, pull the repository so you have your master equal to HEAD (in first line), then to rebase your branch on the current master and then commit it. The exact commands to accomplish this are shown in the next couple of sections.


Publishing your changes

Since Git is more complex than SVN, it takes a bit of time to learn how to use it properly, and if you are not careful, you can potentially create a new history in the repository. In addition, since Git is a distributed version control system, we prefer to receive a full branch submission rather than simply a patch. To accomplish this, you must create your changes in a branch, then push them to some public repository - it can be your own repository that you publish or another. To simplify this phase for you, we have created a publich Bacula Git repository on github where you can push your branch containing changes you would like integrated into the Bacula source code.

Once you have pushed your branch to github or told us where we can pull from your public repository, one of the senior Bacula devlopers will fetch your changes, examine them, possibly make comments for changes they would like to see, and as the final step, the senior developer will commit it to the Bacula Source Forge Git repository.


github

If you are going to submit code, you create a login on the Github website:
http://github.com/http://github.com/
before you clone the repository. You must also upload your public ssh key. Please see the instructions for doing so at the above link. Then you notify one of the senior Bacula developers, who will authorize your Github user name as a committer to the Bacula repository. Finally, you clone the Bacula repository with:

 git clone git@github.com:bacula/bacula.git <xxx>

where you replace <xxx> with the name of a directory that you want Git to create to hold your local Bacula Git repository.

Normally, you will work by creating a branch of the master branch of your repository, make your modifications, then make sure it is up to date, and finally push it to Github. Assuming you call the Bacula repository bacula, you might use the following commands:

cd bacula
git checkout master
git pull 
git branch <your-name>/newbranch
git checkout <your-name>/newbranch
(edit, ...)
git add <file-edited>
git commit -m "<comment about commit>"
...

Note, we request you to create the branch name (<your-name>/newbranch with your Github login name. This guarantees that the branch name will be unique and easily identified as well.

When you have completed working on your branch, you will do:

cd bacula
git checkout <your-name>/newbranch
git pull
git rebase master

If you have completed your edits before anyone has modified the repository, the git rebase master will report that there was nothing to do. Otherwise, it will merge the changes that were made in the repository before your changes. If there are any conflicts, Git will tell you. Typically resolving conflicts with Git is relatively easy. You simply make a diff:

git diff

Then edit each file that was listed in the git diff to remove the conflict, which will be indicated by lines of:

<<<<<<< HEAD
text
>>>>>>>>
other text
=====

where text is what is in the Bacula repository, and other text is what you have changed.

Once you have eliminated the conflict, the git diff will show nothing, and you must do a:

git add <file-with-conflicts-fixed>

Once you have fixed all the files with conflicts in the above manner, you enter:

git rebase --continue

and your rebase will be complete.

If for some reason, before doing the -continue, you want to abort the rebase and return to what you had, you enter:

git rebase --abort

Finally to upload your branch, you do:

git push origin <your-name>/newbranch

If you wish to delete it later, you can use:

git push origin :<your-name>/newbranch


next up previous contents index
Next: Developing Bacula Up: Bacula Developer Notes Previous: Bacula Git repositories   Contents   Index
2009-10-28