Gallery:Using Subversion - Gallery Codex
Personal tools

Gallery:Using Subversion

From Gallery Codex

Quick Start

Gallery 3 has switched to using git for revision control. Please refer to those instructions instead.

What is Subversion?

Subversion is a revision control system -- a way for us to keep track of the history of our code as we work on it. We can use it to look back in time at any given change and see what we did, when and why. Revision control systems are an integral part of software development.

How do I get the latest code?

In order to follow these instructions, you'll need a shell account on a Unix system. If you're using Windows, you should also refer to our Subversion on Windows instructions. If you are using Eclipse as IDE you should also read Subversion in Eclipse. Mac OS X users should review the contents of this page to become familiar with Subversion in addition to our Subversion on Mac instructions.

Our subversion repository is divided up into several areas. Each area revolves around a specific product or concept in the project. The following areas are available:

Once you decide which one you want, you can get a copy of it by doing a svn checkout. If you want the latest Gallery2 code:

 svn checkout

Note that the URL uses the HTTPS protocol, not HTTP. You can replace "gallery2" in this example with the name of a different area of the repository from the table above. Note that the checkout cannot overwrite existing files (from a non-svn install). For more Gallery 1 Subversion information see Gallery1:Developer_Guide.


How do I see the code in a web browser?

Just want to look at the revision history of the code?

How do I update the code?

If you just did a "checkout" then you're all set. But if some time has passed and you want to get the latest version of the code, then you can keep it up to date by going into the directory where the code is located and typing:

 svn update

You'll see a response like this

 U index.php
 U main.php
 U embed.php

This will get you the latest version of the code. Each file you receive will be marked with a letter telling you what Subversion had to do with it. These letters are explained in detail here. For the most part the files will be marked with U meaning that they were updated. If you've modified files and your changes conflict with changes that we have made, then you may see files marked with a C.

What do I do if I get conflicts?

Subversion can't automatically figure out what to do when your changes to the code are in conflict with changes that the Gallery team has made. In those cases, Subversion marks the file as Conflicted and you must resolve it yourself. The Subversion book has a very useful section on resolving conflicts. Here's a short example. If you modified index.php and we modified index.php, you'll wind up with a line like this:

 C  index.php

If you look, you'll see files like this:

 ls -al index*

The actual numbers (r1, r2) will vary. But the smaller number will be the old version of the file in the repository, and the bigger number will be the new version. The .mine file is your file before Subversion tried to merge it, and index.php will contain Subversion's best attempt to merge it. Inside index.php you'll see lines like this:

 <<<<<<< .mine
 /* Some change you made */
 /* Some change Gallery made*/
 >>>>>>> .r2

You need to look at your changes and look at Gallery's changes and figure out how to make the two work well together. How difficult it is to merge depends wholly on how big of a change you made.

Once you've finished merging the file, you can tell Subversion that it's been resolved by doing:

 svn resolved index.php

This may seem like a pain, but it's really not too bad. Subversion will do all the easy merges for you -- only the hard ones will be left. If you don't make any big changes to the code, you may not have any conflicts at all.

Can I use Subversion for my production Gallery?

Sure! We think that is a very good idea. It's quick and easy to update your code, and any changes you've made to your code will be preserved when you upgrade. If you want a stable Gallery, we recommend that you track a major release branch. This will ensure that when you update, you only get the minor modifications that were essential to resolve issues with the major release (such as security updates or critical bugfixes).

What is a major release branch?

Subversion has a feature called branches. These are separate, parallel copies of the code that are divergent. Every time we put out a major release (eg 2.0, 2.2) we create a branch for it (eg BRANCH_2_0, BRANCH_2_2). You can then tell Subversion to check out that version of the code for you. If you want to get Gallery 2.2 from our Subversion repository you would use the following command from the commandline:

 svn checkout .

This will check out a copy of the latest Gallery 2.2 code into your current directory. It would be almost the same as if you downloaded the developer package of Gallery2.

How do I stay up to date with a branch?

Whenever we put out a new minor release (eg 2.1.1), we update the code in its major release branch. So when we released 2.1.1, all the differences between 2.1 and 2.1.1 went into BRANCH_2_1. This means that if you had checked out BRANCH_2_1, all you have to do is a "svn update" and you'll be up to date with 2.1.1. This is a very efficient way to upgrade. We try to only make minor, API compatible changes in dot releases, so you should always be able to safely update to the latest code in a branch. You won't get any experimental code this way.

How do I switch to the next major release branch?

Supposing you've installed 2.0 by checking out BRANCH_2_0 and you've made some minor modifications to it. Now you want to upgrade to the latest code from the 2.1.1 release. You can tell Subversion to switch to BRANCH_2_1 by doing:

 cd gallery
 svn switch

