SVN Usage

Please note that if you are familar with CVS, SVN is very similar (and better), but there can be a few surprising differences.

The *entire* Bacula SourceForge.net Subversion repository can be checked out through SVN with the following command:

svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula

With the above command, you will get everything, which is a very large amount of data:

branches/
  Branch-1.32a/
  ...
  Branch-2.0/
  import/
  vendor/
tags/
  Release-1.1/
  ...
  Release-2.0.2/
trunk/
  bacula/
  docs/
  gui/
  regress/
  rescue/

Note, you should NEVER commit code to any checkout that you have done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2) should be considered read-only.

You may commit code to the most recent item in branches (in the above the most recent one is Branch-2.0). If you want to commit code to an older branch, then please contact Kern first.

You may create your own tags and/or branches, but they should have a name clearly distinctive from Branch-, Release-, or Beta-, which are official names used by the project. If you create a tag, then you should NEVER commit code to it, for the same reason noted above -- it should serve as a marker for something you released. If you create a branch, then you are free to commit to it as you wish.

You may, of course, commit to the trunk.

In summary:

branches
  Branch-nnn
tags
  Release-nnn
  Beta-nnn

are reserved names to be created only by the project manager (or with his OK), where the nnn is any sequence of numbers and periods (e.g. 2.0, 2.0.1, ...).

In addition all tags even those that you create are read-only forever. Typically tags represent release points either in the trunc or in a branch.

Coming back to getting source code. If you only want the current Bacula source code, you could use:

svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula

To view what is in the SVN, point your browser at the following URL: http://bacula.svn.sourceforge.net/viewvc/bacula/

Many of the Subversion (svn) commands are almost identical to those that you have used for cvs, but some (such as a checkout) can have surprising results, so you should take a careful look at the documentation.

The following documentation on the new svn repository will help you know how to use it:

Here is the list of branches:

        Branch-1.32a
        Branch-1.32e
        Branch-1.34.2
        Branch-1.34.5
        Branch-1.36
        Branch-1.36.1
        Branch-1.36.2
        Branch-1.38
        Branch-2.0
        import
        vendor

The list of tags is:

        Release-1.1     Release-1.19    Release-1.19a   Release-1.19b
        Release-1.20    Release-1.21    Release-1.22    Release-1.23
        Release-1.23a   Release-1.24    Release-1.25    Release-1.25a
        Release-1.26    Release-1.27    Release-1.27a   Release-1.27b
        Release-1.27c   Release-1.28    Release-1.29    Release-1.30
        Release-1.31    Release-1.31a   Release-1.32    Release-1.32a
        Release-1.32b   Release-1.32c   Release-1.32d   Release-1.32e
        Release-1.32f   Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
        Release-1.32f-5 Release-1.34.0  Release-1.34.1  Release-1.34.3
        Release-1.34.4  Release-1.34.5  Release-1.34.6  Release-1.35.1
        Release-1.35.2  Release-1.35.3  Release-1.35.6  Release-1.35.7
        Release-1.35.8  Release-1.36.0  Release-1.36.1  Release-1.36.2
        Release-1.36.3  Release-1.38.0  Release-1.38.1  Release-1.38.10
        Release-1.38.11 Release-1.38.2  Release-1.38.3  Release-1.38.4
        Release-1.38.5  Release-1.38.6  Release-1.38.7  Release-1.38.8
        Release-1.38.9  Release-1.8.1   Release-1.8.2   Release-1.8.3
        Release-1.8.4   Release-1.8.5   Release-1.8.6   Release-2.0.0
        Release-2.0.1   Release-2.0.2

Here is a list of commands to get you started. The recommended book is "Version Control with Subversion", by Ben Collins-Sussmann, Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is Open Source, so it is also available on line at:

   http://svnbook.red-bean.com

Get a list of commands

   svn help

Get a help with a command

   svn help command

Checkout the HEAD revision of all modules from the project into the directory bacula-new

   svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new

Checkout the HEAD revision of the bacula module into the bacula subdirectory

   svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula

See which files have changed in the working copy

   svn status

See which files are out of date

   svn status -u

Add a new file file.c

   svn add file.c

Create a new directory

   svn mkdir newdir

Delete an obsolete file

   svn delete file.c

Rename a file

   svn move file.c newfile.c

Move a file to a new location

   svn move file.c ../newdir/file.c

Copy a file retaining the original history in the new file

   svn copy file.c newfile.c

Update the working copy with the outstanding changes

   svn update

Compare working copy with the repository

   svn diff file.c

Commit the changes in the local working copy

   svn commit

Specify which files are ignored in the current directory

   svn propedit svn:ignore .

Mark a file to be executable

   svn propset svn:executable '*' prog.sh

Unmark a file as executable

   svn propdel svn:executable prog.sh

List a file's properties

   svn proplist file.c

Create a branch for a new version

   svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
          https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1

Tag a version for a new release

   svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
          https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1

Let's say you are working in the directory scripts. You would then do:

cd scripts
(edit some files)

when you are happy with your changes, you can do the following:

cd bacula   (to your top level directory)
svn diff  my-changes.patch

When the command is done, you can look in the file my-changes.patch and you will see all the changes you have made to your copy of the repository. Make sure that you understand all the changes that it reports before proceeding. If you modified files that you do do not want to commit to the main repository, you can simply delete them from your local directory, and they will be restored from the repository with the "svn update" that is shown below. Normally, you should not find changes to files that you do not want to commit, and if you find yourself in that position a lot, you are probably doing something wrong.

Let's assume that now you want to commit your changes to the main SVN repository.

First do:

cd bacula
svn update

When you do this, it will pull any changes made by other developers into your local copy of the repository, and it will check for conflicts. If there are any, it will tell you, and you will need to resolve them. The problems of resolving conflicts are a bit more than this document can cover, but you can examine the files it claims have conflicts and look for <<<< or look in the .rej files that it creates. If you have problems, just ask on the developer's list.

Note, doing the above "svn update" is not absolutely necessary. There are times when you may be working on code and you want to commit it, but you explicitly do not want to move up to the latest version of the code in the SVN. If that is the case, you can simply skip the "svn update" and do the commit shown below. If the commit fails because of a conflict, it will tell you, and you must resolve the conflict before it will permit you to do the commit.

Once your local copy of the repository has been updated, you can now commit your changes:

svn commit -m "Some comment about what you changed"

or if you really only want to commit a single file, you can do:

svn commit -m "comment" scripts/file-I-edited

Note, if you have done a build in your directory, or you have added other new files, the commit will update only the files that are actually in the repository. For example, none of the object files are stored in the repository, so when you do a commit, those object files will simply be ignored.

If you want to add new files or remove files from the main SVN repository, and you are not experienced with SVN, please ask Kern to do it. If you follow the simple steps above, it is unlikely that you will do any damage to the repository, and if you do, it is always possible for us to recover, but it can be painful.

If you are only working in one subdirectory of say the bacula project, for example, the scripts directory, you can do your commit from that subdirectory, and only the changes in that directory and all its subdirectories will be committed. This can be helpful for translators. If you are doing a French translation, you will be working in docs/manual-fr, and if you are always cd'ed into that directory when doing your commits, your commit will effect only that directory. As long as you are careful only to change files that you want changed, you have little to worry about.

Kern Sibbald 2009-04-30