Apache Subversion 1.15 Release Notes

This is work in progress. Subversion 1.15 has not been released yet.

What's New in Apache Subversion 1.15

Apache Subversion 1.15 is a superset of all previous Subversion releases, and is as of the time of its release considered the current "best" release. Any feature or bugfix in 1.0.x through 1.14.x is also in 1.15, but 1.15 contains features and bugfixes not present in any earlier release.

This page describes only major changes. For a complete list of changes, see the 1.15 section of the CHANGES file.

Compatibility Considerations

Client/Server Compatibility

Subversion 1.15 clients and servers interoperate transparently with older servers and clients. However, some of the new 1.15 features may not be available unless both client and server are the latest version. There are also cases where a new feature will work but will run less efficiently if the client is new and the server old.

Repository Compatibility

Subversion 1.15 servers can read and write to repositories created by earlier versions.

There is no need to dump and reload your repositories.

Working Copy Compatibility

Subversion 1.15 can upgrade 1.0 through 1.7 working copies in place. See Upgrading the Working Copy below.

Subversion 1.15 is fully compatible with 1.8 through 1.14 working copies (without upgrading) and can be used interchangeably with Subversion 1.8 through 1.14 clients on these working copies.

Additionally, Subversion 1.15 introduces a new working copy format to support the Pristines On Demand feature added in this release. Working copies in this newer format require a Subversion 1.15 or newer client and cannot be used with Subversion 1.14 or older clients.

To maximize compatibility, by default both svn checkout and svn upgrade produce working copies which can be used interchangeably with Subversion 1.8 through 1.14 clients, except when the user requests Pristines On Demand or requests the newer working copy format.

API/ABI compatibility

Subversion 1.15 maintains API/ABI compatibility with earlier releases, by only adding new functions, never removing old ones. A program written to any previous 1.x API can both compile and run using 1.15 libraries. However, a program written for 1.15 cannot necessarily compile or run against older libraries.

There may be limited cases where the behavior of old APIs has been slightly modified from previous releases. These are instances where edge cases of the functionality have been deemed buggy, and therefore improved or removed. Please consult the API errata for more detailed information on what these APIs are and what impact these changes may have.

New Feature Compatibility Table

New Feature Minimum Client1 Minimum Server Minimum Repository Notes
Pristines On Demand 1.15 TODO TODO
Streamy Checkouts 1.15 TODO TODO

Upgrading the Working Copy

Subversion 1.15 is fully compatible with 1.8 through 1.14 working copies. These do not need to be upgraded.

Subversion 1.15 can upgrade most 1.0 through 1.7 working copies in place but cannot otherwise operate on them until upgraded.

In some cases, it may be more convenient to check out a new working copy, rather than to upgrade an older one.

To upgrade a working copy, run the svn upgrade command in it. This command may take some time to complete.

Caveats:

1.6 and older working copies: In the event that a 1.6 or older working copy requires svn cleanup, the cleanup must be performed by a 1.6 or older Subversion client. Subversion 1.15 cannot upgrade these in place until the cleanup is run with the older client.

Corrupt working copies: Subversion 1.15 cannot upgrade corrupt working copies. Unfixable problems can arise from missing or corrupt meta-data inside .svn directories. Such damage to the working copy is permanent, and cannot be fixed even if svn cleanup is run prior to the upgrade.

If your working copy does not upgrade cleanly, please check out a new one.

New Features

Pristines On Demand

At the user's option, the storage space requirement of a Subversion working copy can be reduced by up to 50%.

The space savings are achieved by reducing or eliminating cached content in the working copy administrative directory (.svn) at the potential cost of additional communication with the repository server.

Background

All Subversion working copies require extra storage space for the working copy administrative directory (.svn). By default, the storage space required for this administrative directory is slightly more than the total size of the checked out files. Subversion uses most of that extra space to cache a copy of each file's BASE revision ("pristine") so that operations such as diff and revert can work offline, and commit can send just the modified portions of a file to the repository server rather than the whole file.

This design optimises the speed and availability of these operations on the assumption that network connectivity to the repository may be a bottleneck (or unavailable at times) while local storage is assumed to be inexpensive.

However, in some use cases, it may be more sensible to fetch pristines from the repository server only when needed ("on demand"), rather than to cache all pristines all the time. Some example use cases:

  • Very large files that change infrequently. In this case, the pristine is usually not needed but takes up space, doubling the storage requirement while providing little or no benefit.
  • Working copies on storage-constrained devices with a fast, always-on connection to the repository server. In this case, network bandwidth is more readily available than local storage, inverting the original design assumption that local storage is inexpensive.
  • Working copies on the same device as the repository.

