AliRoot Subversion HOWTO

• Checking Out and Updating
  • How do I check out the AliRoot Subversion repository?
  • How do I check out a specific tag?
  • I have checked out starting at trunk. How can I check out branches without downloading everything again?
  • How do I update my checked out version?
• Editing Files and Committing
  • Editing files
  • Committing changes
  • Renaming and copying files and directories
  • Reverting changes
  • Correcting commit log messages
  • Resolving conflicts
• Branching and Tagging
  • What's the difference between branches and tags in Subversion?
  • How does the AliRoot repository do branches and tags?
  • So, how do I create a branch or copy of my work?
  • Creating the branch directly on the server
  • I'm the Release Dude. How do I make the next AliRoot release?
• Working with Branches
  • Switching
  • Getting information about the working directory
  • Synchronizing a branch with the trunk
  • Displaying differences
• Miscellaneous
  • What's this PREV, HEAD, etc. stuff?
  • How to avoid seeing generated files?
  • How to set automatically basic properties on new files?
  • How do I track changes?
  • Where to get the svn client for my machine?
  • Where to find more on Subversion?

Checking Out and Updating

How do I check out the AliRoot Subversion repository?

Note: the repository at https://alisoft.cern.ch/AliRoot/ is only for AliRoot developers. Non-developers should useAliRoot/ instead. For browsing the repository with a web browser, use viewvc.

To check out the AliRoot repository, you do the following:

That will check out the whole AliRoot trunk (i.e. the head in CVS language) and store it in local directory AliRoot.

Note: watch out not to checkout https://alisoft.cern.ch/AliRoot as that will checkout the trunk as well as all branches and tags.

Some additional information:

