3 Installing and Configuring Subversion for Version Control
This chapter describes how to install and configure Subversion for version control.
Topics:
- Downloading Subversion
Although Subversion is an Apache project, Apache does not build their own binary files for any operating system. Third parties build binary files for all major operating systems. - Installing Subversion
You can install Subversion on any major platform. - Configuring the Subversion Server as a Service
To ensure that Subversion is running when you need it, configure it as a service. - Setting Up a Repository
A Subversion repository is a collection of versioned artifacts on the Subversion server. - Understanding the SVN Workflow
Before you start working in SVN, you should understand the typical workflow. - Working with Subversion Projects
When you are working with Subversion projects, you check out the files into your local file system. Then, when you are ready to commit the files to the repository, you check the project in. - Considerations for Tagging and Branching
Tagging creates a named point-in-time copy of a branch. - About Subversion Clients
There are several Subversion clients that are available. - More Information About Subversion
This document is meant as a quick guide for starting and running Subversion and does not provide extensive detail on Subversion operations.
Downloading Subversion
Although Subversion is an Apache project, Apache does not build their own binary files for any operating system. Third parties build binary files for all major operating systems.
The following URL provides links to the latest stable releases of Subversion built by third parties for all major operating systems:
http://subversion.apache.org/packages.html
If possible, use a package manager such as YUM or APT to manage the installation of other software.
On Windows, Oracle recommends that you use a precompiled binary package such as Silk SVN which is available in the following URL:
On Windows, if you install Subversion through the installer package, then ensure that you choose an installer which includes the server binary files.
Installing Subversion
You can install Subversion on any major platform.
The installation method varies depending upon the platform and distribution method.
For example, if you use YUM, the command is likely to be:
sudo yum install subversion
On Windows, you can change the default installation path to a shorter location:
C:\svn
Ensure that the PATH
variable is correctly set by the installer.
To obtain the version information of svnserve
, run the following command:
svnserve --version
If you cannot find the command, then do the following:
- Open Control Panel.
- Select System, and then Advanced System Settings.
- Under Advanced, select Environment Variables.
- Edit the
PATH
variable in the System variables pane by adding the path to the Subversion binary directory.
Configuring the Subversion Server as a Service
To ensure that Subversion is running when you need it, configure it as a service.
To configure the Subversion server as a service:
-
On Linux
The Linux installation process automatically creates an
/etc/init.d/svnserve
script. This starts the server when you start up your system.To start the service manually, run the following command:
sudo /etc/init.d/svnserve start
-
On Windows
You must register
svnserve
with the service manager. To registersvnserve
, run the following command:sc create svnserver binpath= "C:\svn\svnserve.exe" --service -r "REPOS_PATH" displayname="Subversion" depend=Tcpip start=auto
In the preceding command,
REPOS_PATH
is the absolute path to the local file system.
Setting Up a Repository
A Subversion repository is a collection of versioned artifacts on the Subversion server.
This section contains the following topics:
- Creating a Repository
After Subversion is installed, you must create a repository. The command-line utility calledsvnadmin
is the primary tool for server-side administrative operations. - Using a Consistent Subversion Layout
Although Subversion does not require any particular subdirectory structure within a repository, it is a good idea to follow an established convention, as this book does. - Importing Existing Projects
Creating a Repository
After Subversion is installed, you must create a repository. The command-line utility called svnadmin
is the primary tool for server-side administrative operations.
To create a repository:
Access to the repository is controlled by file permissions and the user referenced for accessing the repository through the SVN client. Ensure that user and group permissions for all files in the new repository reflect the type of access control that you want to have over the repository contents.
By default, anonymous, read-only access is enabled for a new repository. This means that anyone with SSH access, regardless of repository permissions settings, can check out repository files. You can modify this in the REPOS_PATH
/conf/svnserve.conf
file.
Now that you have created a repository, you can use the Subversion client to perform standard operations against the new repository by using the following base URL:
svn+ssh://USER@HOST/REPOS_PATH
For example:
svn ls svn+ssh://mycompany@localhost/ciroot/subversion/repository
In addition to svn+ssh
, there are several other protocols that are supported by Subversion. Refer to the Subversion documentation for information on how to configure other protocols. svn+ssh
might not be available on Windows by default.
Parent topic: Setting Up a Repository
Using a Consistent Subversion Layout
Although Subversion does not require any particular subdirectory structure within a repository, it is a good idea to follow an established convention, as this book does.
The typical repository layout should resemble the following figure:
Development of the main code line occurs in the trunk
directories. When a release is made, the current trunk source is copied into the tags
directory, to a tag corresponding to the release. Subversion copy operations are not expensive in terms of storage because the server tracks changes internally.
The following is an example of a tag:
my-project/tags/3.0.5
In the preceding example, 3.0.5
indicates the release version to which this tag corresponds.
A tag is important for future work that might be necessary for patch creation or bug-fix releases. Another importance of a release tag is to facilitate investigation regarding issues in the associated release.
If a patch or subsequent change of a tag is considered necessary, you must create a branch. A branch is a copy of a location elsewhere in the repository and does not differ in composition from a tag. After a copy of the tag is made under the branches
directory, you can check out the code and modify it as necessary. When changes are complete, the new release is made from the branch and a corresponding tag is created.
The following Project-A example outlines the general workflow for patch management of source code:
-
In Project-A, the main code line is managed under
project-A/trunk
. The current version developing under thetrunk
directory is version 2.1. The three previous releases of Project-A are 1.0, 1.1, and 2.0. -
A problem is discovered in version 1.0 that requires a patch release.
-
To address the problem, the
project-A/tags/1.0
tag is copied, using thesvn copy
command, toproject-A/branches/1.0.1-SNAPSHOT
. TheSNAPSHOT
designation is a Maven device indicating a version that is not yet released, as shown in the following figure: -
When the branch code fix is complete, the branch is copied from
project-A/branches/1.0.1-SNAPSHOT
to aproject-A/tags/1.0.1
tag. The release build can then be made from the tag.
For more information on directory structure conventions, see the section about the recommended repository layout in Version Control with Subversion at:
Parent topic: Setting Up a Repository
Importing Existing Projects
If you have existing projects that you want to manage in your repository, you can import them using the SVN client's import
command:
svn import LOCAL_PATH REPOSITORY_URL/REPOSITORY_PATH
For example:
svn import /checkouts/project-a svn+ssh://user@svn.mycompany.com/ciroot/subversion/repository/project-a/trunk/ -m "initial import"
Parent topic: Setting Up a Repository
Understanding the SVN Workflow
Before you start working in SVN, you should understand the typical workflow.
To modify code, you usually perform the following operations:
-
Update the working copy using the
svn update
command. -
Make changes. Use the
svn add
,svn delete
,svn copy
, andsvn move
commands as needed to edit your files. -
Review changes through the
svn status
andsvn diff
commands. -
Fix mistakes. You can revert and abandon changes using the
svn revert
command. -
Resolve conflicts. When they are resolved, mark them using the
svn resolve
command. -
Commit changes using the
svn commit
orsvn ci
command.
Figure 3-1 shows the complete life cycle of an SVN operation:
In a continuous integration development process, this workflow remains largely unchanged. Committed change sets tend to be smaller and occur more frequently than in a noncontinuous integration process. You must commit the active trunk or branch code for the target release so that the continuous integration system can perform an integration build. Avoid creating a personal branch with the intention of merging back to the main-line code base in the future. The personal branch and merge technique defers integration and runs counter to continuous integration precepts.
Working with Subversion Projects
When you are working with Subversion projects, you check out the files into your local file system. Then, when you are ready to commit the files to the repository, you check the project in.
To begin working on a Subversion-managed project, you must first check out the files into your local file system. The SVN client copies the project files to your system, including Subversion metadata in .svn
directories located in each subdirectory.
To work with Subversion projects:
Considerations for Tagging and Branching
Tagging creates a named point-in-time copy of a branch.
Tag releases on the following occasions:
-
Whenever a project is released
-
Whenever an important milestone occurs
It is important to tag releases, as tags provide a simple mechanism for patching releases. When a bug is found in a release, you can branch from the tag for that release, implement the fix, and then create a patch for the release. Tag this new (patched) release as well, in case you find an issue with it later and need to fix that new issue.
If you do not tag a release, it is very difficult to obtain the exact code line that was built into that release.
Note:
Treat tagged releases as read-only artifacts. You must not continue merging into a release after it is tagged.
About Subversion Clients
There are several Subversion clients that are available.
This section describes two popular Subversion clients:
WebSVN
WebSVN provides a web-based view of a repository and supports visual differences, blame, and search.
WebSVN can be downloaded from:
Parent topic: About Subversion Clients
TortoiseSVN
TortoiseSVN is a free Windows Subversion client that integrates with Windows Explorer. All standard Subversion client operations can be performed through the Windows user interface. Folder and file icon decorators indicate the status of Subversion files. Command-line tools are mapped with menu items and options are configurable through dialogs boxes. Tortoise also provides sophisticated graphical diff and merge tools that can be helpful for resolving conflicts.
TortoiseSVN can be downloaded from:
Parent topic: About Subversion Clients
More Information About Subversion
This document is meant as a quick guide for starting and running Subversion and does not provide extensive detail on Subversion operations.
For a detailed guide, see Version Control with Subversion at:
Note:
Oracle strongly recommends reading Version Control with Subversion if you are new to Subversion.