 | Level: Intermediate Elliotte Harold (elharo@metalab.unc.edu), Adjunct Professor, Polytechnic University
06 Jun 2006 Elliotte Rusty Harold introduces Subversion, an open
source, multiuser version control system that supports non-ASCII text
and binary data. Follow along as Elliotte shows you how to configure
Subversion support in Eclipse (via the Subclipse plug-in), check out a
project, synchronize with your repository, and then run common operations
such as merge, patch, diff, and delete.
Version control is to programmers what the safety net is to a trapeze
artist. Knowing the net is there to catch them if they fall, aerialists
are free to fly. In the same way, version control enables you to take
programming risks that you would never otherwise consider. If something
goes wrong, you can always revert back to a known, good-working version
of your code. You can experiment in a branch off the main trunk without
interfering with other team members. When bugs are discovered in an
older version of a shipped product, you can easily check out
that specific version to confirm, fix, and generate a patch for
the bug. Without version control, you would have to be much more
cautious, move more slowly, and generally be less productive.
Subversion is a new open source, version control system that supports
database and file-system repositories that can be accessed locally or
over the network. As well as providing the usual diff, patch, tag,
commit, revert, and branch functionality, Subversion adds the ability to
track moves and deletes. Furthermore, it supports non-ASCII text and
binary data, all of which makes it very useful not just for traditional
programming tasks but also for Web development, book authoring, and
other domains that have not traditionally adopted version control.
This article demonstrates the basics of using Subversion to
track your projects so that you can take more risks and have more fun
writing code.
A brief history of version control
I started out with the granddaddy of version control systems, sccs,
while working as a grad student at the National Solar Observatory. Numerous version control systems are available today, and sccs
has long since been superseded by more capable products such as
Visual SourceSafe, BitKeeper, Perforce, and the open source CVS (see Resources).
Among open source programmers, CVS has become the de facto
standard. Free CVS hosting at sites like Codehaus, Sourceforge,
Savannah, and the Java™ Community's java.net has made establishing a repository for an open
source project relatively straightforward. A large third-party
marketplace of add-ons has grown up around CVS with tools like
TortoiseCVS, ViewCVS, and Fisheye.
Compared to other version control systems, CVS is most notable for
its non-locking repository, which allows multiple developers to
check out the same file at the same time. CVS resolves conflicts at
commit time, which prevents it from becoming a bottleneck to progress.
The second notable feature of CVS is that it's a network repository.
Programmers on many different systems can access the same repository
over the public Internet.
Outgrowing CVS
While CVS has served the community well over the last 10 years, it is
showing its age. First of all, it can really only handle ASCII files.
Unicode text confuses it badly. Furthermore, CVS repositories are very
hard to change. CVS has no concept of a "move" operation. It can only
note that a file has been deleted in one place and another file created
in a new location. Since it doesn't connect the two operations, it can
easily lose track of the history of a file. When you set up an CVS
repository, you have to be very careful about choosing the exact
location of each file because from that point on you're pretty much
stuck with it.
It has gradually become apparent that CVS is no longer adequate for
modern development. In particular, while CVS serves the ASCII needs of
old-fashioned C programmers, it really doesn't work for Web developers
and other nontraditional users. When you start thinking about storing
an entire Web site in CVS, moving files from one directory to another
becomes critical. Thus a few years ago, many of the core CVS developers
decided it was time to create a next-generation source code repository from
scratch, using the lessons they had learned while working on and with
CVS over the years. In early 2004, their labor bore fruit with
Subversion 1.0.
Subversion support and adoption
Programmers (especially those who rely on version control) are a
cautious bunch, and Subversion has been slow to catch on. Few programmers
wanted to be on the bleeding edge, even if they were already bleeding a
little from the sharp edges of CVS. Even after Subversion became
reliable, it took a couple of years for all the third-party editors,
IDEs, and documentation to catch up. Still, Subversion has continued to
improve, and third-party tools such as BBEdit and Eclipse now have
adequate-to-good Subversion support. Increasingly, new projects are
choosing Subversion for their version control needs, and old
projects are migrating. Most recently, the Apache Software Foundation has
migrated to Subversion. Projects that have already made the shift
include the Xerces XML parser, the Apache HTTP Server, and Spamassassin.
Using Subversion from an IDE
You can use Subversion from the command line, but it's much more
convenient if it's integrated with your IDE. IntelliJ IDEA 5.0 and later
include built-in support for Subversion. NetBeans doesn't yet support
Subversion, but work is under way to add support in future versions. For
Eclipse, you'll need to install the Subclipse plug-in. I use Eclipse as my IDE in this article.
Subclipse installs like any other Eclipse plug-in:
- In Eclipse, go to Help Software Updates | Find and Install....
- In the first panel of the wizard, click the Search for new features to install radio button and click Next.
- In the second panel of the wizard, click New Remote Site. Enter
Subclipse for the name
and http://subclipse.tigris.org/update_1.0.x for the URL. Then click Finish.
This launches another small wizard. The next dialog should offer you
one feature to install, Subclipse. Check it and click Next.
- Accept the license agreement and complete the installation.
The package is not currently digitally
signed, but as long as you're downloading from the URL in step 3, it should
be safe.
|
Shortcuts to Subversion
If you're using Subversion frequently, you'll probably want to add it
to Eclipse's New, Open Perspective, and Show View
menus. To do this, go to Window/Customize Perspective... and
check SVN in the Shortcut categories list. This makes Subversion
accessible in all the menus where you find CVS now.
|
|
After the package is installed, you must restart Eclipse before
you can use Subversion. Once you've done this, you can use Subversion
pretty much like you use CVS today, though there are a few differences.
Checking out a project
Setting up a new Subversion repository, especially a network repository, is
relatively complex. However, if you're joining an existing project,
checking out the files the first time is easy. Go to the File
menu and select New/Other.... These steps bring up
the dialog shown in Figure 1:
Figure 1. Starting a new project from Subversion
Next, open the SVN folder, choose Select Checkout Projects from SVN, and press Next to display the dialog shown in
Figure 2:
Figure 2. Select/Create Location
The first time you check out from a repository, you need to
select Create a new repository location and press Next.
This brings you to the dialog in Figure 3:
Figure 3. Type a URL for the repository
Here you provide the URL of your repository. This is just an
ordinary http URL such as
http://svn.apache.org/repos/asf/xerces/java/. When you click
Next this time, Eclipse connects to the repository and looks
for folders you can check out. Usually there are three: branches,
tags, and trunk, as shown in Figure 4. Branches are for experiments. Tags normally identify
older, already released versions of the software. However, most of the
time, you'll want to work on the main branch (what CVS calls the HEAD), so
select trunk, and click Next.
Figure
4. Choosing the revision to check out
You now have two options: Check out as a Project configured
using the New Project Wizard or Check out as a project in the
workspace, as shown in Figure 5. You can use whichever you prefer.
You probably also want to give the project a name because the default
is "trunk." Finally, click Finish.
Figure
5. Two ways to check out a project
Eclipse now downloads all the source files from the branch,
trunk, or tag you've selected. If you've selected Check out as a project in
the workspace, you have to go through Eclipse's New Project
wizard to set up the compiler level, project layout, and other
options. If you did not use the New Project wizard, you need to set
up the build path and other options manually, just as if you had created
a project from a directory on your file system. Indeed, that's pretty much what
you've done. All files are stored locally. For normal operations like
building, running, and debugging, Eclipse doesn't care whether or not
the files were checked out of version control.
Verifying the setup
At this point, it's a good idea to do a quick sanity check to make
sure you've set up the build path properly. If there are no obvious
problems and you can run the unit tests, you're good to go.
If there is a problem, check the project properties to make sure the
source path and classpath are set properly. It's not uncommon to have
them off by one, either up or down, so you end up with classes that
Eclipse thinks are named something like src.org.apache.xerces.parsers.SAXParser or apache.xerces.parsers.SAXParser instead of org.apache.xerces.parsers.SAXParser. In
multifolder projects, it's also common for Eclipse to mistakenly tag a
data folder as a source folder or omit a source folder. If any of these
glitches have occurred, you need to fix them before continuing.
|
Multiple-file commits
Subversion can commit several files in one atomic operation. (CVS, by
contrast, treats each separate file as an individual commit.) To do
this, just select all the files you want to commit in the Package
Explorer (probably by Control-clicking or Command-clicking each one in
sequence) and then select Team/Commit... from the context menu.
This is especially useful if you later need to back out a change, or
revert the repository to a state before a particular change.
|
|
To check for errors, select Project | Properties and then find Java Build
Path. The source tab is where you can fix anything the wizard
has done wrong. You may also need to add extra JAR archives required by
the project, which Eclipse didn't notice upon check out. You also do
this under Java Build Path but in the library tab.
Expect to spend a little time on this. Eclipse rarely gets
everything right the first time, and each project organizes its files
and libraries at least a little differently.
Synchronizing with the
repository
You can now edit the files as usual. Make any changes you like. Run
the unit tests. Optimize the code. Correct spelling errors in the
comments. When you've finished some piece of work, use the context menu
and select Team/Commit.... You are presented with the
dialog shown in Figure 6 and asked to enter a commit comment:
Figure
6. Subclipse commit dialog
Likewise, if someone else has made changes in the
repository you want to apply to your copy, just select the file in the
Package Explorer and choose Team/Update from the context menu.
This replaces your copy with the master copy.
Merging
If you've made changes and other developers have also, you may have to
merge the files manually. For most simple changes, Subversion can figure
out what to do without any human intervention. However for large,
complex, and conflicting changes, you may need to help it out by merging
the changes manually.
Subclipse can help out here, but to be honest, I usually find it
easier to simply make a scratch copy of my file in a separate window or
tab, update my local copy from the repository so my changes are
overwritten, and then re-enter them from the scratch copy. If the changes
in the repository are fairly minor compared to what I've been doing,
then I make the scratch copy from the repository and commit over
that instead of updating. Then I reapply those changes. This sounds
complicated, but it usually isn't, and it doesn't happen nearly as often
as you'd expect. Even if you make a mistake and forget to reapply or
misapply a change, there's always a complete history of all changes
(including the ones you overwrote) to refer to. Nothing is ever
completely lost.
If you aren't sure which files have changed, the synchronize view shows you. You can also turn on label decorations to see which files
have changed since the last commit/update. Go to Window |
Preferences and then select the General/Appearance/Label
Decorations. There you'll check the SVN checkbox. (This really
should be checked by default.)
Patching
If you don't have commit access to the repository you're working
with, you need to make a patch and send it to the maintainers
instead. Just select the files you want to compare and select
Team/Create Patch... from the context menu. You can save the
patch to a file or the clipboard as convenient. Then you can e-mail the
patch to the maintainers or attach it to a bug report. The patch itself
is in the same diff format that CVS uses.
Applying patches others send you is no more complex. Just select the
file or project you want to patch. Select Team/Apply Patch...
from the context menu and then choose the patch file using your
platform's customary open file dialog box.
Diffing
If you've made some changes and want to see how your copy differs
from what's in the repository, just select Compare/Latest From
Repository from the context menu. This works virtually the same as it
does with CVS. Figure 7 shows the diff function at work:
Figure
7. Comparing two files in Subclipse
Deleting
Deleting files is also easy. Just delete the file from Eclipse's package
manager and then commit the parent folder. Deleting directories
is a little trickier. You can select a directory and delete it. All the
files in the directory are immediately deleted. However, as soon as you
do that, the directory itself and all its subdirectories pop right back
up again. To really delete a folder, you need to select the "deleted"
folder and commit it. The same applies when moving a file from one place
to another.
|
Be careful!
The Apache Project has already gotten itself into trouble by
committing source code to its Subversion repository that it doesn't own
and now can't remove. Apache can hide the code, but if you know where to
look, it's still there. The owner of the source code in question
could be nasty and send a DMCA takedown notice to
Apache's ISP and knock Apache off the Internet. The only defense
for Apache would be to thoroughly hose its repository.
|
|
After you've deleted a file or a folder, you can still get it back
from the repository, even after you've committed it. You never really
lose anything permanently once it's in the repository, which is sometimes
a problem. For instance, suppose you discover someone has accidentally
checked in their entire home directory including their Quicken data
files and the complete archive of love letters from their significant
other. You'd like to be able to obliterate the mistakenly
committed files so no one can ever get them back. While this is an
unusual operation (after all the purpose of a version control system is
to keep every revision of every file forever), sometimes it's necessary.
Sadly, Subversion is missing this one critical feature.
Not having an obliterate command makes me nervous about using Subversion
for externally visible repositories. CVS doesn't have an obliterate
command either; but in CVS, it is possible to manually delete mistakenly
committed files without damaging the repository.
In conclusion
For internal repositories, Subversion is a vast improvement over CVS. Once some kind of obliteration functionality is added, it should be suitable for external repositories as well. While third-party Subversion support in tools like Eclipse is not quite as widespread as support for CVS, this is changing rapidly. As a free, open-source option where a more powerful and mature option such as Rational® ClearCase is not available, Subversion provides a sound source code repository for new projects, as well as existing projects that don't have source code control. Existing projects that already have CVS repositories may wish to wait until all the tools they depend on fully support Subversion before switching.
Resources Learn
-
Rational ClearCase: IBM's software configuration management product for medium to large development teams. Download the trial version today.
- "Sharing code with the Eclipse Platform" (Pawel Leszek, developerWorks, March 2003): An overview of how the Eclipse platform handles source code
version control.
- "Create a blog from scratch with PHP and Subversion" (Tyler Anderson, developerWorks, February 2006): A tutorial introduction to Web development with PHP and Subversion.
- "Automate your team's build and unit-testing process" (Mark Wilkinson, developerWorks, October 2005): Create an automated system to build and test your source code using (among other things) CVS and Subversion.
- "Pragmatic
Version Control using Subversion, 2nd Edition" (Mike Mason, The
Pragmatic Programmers, May 2006): A complete introduction to using
Subversion.
-
Version Control with
Subversion
(Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato; O'Reilly Media): A free online book about Subversion.
-
Sourceforge: Offers free
Subversion hosting for open source projects.
-
The Java technology
zone: Hundreds of articles about every aspect of Java
programming.
Get products and technologies
-
Subversion: Source code and
binaries for various platforms.
-
Subclipse: The Eclipse Subversion
plug-in.
-
Teepee: The
NetBeans Subversion project.
-
TMate: The IntelliJ IDEA
Subversion plug-in.
Discuss
About the author | 
| | Elliotte Rusty Harold is originally from New Orleans, to which he
returns periodically in search of a decent bowl of gumbo. However, he
resides in the Prospect Heights neighborhood of Brooklyn with his wife
Beth and cats Charm (named after the quark) and Marjorie (named after
his mother-in-law). He's an adjunct professor of computer science at
Polytechnic University, where he teaches Java and object-oriented
programming. His Cafe au Lait
Web site has become one of the most popular independent Java sites on
the Internet, and his spin-off site, Cafe con Leche, has become one of the most popular XML sites. His books include
Effective XML
,
Processing XML with Java
,
Java Network Programming
, and
Java I/O
.
He's currently working on the XOM API for processing XML, the Jaxen XPath engine, and the Jester test coverage tool. |
Rate this page
| |