• List the content of the repository (using http://, no need for valid administrator's name)

• List the content of the repository (using https://, needs valid administrator's name)

• Authenticating as a different user: use --username

The username and password will be cached in ~/.subversion (MD5 encryption) and used the next time you make changes in the repository.

div id="code">$ svn rm -m "Removing obsolete tag" https://alisoft.cern.ch/AliRoot/tags/etc_files

• Disable the username/password caching:

To disable caching for a single command, pass the --no-auth-cache option.

How do I check out a specific tag?

To check out a specific tag or branch, you do:

This will check out the v4-06-Rev-04 tag and store it in local directory v4-06-Rev-04.

To find out which tags and branches are available you can browse the repository via the web interface viewvc or using:

I have checked out starting at trunk. How can I check out branches without downloading everything again?

You can check out the other directories somewhere else in your system, even in /tmp. Subversion won't have a problem doing copies from different WCs, as long as they live in the same repository.

If you did not check out the toplevel dir but want to do it now, you can try the following trick:

How do I update my checked out version?

To update your working dir, all you have to do is run:

from inside it, just as you did with CVS.

Editing Files and Committing

Editing files

Editing files with Subversion is no different than doing so with CVS.

To see which files you've edited do:

This is a very fast operation as it does not contact the remote repository (and does not bring the repository to the HEAD level).

Committing changes

The only difference you should know about is that Subversion does atomic commits, and you are encouraged to make your commits complete.

In other words, suppose you add a new header file and a new implementation file to STEER and you update libSTEER.pkg and STEERLinkDef.h. You should first svn add the new files, and then commit all of them together with libSTEER.pkg and STEERLinkDef.h, in one go. That way, anyone doing a checkout cannot possibly get a revision in which one change had happened but not the other. To commit just do:

Renaming and copying files and directories

One of the advantages of svn over cvs is that you can rename and copy files and directories without loosing the history. Where in cvs you would do:

You now simple do:

Reverting changes

If you want to undo some changes you've made but not yet committed, try this command:

If you did commit your changes, you can do this:

(type COMMITTED and PREV, in capitals, as shown).

Resolving conflicts

It might happen that an svn up will update a file you just edited and that the conflicts could not be automatically resolved. In that case the file will contain conflict markers "<<<<<<<" and ">>>>>>>" and you have to edit the file to remove the conflict. Before being able to commit this file you first have to tell svn that the conflict has been resolved:

Only then can you proceed to commit the file.

Branching and Tagging

What's the difference between branches and tags in Subversion?

There are no differences between branches and tags in Subversion. In fact, Subversion doesn't even know the concept of branches or tags: everything is a file or a directory for it.

A branch or a tag is nothing more than a copy of your files under a different path. It is an O(1) operation in time and disk space, so there's no harm copying everything.

How does the AliRoot repository do branches and tags?

AliRoot uses the following scheme for its branches and tags:

• /branches: contains all official branches. They are created after a release and are mainly for backporting bugfixes from the trunk.
• /tags: contains all official tags. That is, when a public release is make a tag here to mark the revision in which it happened.

In /branches and /tags, the naming convention used is like this:

• /branches/branchversion, (example /branches/v4-06-Release)
• /tags/releaseversion (example: /tags/v4-06-03)

So, how do I create a branch or copy of my work?

In order to create a branch or a tag, you must have /branches or /tags checked out, even if not recursing (-N).

If your dev's directory doesn't exist yet, create it:

Now copy the trunk:

Of course, this will include the full AliRoot, but there's no harm in doing so.

Creating the branch directly on the server

You can also create the branch directly without having a checked-out working copy:

The branch is now a identical copy of trunk, and you can check out mybranch. When you are done, you can merge the changes back to trunk. If your work takes a long time, you can easily merge changes from trunk into your working branch to stay in sync with the current development on trunk. This will also make merging your changes back to trunk much easier, as the only differences between trunk and your branch are the actual changes you have done to the branch.

You can read more about branching and merging in the book "Version Control with Subversion" in chapter four at http://svnbook.red-bean.com/en/1.4/svn.branchmerge.html.

I'm the Release Dude. How do I make the next AliRoot release?

It's done.

Working with Branches

Switching

I currently have /trunk checked out. How do I switch to the /branches/v4-06-Release branch?

The swith subcommand can be used for that:

More on the switch man page.

Getting information about the working directory

Where am I? I am about to check in my local files - will they end up on my branch or destroy the trunk?

You can ask your current directory what part of the subversion repository it corresponds to. svn info will tell you the directory's URL, the current revision, and when the last change occurred within the current directory:

Synchronizing a branch with the trunk

How do I merge the latest patches added to the trunk in my development branch?

Suppose that you want to synchronize your development branch branches/dev/mydevs with the trunk. To see what files have been changed compared to your branch do:

You can see the detailed differences in each modified file using:

The next step is to merge the differences in your local working directory:

If not sure, you can first run with the option '--dry-run' to check what is going to happen.

The 'C' in the output indicates that there was a conflict while merging io/src/TFile.cxx. After resolving the conflicts by editing the file (and removing the conflict markers), you have to tell svn that the conflicts have been resolved:

Now you can commit the changes to your development branch:

And your development branch is now in sync with the head.

Displaying differences

How can I check what are the differences between my working copy of a file and revision 20474?

This is simply obtained using svn diff:

You can also get a more elaborated 'diff' result by running your preferred 'diff' command, for example, to get a context diff, you can use the system 'diff' and option '-c' in the following way:

 Miscellaneous

What's this PREV, HEAD, etc. stuff?

Those are symbolic revision names for Subversion, just like the normal numeric ones. They mean the following:

• HEAD: latest (youngest) revision in the server
• BASE: the revision your checkout was last updated against
• COMMITTED: last revision a file or directory was changed
• PREV: the last revision the file or directory was changed immediately before COMMITTED

Maybe this is better explained with an example:

1. You check out trunk at revision 200
2. You make a change to trunk/a_file and commit it: revision 201 is created
3. A day later, you update your working dir and find out it's now revision 208
4. You make another modification and commit: revision 209
5. One day later, you update again, this time to revision 212
6. The following day, before updating, the server has progressed to revision 218

Under those circumstances, here's what each one of those 4 mean:

• HEAD = 218
• BASE = 212
• COMMITTED (for a_file) = 209
• PREV (for a_file) = 201

When you run "svn up", you bring BASE up to HEAD.

How to avoid seeing generated files?

To avoid seeing the generated files, like the dictionary G__* or dependency *.d files, when doing svn st you have to add

to the global-ignores in your ~/.subversion/config file. You can at any time see all files doing svn st --no-ignore.

How to set automatically basic properties on new files?

Subversion keeps for each file and directory a hidden file with property information. Using properties Subversion keeps track, for example, of the mime type of a file (.jpg, .png) or if a file is an executable (.sh) or which keywords should be expanded (e.g. $Id: $), etc. To make sure that new files get a correct set of default properties, you have to set in your ~/.subversion/config file:

For more on properties and how to change, list and delete them see http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html.

How do I track changes?

The easies way to track changes is:

• viewvc/, real-time browsing of revisions.

Where to get the svn client for my machine?

Subversion is by default installed on most recent Linux distributions. On Mac OS X 10.4 you can get it from Fink or from a .dmg containing pre-built binaries. On Mac OS X 10.5 svn is part of the system. On Windows you can get it from cygwin. For all other platforms see http://subversion.tigris.org/project_packages.html.

More details follow:

SLC3:
The SVN client is not installed and no version is available as RPM. You can download the sources from
http://subversion.tigris.org/ and compile the latest release 1.4.5.

SLC4:
SVN version 1.1.4 is available and it can be used to check out the code from the repository, however this version has problems when one tries to commit to the repository. SVN version 1.4.4 is available from the dag repository that can be used with yumex. All the developers are encouraged to replace the obsolete version with the new one. The latest SVN release can be installed from sources as in case of SLC3

MacOS:
You can use fink "fink install svn-client" or to take one of the binary distributions available from http://subversion.tigris.org.

Fedora Core:
SVN is available from the package installer.

Solaris:
Please use the packages from http://www.sunfreeware.com.

Where to find more on Subversion?

The definite information can be found on the Subversion project page http://subversion.tigris.org/ and in the online Subversion book http://svnbook.red-bean.com/.

-- Fons Rademakers - 19 Sep 2007
-- P. Hristov - 22 Nov 2007 Adapted to the AliRoot subversion repository