When using Pristines On Demand, instead of caching pristines for all files all the time, Subversion will only fetch and cache those of individual files when needed, and will eliminate them when no longer needed.

Tradeoffs

The space savings come with some tradeoffs:

A Subversion 1.15 or newer client is required to operate on the working copy. The working copy cannot be used interchangeably with Subversion 1.8 through 1.14 clients, as these will report an error.

A connection to the repository server is required for more operations as compared to a fully-cached working copy. Depending on network speeds and file sizes, the additional network communications may introduce a perceptible delay when a pristine is downloaded.

Checking Out a Pristines On Demand Working Copy

As of Subversion 1.15, users can opt for Pristines On Demand at checkout time by giving the --store-pristine=no option. This applies to the entire working copy:

$ svn checkout --store-pristine=no $REPO $WC

Otherwise, the default is to check out a normal, fully cached working copy:

$ svn checkout $REPO $WC

Users may also write --store-pristine=yes to explicitly request a a normal, fully cached working copy. This may be useful in scripting scenarios:

$ svn checkout --store-pristine=yes $REPO $WC

Examining the Working Copy Pristines Type

Users can check whether a working copy uses Pristines On Demand with the svn info command. This command shows several fields which are new in Subversion 1.15, shown in bold here:

$ svn info
Path: .
Working Copy Root Path: /ramdrive/svn-trunk
Working Copy Compatible With Version: 1.15
Working Copy Format: 32
Working Copy Store Pristine: no
URL: https://svn.apache.org/repos/asf/subversion/trunk
Relative URL: ^/subversion/trunk
Repository Root: https://svn.apache.org/repos/asf
Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
Revision: 1924024
Node Kind: directory
Schedule: normal
Last Changed Author: dsahlberg
Last Changed Rev: 1923965
Last Changed Date: 2025-02-21 11:08:37 -0500 (Fri, 21 Feb 2025)

The relevant one is Working Copy Store Pristine. This shows no when using Pristines On Demand (coinciding with the --store-pristine=no command line switch), yes when using a normal, fully cached working copy (coinciding with --store-pristine=yes).

Repository Access Comparison

The following table lists the Subversion commands that behave differently when using Pristines On Demand. For each command, it shows the difference in how that command accesses the repository.

Working Copy Type
Command Normal Pristines On Demand
cat (BASE) Never Hydrate
commit Send-Delta Send-Full
conflict resolving (resolve/merge/up/sw) Sometimes Sometimes (...)
diff (BASE) Never Hydrate
revert Never Hydrate
update/switch Always Always + Hydrate

Legend:

  • Never: Does not contact the repository server.
  • Always: Always contacts the repository server.
  • Hydrate: This operation downloads and keeps the pristine for each file that has a local content modification (i.e., when svn status shows M in the 1st column) when its pristine is not already stored in the working copy. See notes 1 and 2 below.
  • Send-Delta: Sends just the locally modified parts of each file's content.
  • Send-Full: Sends the complete content of each locally modified file.

Additional Details

Once downloaded, Subversion keeps a file's pristine locally cached in the working copy administrative directory so that further operations on the file will not download it from the repository again. Subversion keeps the pristine until an operation either restores the file to an unmodified state or detects that the file is no longer modified. For example, commit and revert will immediately discard the pristine of each file they operated on, because that file will no longer be locally modified, whereas diff will discard the pristine only if it finds there are no differences.

Note 1: At the beginning of a given operation, Subversion will download missing pristines of at least the files that this particular operation will use. It may download those of other files too, that this particular operation will not use. For example, in the initial implementation of this feature, Subversion considers all potential files in the smallest subtree that spans all the target files of the operation. The details of this behaviour are subject to change before and after the feature is released.

Note 2: In evaluating differences between a file's working text and its BASE text, Subversion takes into account the "EOL style" and "keywords" settings. (See the svn:eol-style and svn:keywords properties.) Just as svn status does not show M in the first column for such differences, neither will these cause the pristine to be downloaded from the repository.

Limitations and Future Possibilities

Currently, this feature applies to an entire working copy. That is, either all working files have their pristines cached (the default) or all working files use pristines on demand (--store-pristine=no). In the future, this feature may be enhanced to give users more granular control, such as by allowing the --store-pristine switch to apply to individual files.

