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 be very confusing (nothing worse than converting from CVS to SVN).

The main 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. Doing so, can possibly rewrite the Git repository history and cause a lot of problems for the project.

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. Obviously you can use any name an not just trunk. In fact, once you have the repository in say trunk, you can copy the whole directory to another place and have a fully functional git repository.

If you have write permission to the Source Forge repository, 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     # refresh my repo with the latest code

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:

• Your main Git directory is a full Git repository to which you can and must commit. In fact, we suggest you commit frequently.
• When you commit, the commit goes into your local Git database. You must use another command to write it to the master Source Forge repository (see below).
• The local Git database is kept in the directory .git at the top level of the directory.
• All the important Git configuration information is kept in the file .git/config in ASCII format that is easy to manually edit.
• When you do a commit the changes are put in .git rather but not in the main Source Forge repository.
• You can push your changes to the external repository using the command git push providing you have write permission on the repository.
• We restrict developers just learning git to have read-only access until they feel comfortable with git before giving them write access.
• You can download all the current changes in the external repository and merge them into your master branch using the command git pull.
• The command git add is used to add a new file to the repository AND to tell Git that you want a file that has changed to be in the next commit. This has lots of advantages, because a git commit only commits those files that have been explicitly added. Note with SVN add is used only to add new files to the repo.
• You can add and commit all files modifed in one command using git commit -a.
• This extra use of add allows you to make a number of changes then add only a few of the files and commit them, then add more files and commit them until you have committed everything. This has the advantage of allowing you to more easily group small changes and do individaual commits on them. By keeping commits smaller, and separated into topics, it makes it much easier to later select certain commits for backporting.
• If you git pull from the main repository and make some changes, and before you do a git push someone else pushes changes to the Git repository, your changes will apply to an older version of the repository you will probably get an error message such as:

   git push
   To git@github.com:bacula/bacula.git
    ! [rejected]        master -> master (non-fast forward)
    error: failed to push some refs to 'git@github.com:bacula/bacula.git'
  

  which is Git's way of telling you that the main repository has changed and that if you push your changes, they will not be integrated properly. This is very similar to what happens when you do an "svn update" and get merge conflicts. As we have noted above, you should never ask Git to force the push. See below for an explanation of why.

• To integrate (merge) your changes properly, you should always do a git pull just prior to doing a git push.
• If Git is unable to merge your changes or finds a conflict it will tell you and you must do conflict resolution, which is much easier in Git than in SVN.
• Resolving conflicts is described below in the github section.