The first is to check out directly from the main repository. For the src tree, use:

% svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src

For the doc tree, use:

% svn checkout svn+ssh://svn.freebsd.org/doc/head /usr/doc

For the ports tree, use:

% svn checkout svn+ssh://svn.freebsd.org/ports/head /usr/ports

The above command will check out a CURRENT source tree as /usr/src/, which can be any target directory on the local filesystem. Omitting the final argument of that command causes the working copy, in this case, to be named “head”, but that can be renamed safely.

svn+ssh means the SVN protocol tunnelled over SSH. The name of the server is svn.freebsd.org, base is the path to the repository, and head is the subdirectory within the repository.

If your FreeBSD login name is different from your login name on your local machine, you must either include it in the URL (for example svn+ssh://[email protected]/base/head), or add an entry to your ~/.ssh/config in the form:

Host svn.freebsd.org
	User jarjar

This is the simplest method, but it is hard to tell just yet how much load it will place on the repository.

Check out a working copy from a mirror by substituting the mirror's URL for svn+ssh://svn.freebsd.org/base. This can be an official mirror or a mirror maintained by using svnsync.

There is a serious disadvantage to this method: every time something is to be committed, a svn relocate to the master repository has to be done, remembering to svn relocate back to the mirror after the commit. Also, since svn relocate only works between repositories that have the same UUID, some hacking of the local repository's UUID has to occur before it is possible to start using it.

The hassle of a local svnsync mirror probably is not worth it unless the network connectivity situation or other factors demand it. If it is needed, see the end of this chapter for information on how to set one up.

In svn+ssh://svn.freebsd.org/base, base refers to the source tree. Similarly, ports refers to the ports tree, and so on. These are separate repositories with their own change number sequences, access controls and commit mail.

For the base repository, HEAD refers to the -CURRENT tree. For example, head/bin/ls is what would go into /usr/src/bin/ls in a release. Some key locations are:

In svn+ssh://svn.freebsd.org/doc, doc refers to the repository root of the source tree.

In general, most FreeBSD Documentation Project work will be done within the head/ branch of the documentation source tree.

FreeBSD documentation is written and/or translated to various languages, each in a separate directory in the head/ branch.

Each translation set contains several subdirectories for the various parts of the FreeBSD Documentation Project. A few noteworthy directories are:

In svn+ssh://svn.freebsd.org/ports, ports refers to the repository root of the ports tree.

In general, most FreeBSD port work will be done within the head/ branch of the ports tree which is the actual ports tree used to install software. Some other key locations are:

SVN has built in help documentation. It can be accessed by typing the following command:

% svn help

Additional information can be found in the Subversion Book.

As seen earlier, to check out the FreeBSD head branch:

% svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src

At some point, more than just HEAD will probably be useful, for instance when merging changes to stable/7. Therefore, it may be useful to have a partial checkout of the complete tree (a full checkout would be very painful).

To do this, first check out the root of the repository:

% svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base

This will give base with all the files it contains (at the time of writing, just ROADMAP.txt) and empty subdirectories for head, stable, vendor and so on.

Expanding the working copy is possible. Just change the depth of the various subdirectories:

% svn up --set-depth=infinity base/head
% svn up --set-depth=immediates base/release base/releng base/stable

The above command will pull down a full copy of head, plus empty copies of every release tag, every releng branch, and every stable branch.

If at a later date merging to 7-STABLE is required, expand the working copy:

% svn up --set-depth=infinity base/stable/7

Subtrees do not have to be expanded completely. For instance, expanding only stable/7/sys and then later expand the rest of stable/7:

% svn up --set-depth=infinity base/stable/7/sys
% svn up --set-depth=infinity base/stable/7

Updating the tree with svn update will only update what was previously asked for (in this case, head and stable/7; it will not pull down the whole tree.

It is possible to anonymously check out the FreeBSD repository with Subversion. This will give access to a read-only tree that can be updated, but not committed back to the main repository. To do this, use the following command:

% svn co https://svn0.us-west.FreeBSD.org/base/head /usr/src

Select the closest mirror and verify the mirror server certificate from the list of Subversion mirror sites.

To update a working copy to either the latest revision, or a specific revision:

% svn update
% svn update -r12345

To view the local changes that have been made to the working copy:

% svn status

To show local changes and files that are out-of-date do:

% svn status --show-updates

Unlike Perforce, SVN does not need to be told in advance about file editing.

To commit all changes in the current directory and all subdirectories:

% svn commit

To commit all changes in, for example, lib/libfetch/ and usr/bin/fetch/ in a single operation:

% svn commit lib/libfetch usr/bin/fetch

There is also a commit wrapper for the ports tree to handle the properties and sanity checking your changes:

% /usr/ports/Tools/scripts/psvn commit

Files are added to a SVN repository with svn add. To add a file named foo, edit it, then:

% svn add foo

Files can be removed with svn remove:

% svn remove foo

Subversion does not require deleting the file before using svn rm, and indeed complains if that happens.

It is possible to add directories with svn add:

% mkdir bar
% svn add bar

Although svn mkdir makes this easier by combining the creation of the directory and the adding of it:

% svn mkdir bar

Like files, directories are removed with svn rm. There is no separate command specifically for removing directories.

% svn rm bar

This command creates a copy of foo.c named bar.c, with the new file also under version control:

% svn copy foo.c bar.c

The example above is equivalent to:

% cp foo.c bar.c
% svn add bar.c

To move and rename a file:

% svn move foo.c bar.c

svn log shows revisions and commit messages, most recent first, for files or directories. When used on a directory, all revisions that affected the directory and files within that directory are shown.

svn annotate, or equally svn praise or svn blame, shows the most recent revision number and who committed that revision for each line of a file.

svn diff displays changes to the working copy. Diffs generated by SVN are unified and include new files by default in the diff output.

svn diff can show the changes between two revisions of the same file:

% svn diff -r179453:179454 ROADMAP.txt

It can also show all changes for a specific changeset. The following will show what changes were made to the current directory and all subdirectories in changeset 179454:

% svn diff -c179454 .

Local changes (including additions and deletions) can be reverted using svn revert. It does not update out-of-date files, but just replaces them with pristine copies of the original version.

If an svn update resulted in a merge conflict, Subversion will remember which files have conflicts and refuse to commit any changes to those files until explicitly told that the conflicts have been resolved. The simple, not yet deprecated procedure is the following:

% svn resolved foo

However, the preferred procedure is:

% svn resolve --accept=working foo

The two examples are equivalent. Possible values for --accept are:

SVN allows sparse, or partial checkouts of a directory by adding --depth to a svn checkout.

Valid arguments to --depth are:

The --depth option applies to many other commands, including svn commit, svn revert, and svn diff.

Since --depth is sticky, there is a --set-depth option for svn update that will change the selected depth. Thus, given the working copy produced by the previous example:

% cd ~/freebsd
% svn update --set-depth=immediates .

The above command will populate the working copy in ~/freebsd with ROADMAP.txt and empty subdirectories, and nothing will happen when svn update is executed on the subdirectories. However, the following command will set the depth for head (in this case) to infinity, and fully populate it:

% svn update --set-depth=infinity head

Certain operations can be performed directly on the repository without touching the working copy. Specifically, this applies to any operation that does not require editing a file, including:

Branching is very fast. The following command would be used to branch RELENG_8:

% svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/stable/8

This is equivalent to the following set of commands which take minutes and hours as opposed to seconds, depending on your network connection:

% svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base
% cd base
% svn update --set-depth=infinity head
% svn copy head stable/8
% svn commit stable/8

This section deals with merging code from one branch to another (typically, from head to a stable branch).

% svn merge -c r123456 ^/head/ checkout
% svn commit checkout

% svn merge -c r123456 ^/stable/10 releng/10.0

% cd stable/7
% svn up --set-depth=infinity

% cd stable/6/contrib/openpam
% svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam

% svn propget svn:mergeinfo -R $target
$target - /head/$source:$P,$Q

% svn merge -c$R $FSVN/head/$source $target

% svn propget svn:mergeinfo -R $target
$target - head/$source:$P,$Q,$R

% svn propget svn:mergeinfo -R stable/9/share/man/man4

% svn merge -c r238987 svn+ssh://svn.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4
--- Merging r238987 into 'stable/9/share/man/man4':
U    stable/9/share/man/man4/netmap.4
--- Recording mergeinfo for merge of r238987 into
'stable/9/share/man/man4':
 U   stable/9/share/man/man4

% svn commit stable/9/share/man/man4

Reverting a commit to a previous version is fairly easy:

% svn merge -r179454:179453 ROADMAP.txt
% svn commit

Change number syntax, with negative meaning a reverse change, can also be used:

% svn merge -c -179454 ROADMAP.txt
% svn commit

This can also be done directly in the repository:

% svn merge -r179454:179453 svn+ssh://svn.freebsd.org/base/ROADMAP.txt

Reverting the deletion of a file is slightly different. Copying the version of the file that predates the deletion is required. For example, to restore a file that was deleted in revision N, restore version N-1:

% svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454
% svn commit

or, equally:

% svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://svn.freebsd.org/base

Do not simply recreate the file manually and svn add it—this will cause history to be lost.

While we can do surgery in an emergency, do not plan on having mistakes fixed behind the scenes. Plan on mistakes remaining in the logs forever. Be sure to check the output of svn status and svn diff before committing.

Mistakes will happen but, they can generally be fixed without disruption.

Take a case of adding a file in the wrong location. The right thing to do is to svn move the file to the correct location and commit. This causes just a couple of lines of metadata in the repository journal, and the logs are all linked up correctly.

The wrong thing to do is to delete the file and then svn add an independent copy in the correct location. Instead of a couple of lines of text, the repository journal grows an entire new copy of the file. This is a waste.

You probably do not want to do this unless there is a good reason for it. Such reasons might be to support many multiple local read-only client machines, or if your network bandwidth is limited. Starting a fresh mirror from empty would take a very long time. Expect a minimum of 10 hours for high speed connectivity. If you have international links, expect this to take 4 to 10 times longer.

A far better option is to grab a seed file. It is large (~1GB) but will consume less network traffic and take less time to fetch than a svnsync will. This is possible in one of the following three ways:

% rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .

% rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .

% fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz

Once you have the file, extract it to somewhere like home/svnmirror/base/. Then, update it, so that it fetches changes since the last revision in the archive:

% svnsync sync file:///home/svnmirror/base

You can then set that up to run from cron(8), do checkouts locally, set up a svnserve server for your local machines to talk to, etc.

The seed mirror is set to fetch from svn://svn.freebsd.org/base. The configuration for the mirror is stored in revprop 0 on the local mirror. To see the configuration, try:

% svn proplist -v --revprop -r 0 file:///home/svnmirror/base

Use propset to change things.

Files that have high-ASCII bits are considered binary files in SVN, so the pre-commit checks fail and indicate that the mime-type property should be set to application/octet-stream. However, the use of this is discouraged, so please do not set it. The best way is always avoiding high-ASCII data, so that it can be read everywhere with any text editor but if it is not avoidable, instead of changing the mime-type, set the fbsd:notbinary property with propset:

% svn propset fbsd:notbinary yes foo.data

A project branch is one that is synced to head (or another branch) is used to develop a project then commit it back to head. In SVN, “dolphin” branching is used for this. A “dolphin” branch is one that diverges for a while and is finally committed back to the original branch. During development code migration in one direction (from head to the branch only). No code is committed back to head until the end. Once you commit back at the end, the branch is dead (although you can have a new branch with the same name after you delete the branch if you want).

As per http://people.freebsd.org/~peter/svn_notes.txt, work that is intended to be merged back into HEAD should be in base/projects/. If you are doing work that is beneficial to the FreeBSD community in some way but not intended to be merged directly back into HEAD then the proper location is base/user/your-name/. This page contains further details.

To create a project branch:

% svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/projects/spif

To merge changes from HEAD back into the project branch:

% cd copy_of_spif
% svn merge svn+ssh://svn.freebsd.org/base/head
% svn commit

It is important to resolve any merge conflicts before committing.