TODO: Point to the "User Guide" in notes/i525/. Regenerate /docs/i525-user-guide.html from the source markdown.

Multi-WC: Multiple Working Copy Format Support

Subversion 1.15 introduces a new working copy format to support Pristines On Demand, internally called Format 32.

In past releases, a new working copy format meant that users needed to upgrade any existing working copies by running svn upgrade in them. Once upgraded, older Subversion clients could no longer be used with these working copies.

For user convenience, Subversion 1.15 introduces support for multiple working copy format versions (Multi-WC). This provides two benefits:

  • Users do not need to upgrade their 1.8 through 1.14 working copies before using Subversion 1.15 with them, unless they want to use Pristines On Demand.
  • Users can use a mix of Subversion 1.8 through 1.15 clients interchangeably with working copies in 1.8 through 1.14 format. This use case can arise when users install multiple versions of Subversion clients, or use 3rd party software that incorporates older Subversion releases.

Supported Working Copy Formats

Subversion 1.15 supports working copies in two format versions:

Working Copy Format Introduced Supported By Available Pristine Types
Format 31 Subversion 1.8 1.8 through 1.15 Fully-Cached
Format 32 Subversion 1.15 1.15 Fully-Cached, Pristines On Demand

Subversion 1.15 uses Format 31 by default, unless the user selects Format 32 explicitly or opts in to Pristines On Demand.

Future releases may introduce newer working copy formats while keeping support for existing formats.

New Command Line Options

Two new command line options allow users to control the working copy format:

--store-pristine=ARG can be used with svn checkout:

  • --store-pristine=no: requests a working copy with Pristines On Demand. This option implies working copy Format 32, supported by 1.15 and newer clients.
  • --store-pristine=yes (default): requests a working copy with traditional fully-cached Pristines. By default, the working copy will use Format 31, supported by 1.8 and newer clients, unless overridden by --compatible-version=1.15; see below.

--compatible-version=ARG, where ARG is a version of Subversion, can be used with svn checkout and svn upgrade:

This requests the newest working copy format that is compatible with the specified Subversion client version.

When choosing ARG, specify the version of the oldest Subversion client that will be used with the working copy.

ARG may be in MAJOR.MINOR format, such as 1.9. ARG may also specify a patch version, such as 1.9.5 but the third component is ignored because Subversion does not introduce new working copy metadata formats in patch releases.

  • --compatible-version=1.8 through --compatible-version=1.14 (default): requests a working copy in Format 31, supported by Subversion 1.8 and newer clients. Supports traditional fully-cached Pristines only.
  • --compatible-version=1.15: requests a working copy in Format 32, supported by Subversion 1.15 and newer clients. Although this format supports Pristines On Demand, it will use traditional fully-cached Pristines by default, unless overridden by --store-pristine=no; see above.

The following table shows which format and pristine type is achieved by each combination of the --store-pristine and --compatible-version switches (including when omitting one or both of these):

--store-pristine --compatible-version Working Copy Format Pristines
Omitted Omitted 31 Fully cached
Omitted 1.8 thru 1.14 31 Fully cached
Omitted 1.15 32 Fully cached
yes Omitted 31 Fully cached
yes 1.8 thru 1.14 31 Fully cached
yes 1.15 32 Fully cached
no Omitted 32 Pristines On Demand
no 1.8 thru 1.14 Not a valid combination
no 1.15 32 Pristines On Demand

New svn info Output

Users can determine the working copy format and pristine storage type with the svn info command (new fields shown in bold):

$ svn info
Path: .
Working Copy Root Path: /ramdrive/svn-trunk
Working Copy Compatible With Version: 1.15
Working Copy Format: 32
Working Copy Store Pristine: no
URL: https://svn.apache.org/repos/asf/subversion/trunk
Relative URL: ^/subversion/trunk
Repository Root: https://svn.apache.org/repos/asf
Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
Revision: 1924024
Node Kind: directory
Schedule: normal
Last Changed Author: dsahlberg
Last Changed Rev: 1923965
Last Changed Date: 2025-02-21 11:08:37 -0500 (Fri, 21 Feb 2025)

Explanation of the new fields:

  • Working Copy Compatible With Version shows the oldest Subversion client that can be used with this working copy. In this release, this field may show 1.8 or 1.15.
  • Working Copy Format shows the working copy format version. In this release this field may show 31 or 32.
  • Working Copy Store Pristine shows no when using Pristines On Demand, yes when using traditional fully-cached pristines.

