So How Do I Use This Stuff?

All right, enough background, on to the actual Subversion client
API.

Subversion is broken into several libraries. From the client
developer's point of view, the most important is
libsvn_client, which holds the functions used to
implement the various commands you've seen in the command line client.
This library is a wrapper around the underlying libraries which manage
access to the working copy (your checked out copy of the contents of
the repository) and to the repository (via a number of possible
paths).

Some Common Characteristics

All the functions in this library share some common
characteristics. First, they all assume textual data (paths, URLs,
raw text like a log entry or a username, etc.) is UTF-8 encoded and
uses newlines for line endings. This provides consistency between
clients and avoids the need for cumbersome and unnecessary locale and
line ending data tagging. To convert your data into UTF-8, use the
functions in svn_utf.h. For the purposes of this article,
we will assume all input is in ASCII and will avoid conversion to
UTF-8.

Second, each function takes an apr_pool_t pointer to
use for memory allocation.

Third, each function takes a pointer to a structure called
svn_client_ctx_t. This "client context" serves as a
container for several different things that are used across many
libsvn_client functions. For example, all the Subversion
functions that commit a change to the repository require the client to
provide them with a log message. To do this, they use a callback
function and baton that are stored in the client context. Similarly,
many of the functions need to provide progress notification to the
calling application and, eventually, to the user. The library
functions call a notification callback-baton pair that are passed in
via the context. The client context also caches configuration
options, so the libraries don't need to read them in whenever they
require them.

To use the rest of libsvn_client, you will have to
fill in a bare minimum of the context. Here's an example of how to do
it:

The comments in svn_client.h provide more details on
the contents of svn_client_ctx_t.

Compiling and Linking

All you need now to start using the Subversion libraries are a few
details on how to compile and link against them. For all the examples
in this article, you will have to link against
libsvn_client-1, libsvn_auth-1, and
libsvn_subr-1. The header files are located in
$(PREFIX)/include/subversion-1, where
$(PREFIX) is either the path you specified for
--prefix when configuring Subversion or
/usr/local by default. You should also include the
output of svn-config --includes --cflags --libs in your
compile and link lines.

Eventually, you should be able to forget about manually including
Subversion's include and libs, allowing svn-config to
take care of the details. But for now you will have to do it yourself.
Here's the Makefile I used when preparing this article,
which should get you far enough along to get things working.

A Practical Example

Now you're ready to write an actual application that uses
libsvn_client. Let's say your company makes a web
application. You store everything in a Subversion repository and can
simply check out some parts of your source onto the web server and
things just work. Suppose also that several of your web developers
are unskilled in using version control tools. To simplify life for
them, you're writing an application to let them deploy a site from the
tree to the server, query what versions of each file they have there,
and update to new versions from the repository.

You will need to use at least three functions from
libsvn_client. svn_client_checkout deploys
the site for the first time to a new
server. svn_client_status checks the versions deployed on
a given server. svn_client_update deploys new versions
of the site to an existing install on the server. We'll look at each
function in turn.

As you might guess, svn_client_checkout implements the
svn checkout command. It takes as arguments the URL to
check out from the repository, a path that will become the root of the
new working copy it creates, and a number that indicates which
revision of the URL you want to check out. There's also a boolean
flag that indicates if the checkout should recurse into subdirectories
inside the URL. Besides these specific arguments, the normal
libsvn_client function arguments apply; a client context
and a pool. If you want to provide feedback to your user as the
checkout takes place, you can provide a notification callback and
baton inside the context to be called each time something happens.
Here's an example of how your application could use it:

Now that your application can deploy a new website, it needs to be
able to query the deployed version to find out which versions of each
file are there. This needs svn_client_status, the
routine that implements the core of the svn status
command. svn_client_status is a bit more complicated
than svn_client_checkout, as there are more variations.

If the "descend" argument is TRUE, it recurses down a
path in a working copy, filling in an apr_hash_t with
keys that contain each entry's path and values that are
svn_wc_status_ts. Otherwise, it just reads the entries
in the top level of the directory structure.

To check the status of the entry in the working copy against that
of the repository, you can pass TRUE as the "update" flag. The
svn_wc_status_ts in the hash will have their
repos_text_status and repos_prop_status
members filled in appropriately. This will also fill in the
youngest argument with the number of the most current
revision in the repository.

Use the "get_all" argument to switch between fetching all entries
in the working copy in the hash or only the "interesting" entries
(either locally modified or out of date compared to the repository).
If you don't want the svn:ignore property to control
which entries are seen, pass TRUE for the 'no_ignore'
argument. As with svn_client_checkout, any notification
callback will be called, along with the context's notification baton,
for each entry placed in the hash. The following example uses
svn_client_status to print the revision numbers of
everything in the deployed site.

The final feature for your application is the ability to update a
deployed site to a newer version, using svn update. As
you might suspect, the libsvn_client function for this is
svn_client_update. Fortunately, this is much simpler
than svn_client_status. Pass it the path to the deployed
site, an svn_opt_revision_t identifying the version to
which to update, and a flag to allow or disallow recursion into
subdirectories. As usual, it takes pool and context arguments, and
any notification callback in the context will be called for each
updated entry. Let's see how this can be used to update our deployed
website to the latest revision in the repository.

Conclusion

There you have it, a simple set of functions that take the existing
functionality of libsvn_client and apply it to your
specific problem. Due to the design of Subversion, you can do this
much more flexibly than by wrapping up an existing command line
client. My next article will look at how to extend this to provide
the ability to edit the deployed files and to commit the changes back
into the repository, using the rest of libsvn_client.

Garrett Rooney
is a software developer at FactSet Research Systems, where he works on real-time market data.