Version Control with SVK

All version control systems have to solve the same fundamental problem: how will the system allow users to share information, but prevent them from accidentally stepping on each other's feet? It's all too easy for users to accidentally overwrite each other's changes in the depot.

Consider the scenario shown in Figure 2.1, “The problem to avoid”. Suppose we have two co-workers, Harry and Sally. They each decide to edit the same repository file at the same time. If Harry saves his changes to the repository first, then it's possible that (a few moments later) Sally could accidentally overwrite them with her own new version of the file. While Harry's version of the file won't be lost forever (because the system remembers every change), any changes Harry made won't be present in Sally's newer version of the file, because she never saw Harry's changes to begin with. Harry's work is still effectively lost—or at least missing from the latest version of the file—and probably by accident. This is definitely a situation we want to avoid!

Figure 2.1. The problem to avoid

Many version control systems use a lock-modify-unlock model to address this problem. In such a system, the repository allows only one person to change a file at a time. First Harry must “lock” the file before he can begin making changes to it. Locking a file is a lot like borrowing a book from the library; if Harry has locked a file, then Sally cannot make any changes to it. If she tries to lock the file, the repository will deny the request. All she can do is read the file, and wait for Harry to finish his changes and release his lock. After Harry unlocks the file, his turn is over, and now Sally can take her turn by locking and editing. Figure 2.2, “The lock-modify-unlock solution” demonstrates this simple solution.

Figure 2.2. The lock-modify-unlock solution

The problem with the lock-modify-unlock model is that it's a bit restrictive, and often becomes a roadblock for users:

SVK, Subversion, CVS, and other version control systems use a copy-modify-merge model as an alternative to locking. In this model, each user's client contacts the project repository and creates a personal working copy—a local reflection of the repository's files and directories. Users then work in parallel, modifying their private copies. Finally, the private copies are merged together into a new, final version. The version control system often assists with the merging, but ultimately a human being is responsible for making it happen correctly.

Here's an example. Say that Harry and Sally each create working copies of the same project, copied from the repository. They work concurrently, and make changes to the same file A within their copies. Sally saves her changes to the repository first. When Harry attempts to save his changes later, the repository informs him that his file A is out-of-date. In other words, that file A in the repository has somehow changed since he last copied it. So Harry asks his client to merge any new changes from the repository into his working copy of file A. Chances are that Sally's changes don't overlap with his own; so once he has both sets of changes integrated, he saves his working copy back to the repository. Figure 2.3, “The copy-modify-merge solution” and Figure 2.4, “The copy-modify-merge solution (continued)” show this process.

Figure 2.3. The copy-modify-merge solution

Figure 2.4. The copy-modify-merge solution (continued)

But what if Sally's changes do overlap with Harry's changes? What then? This situation is called a conflict, and it's usually not much of a problem. When Harry asks his client to merge the latest repository changes into his working copy, his copy of file A is somehow flagged as being in a state of conflict: he'll be able to see both sets of conflicting changes, and manually choose between them. Note that software can't automatically resolve conflicts; only humans are capable of understanding and making the necessary intelligent choices. Once Harry has manually resolved the overlapping changes—perhaps after a discussion with Sally—he can safely save the merged file back to the repository.

The copy-modify-merge model may sound a bit chaotic, but in practice, it runs extremely smoothly. Users can work in parallel, never waiting for one another. When they work on the same files, it turns out that most of their concurrent changes don't overlap at all; conflicts are infrequent. And the amount of time it takes to resolve conflicts is far less than the time lost by a locking system.

In the end, it all comes down to one critical factor: user communication. When users communicate poorly, both syntactic and semantic conflicts increase. No system can force users to communicate perfectly, and no system can detect semantic conflicts. So there's no point in being lulled into a false promise that a locking system will somehow prevent conflicts; in practice, locking seems to inhibit productivity more than anything else.

You've already read about working copies; now we'll demonstrate how the SVK client creates and uses them.

A SVK working copy is an ordinary directory tree on your local system, containing a collection of files. You can edit these files however you wish, and if they're source code files, you can compile your program from them in the usual way. Your working copy is your own private work area: SVK will never incorporate changes from the depot, nor publish your own changes to the depot, until you explicitly tell it to do so.

After you've made some changes to the files in your working copy and verified that they work properly, SVK provides you with commands to “publish” your changes to the depot. If the depot contained changes not yet in your working copy^[3], SVK provides you with commands to merge those changes into your working directory (by reading from the depot).

A SVK working copy doesn't contain any extra files, unlike Subversion and CVS working copies. Instead SVK keeps track of the state of your working copy in a subdirectory of your home directory named .svk.

A typical SVK depot often holds the files (or source code) for several projects; usually, each project is a subdirectory in the depot's filesystem tree. In this arrangement, a user's working copy will usually correspond to a particular subtree of the depot.