Now you'll have the 2.1 code, while still preserving all of the changes you made to the 2.0 code. The response that you see from this command is very similar to when you do an svn update. Refer to the section on updating for information on how to read the results.

How do I use less disk space for a SVN checkout?

Download and unzip and place svnSlim in a directory in your PATH. See instructions at the top of the script. svnSlim creates a checkout of gallery2 omitting unit tests and language files (optionally include one language with -L {locale}). After checkout you can run svnSlim slim to remove the second copy of every file that subversion maintains. This option saves a lot of disk space, but you cannot use several svn commands (like svn diff) unless you restore these files with svnSlim fat. To update a svnSlim checkout run svnSlim update. This will work whether it is "slim" or "fat".

How do I migrate from CVS to Subversion?

The basic plan is to get your CVS version of Gallery to a known point, and then switch over to the matching point in Subversion. You can do this without losing any modifications you've made to the code. These instructions assume that your code is in a directory called gallery2.

Update to the latest version in CVS on sourceforge:

 cvs -t -d update

Note that you should provide the new -d flag because on 12-May 2006, SourceForge transitioned to a new set of CVS servers (in response to a hardware failure) and changed the CVS paths.

Then move your code out of the way

 mv gallery2 gallery2-cvs

Then check out the matching code from subversion. To move from CVS HEAD to Subversion trunk:

 svn checkout -r 13519

Or if you're moving from a branch (eg, BRANCH_2_1) you'd do:

 svn checkout -r 13519

Then copy over your changes to the subversion copy. This command copies everything from your cvs instance over to your subversion instance, except for the CVS dirs (which are no longer necessary):

 cd gallery2-cvs
 tar --exclude CVS -cf - . | ( cd ../gallery2 && tar -xvf - )

Now you can browse to your gallery2 directory in the browser and everything should work just as it did before. However, there are some subtle differences between the way that SVN and CVS treat keywords so to fix those you should do the following. Note that this has only been tested for HEAD->trunk .. your mileage may vary if you're switching from a branch. These commands fix up the $RCSfile$ keyword found in all of our files, then discards the changes to a few files which can't be fixed.

 cd gallery2
 perl -pi -e 's/(\$RCSfile):.*?\$/$1\$/' `find . -name "*.php" -print -o -name "*.inc" -print -o -name "*.class" -print -o -name "*.js" -print` install/config.php-template themes/ajaxian/theme.css lib/tools/creator/*.tpl lib/tools/uml/JavaClasses.xsl
 svn revert modules/core/test/phpunit/AdminRepository* modules/picasa/classes/*ss modules/picasa/test/phpunit/*ss

Now you should be able to see a list of just your changes by doing this:

 svn status

Your Gallery should work just fine. To update to the latest code in the line you're tracking (trunk or branch) you'd do:

 svn update

How do I switch from a non-svn installation to svn?

Developer Info

Edit your ~/.subversion/config file and merge the following lines into the [auto-props] section. This will set the proper svn properties when adding new files.

*.php = svn:keywords=Author Id Revision;svn:eol-style=native
*.inc = svn:keywords=Author Id Revision;svn:eol-style=native
*.class = svn:keywords=Author Id Revision;svn:eol-style=native
*.tpl = svn:keywords=Author Id Revision;svn:eol-style=native
*.html = svn:keywords=Author Id Revision;svn:eol-style=native
*.css = svn:keywords=Author Id Revision;svn:eol-style=native
*.js = svn:keywords=Author Id Revision;svn:eol-style=native
*.txt = svn:eol-style=native
*.xml = svn:eol-style=native
MANIFEST = svn:keywords=Author Id Revision;svn:eol-style=native
GNUmakefile = svn:keywords=Author Id Revision;svn:eol-style=native
strings.raw = svn:keywords=Author Id Revision;svn:eol-style=native
*.po = svn:keywords=Author Id Revision;svn:eol-style=native
*.mo = svn:mime-type=application/octet-stream
*.gif = svn:mime-type=image/gif
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg

Note: Gallery does not use the "Date" keyword in the settings above because its output differs by locale and causes problems with the file integrity check for svn installs.

Lastly, don't forget to set enable-auto-props to yes in the [miscellany] section if you want to enable auto-props.

For Windows users the per user config file is typically found at:

C:\Documents and Settings\<YOUR_LOGIN>\Application Data\Subversion\config

subject to the locale version of Windows. So a german user will find it at:

C:\Dokumente und Einstellungen\<YOUR_LOGIN>\Anwendungsdaten\Subversion\config

%APPDATA% is an environment variable referring to your "Application Data" directory. Copy and paste the following line into the address bar of any Explorer window, and you'll end up in the right folder regardless of your Windows locale.


This is also the place to look for the config file if you are using Windows, Eclipse and the Subclipse Plugin and using the JavaHL binding (probably also for the JavaSVN binding, but I did not test that).