Subversion 1.5 Release Notes

Working Copy Upgrades

WARNING: if a Subversion 1.5 client encounters a pre-1.5 working copy, it will automatically upgrade the working copy format as soon as it touches it, making it unreadable by older Subversion clients. If you are using several versions of Subversion on your machine, be careful about which version you use in which working copy, to avoid accidentally upgrading a working copy. (But note that this "auto upgrade" behavior does not occur with the repositories, only working copies.)

If you accidentally upgrade a 1.4 working copy to 1.5, and wish to downgrade back to 1.4, use the change-svn-wc-format.py script. See this FAQ entry for details, and run the script with the --help option for usage instructions.

Repository Upgrades

The Subversion 1.5 server works with 1.4 and older repositories, and it will not upgrade such repositories to 1.5 unless specifically requested to via the svnadmin upgrade command. This means that some of the new 1.5 features will not become available simply by upgrading your server: you will also have to upgrade your repositories. (We decided not to auto-upgrade repositories because we didn't want 1.5 to silently make repositories unusable by 1.4 — that step should be a conscious decision on the part of the repository admin.)

After running svnadmin upgrade, you may wish to also run the svn-populate-node-origins-index program on the repository. Subversion 1.5 maintains a node-origins index for each repository, and builds the index lazily as the information is needed. But for old repositories with lots of revisions, it's better to create the index in one step, using the aforementioned tool, than to have live queries be slower until the index has built itself. See issue #3024 for details.

Overview

Subversion's merge tracking is designed to:

• Reduce the bookkeeping overhead for branch maintenance
• Avoid common cases of the "repeated merge" problem
• Allow for cherry-picking of changes

Each changeset is identified by its revision number, and merged changesets are recorded in the new svn:mergeinfo property (known colloquially as "mergeinfo") set on the destination of the merge. Subversion keeps mergeinfo up-to-date automatically, but there is also a way to record/unrecord merges manually, since there will always be cases where a human knows something that Subversion doesn't.

User interface

Merging changes from (say) trunk to a branch no longer requires that you specify the revision range. Instead, each time you want to sync up with trunk, you can just do:

   $ cd BRANCH_WORKING_COPY
   $ svn merge URL_TO_TRUNK

Subversion will figure out what changes from URL_TO_TRUNK have not yet been merged and pull in just those changes. When it's time to merge the branch back to trunk, do this:

   $ cd TRUNK_WORKING_COPY
   $ svn merge --reintegrate URL_TO_BRANCH

Below is a more formal description of all the merge-tracking-related interface changes.

The svn merge command takes two new options: --record-only and --reintegrate.

The new svn mergeinfo command can show which changesets a directory has absorbed and which changesets it's still eligible to receive. See Mergeinfo and Previews in the Subversion book for more information.

The svn log and svn blame commands take a new -g (--use-merge-history) option, which tells them to take mergeinfo into account. Without this option, they won't.

The reason for the -g option is that it is sometimes useful to ignore merge history. In blame output you sometimes want to see the person B who merged a change, though other times you want to see the person A who originally wrote the change that B later merged; use -g to get the latter information. In log output, you sometimes want to see exactly the revisions that were committed on a given line of development, though other times you want to see, as part of the same output, the original changes that were later ported as merge revisions; again, -g includes the latter information (tagged with lines that say "Merged via: " followed by the revision number in which the merge took place). See Merge-Sensitive Logs and Annotations in the Subversion book for more details.

Merge tracking and compatibility

As described earlier, merge-tracking is not supported unless you upgrade the repository as well as the server.

If you were using the svnmerge wrapper program to do merging, and now want to switch to using Subversion 1.5's native merge-tracking, then you should use the svnmerge-migrate-history.py script to convert svnmerge's custom properties to the svn:mergeinfo properties that Subversion itself now uses.

Known Issues

There are still known issues with merge tracking in 1.5.0. We're working on the most important ones first, which are:

• issue #3128: merge --reintegrate should handle renames better
• issue #2897: proper support for reflective merges
• issue #3126: better change-availability reporting (svn mergeinfo shows too few or too many eligible revisions)
• issue #2837: allow merge tracking to be useful when performing cyclic merging
• issue #3056: avoid repeat merge in an intelligent way
• issue #2898: handle mergeinfo when deleting/adding children you don't have access to
• issue #3067: subtrees that don't exist at the start or end of a merge range shouldn't break the merge
• issue #3157: merging a change from a path's natural history creates self-referential mergeinfo
• issue #3174: merge algorithm chokes on subtrees needing special attention that have been renamed

(See also the list of merge-tracking-related open issues and the list of all merge-related open issues, though note that not all of merge-related issues are about merge-tracking and many predate it.)

Issue #3157 is particularly easy to run into, so here's a more detailed explanation of what the issue is and how to work around it:

Merge tracking information currently can include the "natural history" of a path. One situation where this happens is when creating a branch from trunk at a certain revision X and later merging all changes from branch back to trunk, without explicitly limiting the merge range and without using the --reintegrate option. Afterwards, the merge tracking information on trunk will list revisions before X. This does no harm to future merge operations, but thereafter svn log -g on trunk will report these revisions from the "natural history", which is typically not expected. This is because svn log -g uses the merge tracking information from previous revisions (not only from HEAD).

Note that this should not be a problem with release branches (also called "maintenance branches"), because one typically does not merge them back to trunk. Instead, recommended practice is for new changes to enter on trunk and be ported outward to the branches that need the changes. However, you could run into this problem with a feature branch, which would be merged back to trunk once, at the end of the branch's lifetime.

One workaround is to correct the merge tracking information before committing the merged revision, by reverse merging the "natural history" information: svn merge --record-only -rX:1. Another solution is to avoid this situation entirely, by explicitly specifying merge ranges in the first place, e.g.: -rX:HEAD. See this mail for more information.

When merging a feature branch, the best solution is to use the --reintegrate option; then this problem won't happen in the first place.

Further reading

For more on merge-tracking in Subversion 1.5, see:

• Chapter 4: Branching and Merging in the Subversion book
• Subversion 1.5 merge-tracking in a nutshell (blog post by Ben Collins-Sussman)
• The merge tracking design documents (requirements, use cases, functional spec, design)

Depth overview

Each directory now understands the notion of depth, which has four possible values: empty, files, immediates, infinity. The values are defined as follows:

The --depth option sets depth values as it updates the working copy, tweaking new subdirectories' depth values as described above.

User Interface

Affected commands:

• checkout
• switch
• update
• status
• info

The -N option becomes a synonym for --depth=files for these commands. This changes the existing -N behavior for these commands, but in a trivial way (see below).

checkout without --depth or -N behaves the same as it does today. switch and update without --depth or -N behave the same way as today if and only if the working copy is fully depth-infinity. switch and update without --depth or -N will not change depth values (exception: a missing directory specified on the command line will be pulled in).

Thus, checkout is identical to checkout --depth=infinity, but switch and update are not the same as switch --depth=infinity and update --depth=infinity. The former update entries according to existing depth values, while the latter pull in everything.

To get started, run checkout with --depth=empty or --depth=files. If additional files or directories are desired, pull them in with update commands using appropriate --depth options. The svn status command should list the ambient depths of directories, in addition to whatever other statuses are listed. The svn info command also lists ambient depth, when invoked on a directory whose depth is not the default (depth-infinity)

Note: There is currently no deselection interface for sparse checkouts — that is, there is no command to unselect or "fold up" a subdirectory after you've brought it into a sparse working copy (although there are some fairly easy workarounds to achieve the same effect). See issue #2843 for details.

Compatibility with older servers

The new --depth feature naturally requires the client to be 1.5+, and will work most efficiently if the server is also 1.5+. However, the client will still behave correctly if the server is 1.4.x or lower; things will just be less efficient.

This is because older servers do not understand — and therefore ignore — what the client tells them about "depth". So when a client requests a depth shallower than depth-infinity, older servers will send back more data than the client wants. However, a 1.5+ client will know it's talking to an older server and filter out this extra data. Thus, operations may take a while, because the server sends a lot of data over the network that the client then ignores, but the final result on the client side will be the same. (Note that older servers understand a recurse flag in the network protocols, and 1.5+ clients send that flag based on the depth; this alleviates some of the extra network traffic penalty.)

Further reading

• The Sparse Directories section in the Subversion book.
• The design/implementation document in the repository.

Further reading

• The Changelists section in the Subversion book.
• The design/implementation document in the repository.

Peg revision syntax for URLs

Compatibility and the new syntax: For compatibility reasons, the pre-1.5 svn:externals syntax continues to not understand peg revisions. A new format has been introduced to allow peg revisions in URLs.

The old format of

   foo             http://example.com/repos/zig
   foo/bar -r 1234 http://example.com/repos/zag

does not support peg revisions, and the following externals will not work (unless there are directories named zig@HEAD and zag@HEAD):

   foo             http://example.com/repos/zig@HEAD
   foo/bar -r 1234 http://example.com/repos/zag@HEAD

The new format moves the URL first followed by the directory the external is checked out or exported into; if there is an operative (-r) revision, it precedes the URL. Here are four externals lines:

   http://example.com/repos/zig foo1
   -r 1234 http://example.com/repos/zag foo/bar1
   http://example.com/repos/zig@HEAD foo2
   -r 1234 http://example.com/repos/zag@HEAD foo/bar2

In other words, both operative ("-r") and peg ("@") revisions are allowed, but neither is required.

Support for relative URLs

Prior to Subversion 1.5, the URLs in an svn:externals specification must be absolute. Now they can be relative. Four different relative externals specifications are supported. (In the following examples, assume we have two repositories: one at http://example.com/svn/repos-1 and another at http://example.com/svn/repos-2. We have a checkout of http://example.com/svn/repos-1/project1/trunk and the svn:externals property is set on trunk.)

../

Relative to the directory with the svn:externals property. These URLs always begin with the string ../, for example:

   ../../project2/trunk common/project2/trunk

This will extract http://example.com/svn/repos-1/project2/trunk into common/project2/trunk. The external's URL is relative to the URL of the directory with the svn:externals property, not the directory where the external is written to disk.

^/

Relative to the repository root.

   ^/project2/trunk common/project2/trunk

This will extract http://example.com/svn/repos-1/project2/trunk into common/project2/trunk.

You can also refer to other repositories easily using repository root relative URLs:

   ^/../repos-2/foo/trunk common/foo/trunk

This will extract http://example.com/svn/repos-2/foo/trunk into common/foo/trunk.

//

Relative to the scheme. This copies the scheme of the checkout or export URL into the URL in svn:externals. It is useful when the same hostname must the accessed with different schemes depending upon network location; i.e. clients in the intranet use http:// while external clients use svn+ssh://.

   //example.com/svn/repos-1/project2/trunk common/project2/trunk

This will extract http://example.com/svn/repos-1/project2/trunk into common/project2/trunk. If the working copy was checked out from svn+ssh://example.com/svn/repos-1/project1/trunk then this URL would be svn+ssh://example.com/svn/repos-1/project1/trunk.

/

Server root relative URLs. This copies the scheme and hostname from the checkout or export URL into the svn:externals URL.

   /svn/repos-1/project2/trunk common/project2/trunk

This will extract http://example.com/svn/repos-1/project2/trunk into common/project2/trunk. If the working copy was checked out from svn+ssh://example.com/svn/repos-1/project1/trunk then this URL would be svn+ssh://example.com/svn/repos-1/project1/trunk.

Relative URLs are still supported in the old svn:externals format (that does not support peg revisions).

When Subversion sees an svn:externals without an absolute URL, it takes the first argument as a relative URL and the second as the target directory.

Further reading

See The svn:externals section of the Subversion Book.

Requirements

• Subversion 1.5 or newer.
• Apache HTTP Server 2.2.0 or higher with mod_proxy enabled. (Several fixes to mod_proxy were committed for this patch that were not backported to the 2.0 branch of httpd.)

Example configuration

Participants:

• Slave → slave.example.com (there can be many!)
• Master → master.example.com (there can only be one!)
• A WebDAV client (ra_neon, ra_serf, other WebDAV clients)

Each client does:

    % svn co http://slave.example.com/repos/slave/
    ...
    % svn ci
    % ...etc...

(The client can perform all operations as normal.)

Each slave has:

    <Location /repos/slave>
      DAV svn
      SVNPath /my/local/copy/of/repos
      SVNMasterURI http://master.example.com/repos/master/
    </Location>

The master MUST have a post-commit hook that updates all of the slaves. An example that does this using svnadmin dump/svnadmin load and ssh is provided below. svnsync can probably do the same thing.

Additionally, if locks are permitted on the master repository, lock databases need to kept in sync via post-lock and post-unlock hooks on the master pushing the lock state to the slaves. (Username preservation is left as an exercise to the reader. Translation: patches to these notes are most welcome.) If the lock database is not propogated, users will not be able to accurately determine whether a lock is held — but locking will still work.

A sample synchronization script may look like this:

   #!/bin/sh
   REPOS="$1"
   REV="$2"
   SLAVE_HOST=slave.example.com
   SLAVE_PATH=/my/local/copy/of/repos

   # Ensure svnadmin is in $PATH on both this machine and the remote server!
   svnadmin dump --incremental -r$2 $1 > /tmp/$2.dump
   scp /tmp/$2.dump $SLAVE_HOST:$SLAVE_PATH
   ssh $SLAVE_HOST "svnadmin load $SLAVE_PATH < $SLAVE_PATH/$2.dump"
   ssh $SLAVE_HOST "rm $SLAVE_PATH/$2.dump"
   rm /tmp/$2.dump

Further reading

Additional information about WebDAV proxy support is available in the repository.

Improved copy-handling during updates (client and server)

A common problem in older versions of Subversion was the way in which svn update handled incoming copies and moves.

Consider this scenario: Harry runs svn move foo bar; svn commit, and meanwhile Sally makes local changes to 'foo', and then runs svn update. In earlier versions of Subversion, the server would send down a completely new file 'bar', and unversion the file 'foo' (if it had no uncommitted changes, Subversion would remove it entirely.) From Sally's point of view, her changes seem to be lost; the newly added 'bar' file has the older content, and the file 'foo' has been taken out of version control.

In Subversion 1.5, the client and server both attempt to be smarter about this. The server doesn't send a whole new file during the update, but rather instructions to copy something that likely already exists in the working copy. So Sally's 'foo' file is copied to 'bar' (with local edits intact!).

In theory, this is the best-case scenario. There are a few caveats: this "proper copying" of existing working-copy resources only works on files, not (yet) on directories. Also, if an incoming move-operation deletes 'foo' before it attempts to copy it to 'bar', then the copy will fail, and the client reverts to the old behavior of fetching a pristine copy of the file from the repository. We hope to address this in svn 1.6.

See issue #503 for more.

Peg revisions (client)

Copy and move operations now accept sources with peg ("@") revisions.

See issue #2546 for more.

Multiple working copy copy/move operations (client)

Clients may now perform chained copy/move operations locally on a single object in a working copy:

   svn mv path1 path2
   svn mv path2 path3

See issue #756 for more.

Improved handling multiple copy/move sources (client)

Clients now accept multiple sources for copy and move operations, with the ability to copy/move each of the sources to the specified directory. This mirrors the behavior of standard command-line copy and move tools, such as cp and mv. For example:

   svn mkdir new_subdir
   svn mv foo.txt bar.txt baz.txt new_subdir

In practice, this means users can take advantage of shell globbing when doing a local copy or move:

   svn cp *.c dir

Multiple source copy/move also works for all previously defined copy/move working copy and repository combinations.

See issue #747 for more.

Copy takes -rBASE (client)

Copy now understands the special revision "BASE" in a working copy (as in: "-rBASE").

See issue #1643 for more.

Creation of intermediate directories with copy/move (client and server)

See the section on the new --parents option for more about this.

New "resolve" subcommand replaces "resolved"

A new resolve subcommand replaces the "resolved" subcommand (the latter is deprecated, but still present for compatibility). The new subcommand takes a --accept=orig|mine|repo option to select which version of a file to retain (which means Subversion now supports batch-style conflict resolution).

See issue #2784 for more.

Create intermediate directories if asked

Add, mkdir, copy, and move take a new --parents option, which makes intermediate directories as necessary to create the destination path.

See issue #1776 for more

New --keep-local option retains path after delete.

Delete (remove) now takes a --keep-local option to retain its targets locally, so paths will not be removed even if unmodified.

Commit now takes a --with-revprop option.

See issue #1976 for more.