A.5. Using Subversion

A.5.1. Introduction

As of July 2012, FreeBSD uses Subversion (svn) as the primary version control system for storing all of FreeBSD's source code, documentation, and the Ports Collection.

Note:

Subversion is generally a developer tool. Most users should use FreeBSD Update to update the FreeBSD base system, and Portsnap to update the FreeBSD Ports Collection.

In Subversion, URLs are used to designate a repository, taking the form of protocol://hostname/path. Mirrors may support different protocols as specified below. The first component of the path is the FreeBSD repository to access. There are three different repositories, base for the FreeBSD base system source code, ports for the Ports Collection, and doc for documentation. For example, the URL svn://svn0.us-east.FreeBSD.org/ports/head/ specifies the main branch of the ports repository on the svn0.us-east.FreeBSD.org mirror, using the svn protocol.

A.5.2. Installation

Subversion must be installed before it can be used to check out the contents of any of the repositories. If a copy of the ports tree is already present, one can install Subversion like this:

# cd /usr/ports/devel/subversion
# make install clean

If the ports tree is not available, Subversion can be installed as a package:

# pkg_add -r subversion

If pkgng is being used to manage packages, Subversion can be installed with it instead:

# pkg install devel/subversion

A.5.3. Running Subversion

The svn command is used to fetch a clean copy of the sources into a local directory. The files in this directory are called a local working copy.

Warning:

If the local directory already exists but was not created by svn, rename or delete it before the checkout. Checkout over an existing non-svn directory can cause conflicts between the existing files and those brought in from the repository.

A checkout from a given repository is performed with a command like this:

# svn checkout svn-mirror/repository/branch lwcdir

where:

  • svn-mirror is a URL for one of the Subversion mirror sites.

  • repository is one of the Project repositories, i.e., base, ports, or doc.

  • branch depends on the repository used. ports and doc are mostly updated in the head branch, while base maintains the latest version of -CURRENT under head and the respective latest versions of the -STABLE branches under stable/8 (for 8.x), stable/9 (9.x) and stable/10 (10.x).

  • lwcdir is the target directory where the contents of the specified branch should be placed. This is usually /usr/ports for ports, /usr/src for base, and /usr/doc for doc.

This example checks out the Ports Collection from the western US repository using the HTTPS protocol, placing the local working copy in /usr/ports. If /usr/ports is already present but was not created by svn, remember to rename or delete it before the checkout.

# svn checkout https://svn0.us-west.FreeBSD.org/ports/head /usr/ports

Because the initial checkout has to download the full branch of the remote repository, it can take a while. Please be patient.

After the initial checkout, the local working copy can be updated by running:

# svn update lwcdir

To update /usr/ports created in the example above, use:

# svn update /usr/ports

The update is much quicker than a checkout, only transferring files that have changed.

An alternate way of updating the local working copy after checkout is provided by the Makefile in the /usr/ports, /usr/src, and /usr/doc directories. Set SVN_UPDATE and use the update target. For example, to update /usr/src:

# cd /usr/src
# make update SVN_UPDATE=yes

A.5.4. For More Information

For other information about using Subversion, please see the Subversion Book, titled Version Control with Subversion, or the Subversion Documentation.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.