Advanced Topics

paths, filenames, and log messages in Unicode, encoded as UTF-8. In that sense, the repository is internationalized— that is, the repository is ready to accept input in any human language. This means, however, that the Subversion client is responsible for sending only UTF-8 filenames and log messages into the repository. In order to do this, it must convert the data from the native locale into UTF-8.

For example, suppose you create a file namedcaffè.txt, and then when committing the file, you write the log message as “Adesso il caffè è più forte”. Both the filename and log message contain non-ASCII characters, but because your locale is set to it_IT, the Subversion client knows to interpret them as Italian. It uses an Italian character set to convert the data to UTF-8 before sending them off to the repository.

Note that while the repository demands UTF-8 filenames and log messages, it does not pay attention to file contents. Subversion treats file contents as opaque strings of bytes, and neither client nor server makes an attempt to understand the character set or encoding of the contents.

Character set conversion errors

While using Subversion, you might get hit with an error related to character set conversions:

svn: Can't recode string.

The message is cryptic, but generally occurs when the Subversion client has received a UTF-8 string from the repository, but the characters can't be converted to the current locale. For example, if your locale is en_US but a collaborator has committed a Japanese filename, you're likely to see this error when you receive the file during an svn update.

The solution is either to set your locale to something which can represent the incoming UTF-8 data, or to change the filename or log message in the repository. (And don't forget to slap your collaborator's hand—projects should decide on common languages ahead of time, so that all participants are using the same locale.)

Subversion Repository URLs

As illustrated throughout this book, Subversion uses URLs to identify versioned resources in Subversion repositories. For the most part, these URLs use the standard syntax, allowing for server names and port numbers to be specified as part of the URL:

$ svn checkout http://svn.example.com:9834/repos

…

But there are some nuances in Subversion's handling of URLs that are notable. For example, URLs containing the file: access method (used for local repositories) must, in accordance with convention, have either a server name of localhost or no server name at all:

$ svn checkout file:///path/to/repos

…

$ svn checkout file://localhost/path/to/repos

…

Also, users of the file: scheme on Windows platforms will need to use an unofficially “standard” syntax for accessing repositories that are on the same machine, but on a different drive than the client's current working drive. Either of the two following URL path syntaxes will work where X is the drive on which the repository resides:

141

Advanced Topics

C:\> svn checkout file:///X:/path/to/repos

…

C:\> svn checkout "file:///X|/path/to/repos"

…

In the second syntax, you need to quote the URL so that the vertical bar character is not interpreted as a pipe. Also, note that a URL uses ordinary slashes even though the native (non-URL) form of a path on Windows uses backslashes.

Finally, it should be noted that the Subversion client will automatically encode URLs as necessary, just like a web browser does. For example, if a URL contains a space or upper-ASCII character:

$ svn checkout "http://host/path with space/project/españa"

…then Subversion will escape the unsafe characters and behave as if you had typed:

$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a

If the URL contains spaces, be sure to place it within quote marks, so that your shell treats the whole thing as a single argument to the svn program.

142