This section is from the "Version Control with Subversion" book, by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. Also available from Amazon: Version Control with Subversion.
Managing vendor branches generally works like this: first,
you create a top-level directory (such as
/vendor
) to hold the vendor branches.
Then you import the third-party code into a subdirectory of
that top-level directory. You then copy that subdirectory
into your main development branch (for example,
/trunk
) at the appropriate location. You
always make your local changes in the main development branch.
With each new release of the code you are tracking, you bring
it into the vendor branch and merge the changes into
/trunk
, resolving whatever conflicts
occur between your local changes and the upstream
changes.
An example will help to clarify this algorithm. We'll use
a scenario where your development team is creating a
calculator program that links against a third-party complex
number arithmetic library, libcomplex. We'll begin with the
initial creation of the vendor branch and the import of the
first vendor drop. We'll call our vendor branch directory
libcomplex
, and our code drops will go
into a subdirectory of our vendor branch called
current
. And since svn
import creates all the intermediate parent
directories it needs, we can actually accomplish both of these
steps with a single command:
$ svn import /path/to/libcomplex-1.0 \ http://svn.example.com/repos/vendor/libcomplex/current \ -m 'importing initial 1.0 vendor drop' …
We now have the current version of the libcomplex source
code in /vendor/libcomplex/current
. Now,
we tag that version (see the section called “Tags”)
and then copy it into the main development branch. Our copy
will create a new directory called
libcomplex
in our existing
calc
project directory. It is in this
copied version of the vendor data that we will make our
customizations:
$ svn copy http://svn.example.com/repos/vendor/libcomplex/current \ http://svn.example.com/repos/vendor/libcomplex/1.0 \ -m 'tagging libcomplex-1.0' … $ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0 \ http://svn.example.com/repos/calc/libcomplex \ -m 'bringing libcomplex-1.0 into the main branch' …
We check out our project's main branch—which now includes a copy of the first vendor drop—and we get to work customizing the libcomplex code. Before we know it, our modified version of libcomplex is now completely integrated into our calculator program. [24]
A few weeks later, the developers of libcomplex release a new version of their library—version 1.1—which contains some features and functionality that we really want. We'd like to upgrade to this new version, but without losing the customizations we made to the existing version. What we essentially would like to do is to replace our current baseline version of libcomplex 1.0 with a copy of libcomplex 1.1, and then re-apply the custom modifications we previously made to that library to the new version. But we actually approach the problem from the other direction, applying the changes made to libcomplex between versions 1.0 and 1.1 to our modified copy of it.
To perform this upgrade, we check out a copy of our vendor
branch and replace the code in the
current
directory with the new libcomplex
1.1 source code. We quite literally copy new files on top of
existing files, perhaps exploding the libcomplex 1.1 release
tarball atop our existing files and directories. The goal
here is to make our current
directory
contain only the libcomplex 1.1 code and to ensure that all
that code is under version control. Oh, and we want to do
this with as little version control history disturbance as
possible.
After replacing the 1.0 code with 1.1 code, svn
status will show files with local modifications as
well as, perhaps, some unversioned files. If we did what we
were supposed to do, the unversioned files are only those new
files introduced in the 1.1 release of libcomplex—we
run svn add on those to get them under
version control. If the 1.1 code no longer has certain files
that were in the 1.0 tree, it may be hard to notice them;
you'd have to compare the two trees with some external tool
and then svn delete any files present in
1.0 but not in 1.1. (Although it might also be just fine to
let these same files live on in unused obscurity!) Finally,
once our current
working copy contains
only the libcomplex 1.1 code, we commit the changes we made to
get it looking that way.
Our current
branch now contains the
new vendor drop. We tag the new version as 1.1 (in the same
way we previously tagged the version 1.0 vendor drop), and
then merge the differences between the tag of the previous
version and the new current version into our main development
branch:
$ cd working-copies/calc $ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0 \ http://svn.example.com/repos/vendor/libcomplex/current \ libcomplex … # resolve all the conflicts between their changes and our changes $ svn commit -m 'merging libcomplex-1.1 into the main branch' …
In the trivial use case, the new version of our third-party tool would look, from a files-and-directories point of view, just like the previous version. None of the libcomplex source files would have been deleted, renamed, or moved to different locations—the new version would contain only textual modifications against the previous one. In a perfect world, our modifications would apply cleanly to the new version of the library, with absolutely no complications or conflicts.
But things aren't always that simple, and in fact it is quite common for source files to get moved around between releases of software. This complicates the process of ensuring that our modifications are still valid for the new version of code, and things can quickly degrade into a situation where we have to manually recreate our customizations in the new version. Once Subversion knows about the history of a given source file—including all its previous locations—the process of merging in the new version of the library is pretty simple. But we are responsible for telling Subversion how the source file layout changed from vendor drop to vendor drop.