Older Subversion Clients

When using the newer Format 32, a Subversion 1.15 or newer client is required. Attempting to operate on such a working copy with an older client will result in an error, such as:

svn: E155021: This client is too old to work with the working copy at
'/path/to/working/copy' (format 32).
You need to get a newer Subversion client. For more details, see
  http://subversion.apache.org/faq.html#working-copy-format-change

Additional Notes

The metadata format is a property of a particular working copy. Users may have multiple working copies on their machine, with some in Format 31 and others in Format 32.

Streamy Checkouts

This new feature delivers a noticeable speed-up for svn checkout and svn update while addressing reports of network connection timeouts that could occur in the middle of these operations.

Previous versions of the Subversion client would fetch files from the server into the working copy's administrative directory, where each file's BASE revision is cached, and then separately "install" them to their proper location in the working copy. The "install" step involves copying and possibly translating the files to account for things like svn:eol-style and svn:keywords. This step was done per-directory and during that time, the client would hold the connection to the server open without reading anything through it. If this communication silence went on for too long, the server would eventually timeout and close the connection from its end, leading to annoying errors on the client side.

For example, assuming a 60 second HTTP timeout (the default in httpd 2.4.x) and reasonably fast storage on the client side, timeouts could be expected to occur while installing any directory about 6 GB in size or larger. (This value could vary significantly based on numerous interrelated factors.)

This issue is addressed by making the checkout stream data to both the administrative directory and the projected working file simultaneously, reducing the actual "install" to an atomic rename. As a result, the svn checkout and svn update operations no longer hold the connection open without reading from it, eliminating the timeouts.

Clients will enjoy a noticeable speed-up due to improved network performance and reduced storage-level I/O.

Note: Streamy Checkouts are not yet implemented for svn export.

Enhancements and Bugfixes

Command-line client improvements (client)

Server-side improvements

Client- and server-side improvements

Plaintext credential cache is supported by default on Unix-like systems

Subversion supports several credential caches to prevent re-typing usernames and passwords repeatedly. Which credential cache(s) are used depends on the operating system, compile-time options, and the user's runtime configuration. On Windows and macOS, Subversion uses OS facilities to save passwords in encrypted form. Unix-like operating systems do not have a single standard facility to do this; on these systems, Subversion supports up to four credential caches: GNOME Keyring, KWallet, GPG Agent, and (as a fallback) the Plaintext cache.

The rest of this section discusses the Plaintext cache and is applicable only to Subversion clients running on Unix-like operating systems.

In Subversion 1.12 through 1.14, write access to the Plaintext cache was disabled by default at compile-time. Binaries compiled in the default configuration could not store new plaintext credentials, but would continue to use any that were already stored. Users and binary packagers could explicitly enable write access to the Plaintext cache by compiling Subversion with the --enable-plaintext-password-storage option to configure. (See r1845377.)

Unfortunately, this has caused a variety of problems for users, especially when using the svn client in unattended processes such as CI systems, or on remote machines through ssh (a GUI password prompt would display on the remote machine, inaccessible to the ssh user). Users reported that they had to employ workarounds that caused passwords to be stored in plaintext anyway, or refused to upgrade their Subversion installations to these releases. Some binary packagers built with --enable-plaintext-password-storage while others didn't, creating inconsistent experiences within the same release lines.

Based on the feedback received, Subversion 1.15 inverts the default. (See r1909351.) Binaries compiled in the default configuration can once again store new plaintext credentials (after warning and asking the user). Sites that wish to eliminate this possibility can do one or both of the following:

  • Compile Subversion with the --disable-plaintext-password-storage option to configure or install a binary package that was compiled this way. Be aware that users can circumvent this by compiling or installing their own Subversion binaries and/or by creating a plaintext cache manually.
  • Allow encrypted stores like GNOME Keyring and KWallet, but not the Plaintext cache, by setting store-plaintext-passwords = no in Subversion's run-time config settings. See the per user files at ~/.subversion/config and ~/.subversion/servers, and the systemwide files at /etc/subversion/config and /etc/subversion/servers.

For more on plaintext credentials, see the FAQ entry.

Known issues in the release

There are no known issues specific to this release at the moment.

Subversion 1.15.x is a Regular Release

1.15 is a regular release, not a Long-Term Support release. See Supported Versions and How We Plan Releases.