For example, suppose you have two software projects, paint and calc, for which you wish to start keeping a history.

To add these 2 projects to your depot you would run the following commands:

$ svk import  --message "Initial import of calc." calc //calc
Repository /Users/sally/.svk/local does not exist, create? (y/n)y
Committed revision 1.
Import path //calc initialized.
Committed revision 2.
Directory /Users/sally/calc imported to depotpath //calc as revision 2.

Then repeat the same steps for the paint project. Now you have 2 projects in the depot. Each project lives in its own top-level subdirectory, as shown in Figure 2.5, “The depot's filesystem”.

Figure 2.5. The depot's filesystem

Since the calc and paint projects have been imported into the depot, it's safe to remove the directories we imported from, so lets run:

$ rm -rf calc
$ rm -rf paint

Now in order to get a working copy, you must check out some subtree of the depot^[4]. (The term “check out” may sound like it has something to do with locking or reserving resources, but it doesn't; it simply creates a private copy of the project for you.) For example, if you check out /calc, you will get a working copy like this:

$ svk checkout //calc
Syncing //calc(/calc) in /Users/sally/calc to 2.
A   calc/button.c
A   calc/Makefile
A   calc/integer.c
$ ls -A calc
Makefile        button.c        integer.c

The list of letter A's indicates that SVK is adding a number of items to your working copy. You now have a editable copy of the depot's /calc directory.

Suppose you make changes to button.c. Since SVK knows the revision that the file in your working copy was based on, SVK can tell that you've changed the file. However, SVK does not make your changes public until you explicitly tell it to. The act of publishing your changes is more commonly known as committing (or checking in) changes to the depot.

To publish your changes to others, you can use SVK's commit command:

$ svk commit button.c
Committed revision 57.

Now your changes to button.c have been committed to the depot; if another user checks out a working copy of /calc, they will see your changes in the latest version of the file.

Suppose you have a collaborator, Sally, who checked out a working copy of /calc at the same time you did. When you commit your change to button.c, Sally's working copy is left unchanged; SVK only modifies working copies at the user's request.

To bring her project up to date, Sally can ask SVK to update her working copy, by using the SVK update command. This will incorporate your changes into her working copy, as well as any others that have been committed since she checked it out.

$ pwd
/Users/sally/calc
$ ls -A 
Makefile integer.c button.c
$ svk update
U   button.c

The output from the svk update command indicates that SVK updated the contents of button.c. Note that Sally didn't need to specify which files to update; SVK uses the information about the working copy stored inside ~/.svk/config, and further information from the depot, to decide which files need to be brought up to date.

A svk commit operation can publish changes to any number of files and directories as a single atomic transaction. In your working copy, you can change files' contents, create, delete, rename and copy files and directories, and then commit the complete set of changes as a unit.

In the depot, each commit is treated as an atomic transaction: either all the commit's changes take place, or none of them take place. SVK tries to retain this atomicity in the face of program crashes, system crashes, network problems, and other users' actions.

Each time the depot accepts a commit, this creates a new state of the filesystem tree, called a revision. Each revision is assigned a unique natural number, one greater than the number of the previous revision. The initial revision of a freshly created depot is numbered zero, and consists of nothing but an empty root directory.

Figure 2.6, “The depot” illustrates a nice way to visualize the depot. Imagine an array of revision numbers, starting at 0, stretching from left to right. Each revision number has a filesystem tree hanging below it, and each tree is a “snapshot” of the way the depot looked after a commit.

Figure 2.6. The depot

It's important to note that working copies do not always correspond to any single revision in the depot; they may contain files from several different revisions. For example, suppose you check out a working copy from a depot whose most recent revision is 4:

calc/Makefile:4
     integer.c:4
     button.c:4

At the moment, this working directory corresponds exactly to revision 4 in the repository. However, suppose you make a change to button.c, and commit that change. Assuming no other commits have taken place, your commit will create revision 5 of the depot, and your working copy will now look like this:

calc/Makefile:4
     integer.c:4
     button.c:5

Suppose that, at this point, Sally commits a change to integer.c, creating revision 6. If you use svk update to bring your working copy up to date, then it will look like this:

calc/Makefile:6
     integer.c:6
     button.c:6

Sally's change to integer.c will appear in your working copy, and your change will still be present in button.c. In this example, the text of Makefile is identical in revisions 4, 5, and 6, but SVK will mark your working copy of Makefile with revision 6 to indicate that it is still current. So, after you do a clean update at the top of your working copy, it will generally correspond to exactly one revision in the repository.

For each working copy, SVK records three essential pieces of information in the hash: subsection of the checkout: section in the ~/.svk/config file:

Given this information, by consulting the depot, SVK can tell which of the following four states a working file is in:

This may sound like a lot to keep track of, but the svk status command will show you the state of any item in your working copy. For more information on that command, see the section called “svk status”.

As a general principle, Subversion tries to be as flexible as possible. One special kind of flexibility is the ability to have a working copy containing files and directories with a mix of different working revision numbers. Unfortunately, this flexibility tends to confuse a number of new users. If the earlier example showing mixed revisions perplexed you, here's a primer on both why the feature exists and how to make use of it.

When you create a new SVK depot, it begins its life at revision zero and each successive commit increases the revision number by one. After your commit completes, the SVK client informs you of the new revision number:

$ svk commit --message "Corrected number of cheese slices."
Committed revision 3.

If at any point in the future you want to refer to that revision (we'll see how and why we might want to do that later in this chapter), you can refer to it as “3”.

If, however, you were committing from a working copy that was a direct checkout of a mirrored depotpath, things would be a little more complicated. This is because the mirrored repository has its own idea of revision numbers which is distinct from the local depots idea of revision numbers.

$ svk commit --message "Corrected number of cheese slices."
Commit into mirrored path: merging back directly.
Merging back to mirror source http://svn.sally.org/calc.
Merge back committed as revision 45.
Syncing http://svn.sally.org/calc
Retrieving log information from 45 to 45
Committed revision 15 from revision 45.

What happened here is that SVK first committed the change you made to the original mirrored repository. After that it automatically performs a svk sync to download the change on the mirror to the local depot again. This ensures that you can never commit anything to a mirrored path that isn't also on the mirror itself.

Above we showed you how to use the --revision switch to refer to a specific revision number. By default the revision numbers you specify are the ones in your depot. Sometimes you want to refer to a particular revision of the mirrored repository instead. Luckily SVK keeps a mapping from local to remote revision numbers and allows you to specify both local depot revision numbers or revision numbers in the mirrored repository when performing operations. To do so you only need to add a @ right after the revision number. To get the log message for the revision we just committed above you would use:

$ svk log --revision 45@
----------------------------------------------------------------------
r15 (orig r45):  sally | 2005-07-23 14:49:11 -0700

Corrected number of cheese slices.
----------------------------------------------------------------------

Notice how the log output shows both the local depots r15, and mirrored repositories r45 revision numbers. This can be a useful aid in certain situations as well.

The SVK client understands a number of revision keywords. These keywords can be used instead of integer arguments to the --revision switch, and are resolved into specific revision numbers by SVK:

Here are some examples of revision keywords in action. Don't worry if the commands don't make sense yet; we'll be explaining these commands as we go through the chapter:

$ svk diff --revision BASE:HEAD foo.c
# shows the changes in the depot not yet in your working copy.

$ svk log --revision HEAD
# shows log message for the latest depot commit

$ svk diff --revision HEAD
# compares your working file (with local mods) to the latest version
# in the depot.

$ svk diff --revision BASE:HEAD foo.c
# compares your “pristine” foo.c (no local mods) with the 
# latest version in the depot

$ svk log --revision BASE:HEAD
# shows all commit logs since you last updated

These keywords allow you to perform many common (and helpful) operations without having to look up specific revision numbers or remember the exact revision of your working copy.

Anywhere that you specify a revision number or revision keyword, you can also specify a date inside curly braces “{}”. You can even access a range of changes in the depot using both dates and revisions together!

Here are examples of the date formats that SVK accepts. Remember to use quotes around any date that contains spaces.

$ svk checkout --revision {2002-02-17}
$ svk checkout --revision {15:30}
$ svk checkout --revision {15:30:00.200000}
$ svk checkout --revision {"2002-02-17 15:30"}
$ svk checkout --revision {"2002-02-17 15:30 +0230"}
$ svk checkout --revision {2002-02-17T15:30}
$ svk checkout --revision {2002-02-17T15:30Z}
$ svk checkout --revision {2002-02-17T15:30-04:00}
$ svk checkout --revision {20020217T1530}
$ svk checkout --revision {20020217T1530Z}
$ svk checkout --revision {20020217T1530-0500}
…

When you specify a date as a revision, SVK finds the most recent revision of the depot as of that date:

$ svk log --revision {2005-07-23}
----------------------------------------------------------------------
r12 (orig r41):  sally | 2005-07-22 10:06:17 -0700
…

You can also use a range of dates. SVK will find all revisions between both dates, inclusive:

$ svk log --revision {2005-07-20}:{2005-07-29}
…

As we pointed out, you can also mix dates and revisions:

$ svk log --revision {2005-07-20}:4040

Users should be aware of a subtlety that can become quite a stumbling-block when dealing with dates in SVK. Since the timestamp of a revision is stored as a property of the revision—an unversioned, modifiable property—revision timestamps can be changed to represent complete falsifications of true chronology, or even removed altogether. This will wreak havoc on the internal date-to-revision conversion that SVK performs.