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.

When working on a project with a team, you'll want to update your mirror to receive any changes made by other developers on the project since your last update.

$ svk sync //mirror/project
Retrieving log information from 500 to 502
Committed revision 503 from revision 500.
Committed revision 504 from revision 501.
Committed revision 505 from revision 502.

Then you'll want to bring those changes into your working copy. Use svk update to bring your working copy into sync with the latest revision in your depot.

$ svk update
Syncing //mirror/project/trunk(/mirror/project/trunk) in /Users/sally/project to 505.
U   foo.c
U   bar.c

In this case, someone else checked in modifications to both foo.c and bar.c since the last time you updated, and SVK has updated your working copy to include those changes.

Let's examine the output of svk update a bit more. When the server sends changes to your working copy, a letter code is displayed next to each item to let you know what actions SVK performed to bring your working copy up-to-date:

Now you can get to work and make changes in your working copy. It's usually most convenient to decide on a particular change (or set of changes) to make, such as writing a new feature, fixing a bug, etc. The SVK commands that you will use here are svk add, svk delete, svk copy, and svk move. However, if you are merely editing files that are already in SVK, you may not need to use any of these commands until you commit. Changes you can make to your working copy:

To make file changes, use your text editor, word processor, graphics program, or whatever tool you would normally use. SVK handles binary files just as easily as it handles text files—and just as efficiently too.

Here is an overview of the four SVK subcommands that you'll use most often to make tree changes (we'll cover svk import and svk mkdir later).

Once you've finished making changes, you need to commit them to the depot, but before you do so, it's usually a good idea to take a look at exactly what you've changed. By examining your changes before you commit, you can make a more accurate log message. You may also discover that you've inadvertently changed a file, and this gives you a chance to revert those changes before committing. Additionally, this is a good opportunity to review and scrutinize changes before publishing them. You can see exactly what changes you've made by using svk status, svk diff, and svk revert. You will usually use the first two commands to find out what files have changed in your working copy, and then perhaps the third to revert some (or all) of those changes.

M   bar.c               # the content in bar.c has local modifications
 M  baz.c               # baz.c has property but no content modifications
?   foo.o               # svk doesn't manage foo.o
!   some_dir            # svk manages this, but it's missing or incomplete
~   qux                 # versioned as file/dir/link, but type has changed
I   .screenrc           # svk doesn't manage this, and is set to ignore it
A   moved_dir           # added with history of where it came from
M   moved_dir/README    # added with history and has local modifications
D   stuff/fish.c        # file is scheduled for deletion
A   stuff/loot/bloo.h   # file is scheduled for addition
C   stuff/loot/lump.c   # file has textual conflicts from an update
 C  stuff/loot/glub.c   # file has property conflicts from an update
R   xyz.c               # file is scheduled for replacement

$ svk status stuff/fish.c
D   stuff/fish.c

$ svk status --verbose
M               44        23    sally     README
                44        30    sally     INSTALL
M               44        20    harry     bar.c
                44        18    ira       stuff
                44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
                44        21    sally     stuff/things
A                0         ?     ?        stuff/things/bloo.h
                44        36    harry     stuff/things/gloo.c

$ svk update --check-only
Syncing //mirror/fish/trunk(/mirror/fish/trunk) in /Users/sally/svk to 35.
C   README
U   stuff/trout.c
1 conflict found.

$ svk diff
=== bar.c
==================================================================
--- bar.c	(revision 3)
    bar.c	(local)
@@ -1,7  1,12 @@
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <unistd.h>
 
 #include <stdio.h>

 int main(void) {
-  printf("Sixty-four slices of American Cheese...\n");
   printf("Sixty-five slices of American Cheese...\n");
 return 0;
 }

=== README
==================================================================
--- README	(revision 3)
    README	(local)
@@ -193,3  193,4 @@ 
 Note to self:  pick up laundry.

=== stuff/fish.c
==================================================================
--- stuff/fish.c	(revision 1)
    stuff/fish.c	(local)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.

=== stuff/things/bloo.h
==================================================================
--- stuff/things/bloo.h	(revision 8)
    stuff/things/bloo.h	(local)
 Here is a new file to describe
 things about bloo.

$ svk diff > patchfile

$ svk commit --message '' --patch - > patchfile

$ svk revert README
Reverted README

$ svk status foo
?   foo

$ svk add foo
A   foo

$ svk revert foo
Reverted foo

$ svk status foo
?   foo

$ svk status README 
$ svk delete README 
D   README
$ svk revert README
Reverted README
$ svk status README

We've already seen how svk update --check-only can predict conflicts. Suppose you run svk update and some interesting things occur:

$ svk update
Syncing //mirror/fish/trunk(/mirror/fish/trunk) in /Users/sally/svk to 46.
U   INSTALL
G   README
g   foo.c

The U, G and g codes are no cause for concern; those files cleanly absorbed changes from the depot. The files marked with U contained no local changes but were Updated with changes from the repository. The G stands for merGed, which means that the file had local changes to begin with, but the changes coming from the depot didn't overlap with the local changes. Finally the g stands for merged, but in this case your local copy already contained all the changes from the depot, so the update operation did not modify the file.

When a file has local changes, and the changes coming from the depot overlap with the local changes, that file is considered to have a conflict. When this happens SVK gives you a number of choices:

$ svk update
Syncing //mirror/fish/trunk(/mirror/fish/trunk) in /Users/sally/svk to 47.
Conflict found in bar.c:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] 

At this point you have a number of options.

For example, Sally makes changes to the file sandwich.txt in the depot. Harry has just changed the file in his working copy and checked it in. Sally updates her working copy before checking in and she gets a conflict. She decides to skip doing the merge and do it by hand after the fact:

$ svk update
Syncing //bread/trunk(/bread/trunk) in /Users/sally/bread to 70.
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] s
C   sandwich.txt
1 conflict found.

At this point, SVK will not allow you to commit the file sandwich.txt until the conflict has been resolved.

$ svk commit --message "Add a few more things"
1 conflict detected. Use 'svk resolved' after resolving them.

If you get a conflict, you need to do one of three things:

Once you've resolved the conflict, you need to let SVK know by running svk resolved. After this SVK no longer considers the file to be in a state of conflict.

$ svk resolved sandwich.txt
/Users/sally/bread/sandwich.txt marked as resolved.

$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
>>>> YOUR VERSION sandwich.txt 112646405792039
Salami
Mortadella
Prosciutto
Djon Mustard
==== ORIGINAL VERSION sandwich.txt 112646405792039
Provolone
Creole Mustard
==== THEIR VERSION sandwich.txt 112646405792039
Provolone
Sauerkraut
Grilled Chicken
Creole Mustard
<<<< 112646405792039
Bottom piece of bread

>>>> YOUR VERSION sandwich.txt 112646405792039
Salami
Mortadella
Prosciutto
Djon Mustard
==== ORIGINAL VERSION sandwich.txt 112646405792039

==== ORIGINAL VERSION sandwich.txt 112646405792039
Provolone
Creole Mustard
==== THEIR VERSION sandwich.txt 112646405792039

==== THEIR VERSION sandwich.txt 112646405792039
Provolone
Sauerkraut
Grilled Chicken
Creole Mustard
<<<< 112646405792039

Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Grilled Chicken
Djon Mustard
Bottom piece of bread

$ svk resolved sandwich.txt
$ svk commit -m "Go ahead and use my sandwich, discarding Sally's Sauerkraut."

$ svk update
Syncing //bread/trunk(/bread/trunk) in /Users/sally/bread to 70.
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] e
Waiting for editor...
Merged sandwich.txt:
a)ccept, e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [a] a
G   sandwich.txt

$ svk update
Syncing //bread/trunk(/bread/trunk) in /Users/sally/bread to 70.
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] t
G   sandwich.txt

$ svk update
Syncing //bread/trunk(/bread/trunk) in /Users/sally/bread to 70.
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] y
G   sandwich.txt

$ svk update
Syncing //bread/trunk(/bread/trunk) in /Users/sally/bread to 70.
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] dt
--- sandwich.txt (BASE)
    sandwich.txt (THEIRS)
@@ -3,5  3,7 @@
 Lettuce
 Tomato
 Provolone
 Sauerkraut
 Grilled Chicken
 Creole Mustard
 Bottom piece of bread
Conflict found in sandwich.txt:
e)dit, d)iff, m)erge, s)kip, t)heirs, y)ours, h)elp? [e] y
G   sandwich.txt

$ svk revert sandwich.txt
Reverted 'sandwich.txt'

Now you're ready to check in your changes. Note that svk resolved, unlike most of the other commands we've dealt with in this chapter, requires an argument. In any case, you want to be careful and only run svk resolved when you're certain that you've fixed the conflict in your file—once you have run svk resolved, SVK will let you commit the file even if it still contains conflict markers.

Finally! Your edits are finished, you've merged all changes from the server, and you're ready to commit your changes to the depot.

The svk commit command sends all of your changes to the depot. When you commit a change, you need to supply a log message, describing your change. Your log message will be attached to the new revision you create. If your log message is brief, you may wish to supply it on the command line using the --message (or -m) switch:

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

However, if you've been composing your log message as you work, you may want to tell SVK to get the message from a file by passing the filename with the --file switch:

$ svk commit --file logmsg 
Committed revision 71.

If you fail to specify either the --message or --file switch, then SVK will automatically launch your favorite editor (see the $SVN_EDITOR section in the section called “”) for composing a log message.

$ svk commit
Waiting for editor...
Log message not modified: a)bort, e)dit, c)ommit?a
Aborted.
$

The depot doesn't know or care if your changes make any sense as a whole; it only checks to make sure that nobody else has changed any of the same files that you did when you weren't looking. If somebody has done that, the entire commit will fail with a message informing you that one or more of your files is out-of-date:

$ svk commit --message "Add more cheese"
Transaction is out of date: Out of date: '/bread/trunk/sandwich.txt' in transaction '71-1'
Please update checkout first.

At this point, you need to run svk update, deal with any merges or conflicts that result, and attempt your commit again.

That covers the basic work cycle for using SVK. There are many other features in SVK that you can use to manage your repository and working copy, but you can get by quite easily using only the commands that we've discussed so far in this chapter.

To find information about the history of a file or directory, use the svk log command. svk log will provide you with a record of who made changes to a file or directory, at what revision it changed, the time and date of that revision, and, if it was provided, the log message that accompanied the commit.

$ svk log
----------------------------------------------------------------------
r71:  sally | 2005-09-11 12:10:39 -0700

Corrected number of cheese slices.
----------------------------------------------------------------------
r70:  sally | 2005-09-11 09:02:15 -0700

Added some Sauerkraut and Grilled Chicken.
----------------------------------------------------------------------
r69:  sally | 2005-09-11 09:00:59 -0700

Made a sandwich.
----------------------------------------------------------------------
r68:  sally | 2005-09-11 09:00:50 -0700

Directory for svk import.
----------------------------------------------------------------------

Note that the log messages are printed in reverse chronological order by default. If you wish to see a different range of revisions in a particular order, or just a single revision, pass the --revision (-r) switch:

$ svk log --revision 5:19    # shows logs 5 through 19 in chronological order

$ svk log -r 19:5            # shows logs 5 through 19 in reverse order

$ svk log -r 8               # shows log for revision 8

You can also examine the log history of a single file or directory. For example:

$ svk log foo.c
…
$ svk log //trunk/code/foo.c
…

These will display log messages only for those revisions in which the working file (or DEPOTPATH) changed.

If you want even more information about a file or directory, svk log also takes a --verbose (-v) switch. Because SVK allows you to move and copy files and directories, it is important to be able to track path changes in the filesystem, so in verbose mode, svk log will include a list of changed paths in a revision in its output:

$ svk log -r8 -v //
----------------------------------------------------------------------
r8:  sally | 2005-07-20 14:37:21 -0700
Changed paths:
  A  /calc/button.c (from /calc/button2.c:7)
  D  /calc/button2.c

Journaled about trip to New York.
----------------------------------------------------------------------

$ svk log -r 2
------------------------------------------------------------------------
$

We've already seen svk diff before—it displays file differences in unified diff format; it was used to show the local modifications made to our working copy before committing to the repository.

In fact, it turns out that there are three distinct uses of svk diff:

$ svk diff
=== rules.txt
==================================================================
--- rules.txt	(revision 3)
    rules.txt	(local)
@@ -1,4  1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
 Chew with your mouth closed
 Listen when others are speaking
$

$ svk diff --revision 3 rules.txt 
=== rules.txt
==================================================================
--- rules.txt	(revision 3)
    rules.txt	(local)
@@ -1,4  1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
 Chew with your mouth closed
 Listen when others are speaking
$

$ svk diff --revision 2:3 rules.txt 
=== rules.txt
==================================================================
--- rules.txt	(revision 2)
    rules.txt	(revision 3)
@@ -1,4  1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
 Freedom = Responsibility
 Everything in moderation
 Chew with your mouth open
$

$ svk diff --revision 4:5 //example/trunk/text/rules.txt
…
$

If you want to examine an earlier version of a file and not necessarily the differences between two files, you can use svk cat:

$ svk cat --revision 2 rules.txt 
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
Chew with your mouth open
$

You can also redirect the output directly into a file:

$ svk cat --revision 2 rules.txt > rules.txt.v2
$

You're probably wondering why we don't just use svk update --revision to update the file to the older revision. There are a few reasons why we might prefer to use svk cat.

First, you may want to see the differences between two revisions of a file using an external diff program (perhaps a graphical one, or perhaps your file is in such a format that the output of unified diff is nonsensical). In this case, you'll need to grab a copy of the old revision, redirect it to a file, and pass both that and the file in your working copy to your external diff program.

Sometimes it's easier to look at an older version of a file in its entirety as opposed to just the differences between it and another revision.

The svk list command shows you what files are in a repository directory without actually downloading the files to your local machine:

$ svk list //
README
bread/
calc/
mirror/
paint/
tags/

If you want a more detailed listing, pass the --verbose (-v) flag to get output like this:

$ svk list --verbose //
     48 harry          1331 Jul 28 02:07 README
     71 sally               Sep 11 12:10 bread/
     63 sally               Aug 25 08:21 calc/
     46 svm                 Jul 23 15:16 mirror/
      4 sally               Jul 20 09:41 paint/
     31 sally               Jul 22 09:33 tags/

The columns tell you the revision at which the file or directory was last modified, the user who modified it, the size if it is a file, the date it was last modified, and the item's name.

In addition to all of the above commands, you can use svk update and svk checkout with the --revision switch to take an entire working copy “back in time” ^[13]:

$ svk checkout --revision 1729 # Checks out a new working copy at r1729
…
$ svk update --revision 1729 # Updates an existing working copy to r1729
…

When SVK modifies your working copy, it tries to do so as safely as possible. Before changing the working copy, SVK writes its intentions to a log file. Next it executes the commands in the log file to apply the requested change. Finally, SVK removes the log file. Architecturally, this is similar to a journaled filesystem. If a SVK operation is interrupted (if the process is killed, or if the machine crashes, for example), the log files remain on disk. By re-executing the log files, SVK can complete the previously started operation, and your working copy can get itself back into a consistent state.

And this is exactly what svk cleanup does: it searches your working copy and runs any leftover logs, removing locks in the process. If SVK ever tells you that some part of your working copy is “locked”, then this is the command that you should run:

$ svk status
/Users/sally/bread/sandwich.txt already locked, use 'svk cleanup' if lock is stalled
$ svk cleanup
$ svk status
M   sandwich.txt

The svk import command is a quick way to copy an unversioned tree of files into a depot, creating intermediate directories as necessary.

$ svk import mytree //some/project --message "Initial import"
Committed revision 1.
Directory /Users/sally/mytree imported to depotpath //some/project as revision 1.

The previous example copied the contents of directory mytree under the directory some/project in the default depot:

$ svk list //some/project
bar.c
foo.c
subdir/

Note that after the import is finished, the original tree is not converted into a working copy. To start working, you still need to svk checkout a fresh working copy of the tree.

$ svk import mytree //some/project --message "Initial import" --to-checkout
Committed revision 1.
Directory /Users/sally/mytree imported to depotpath //some/project as revision 1.
$ svk status --verbose mytree
           1        1 sally        mytree/bar.c
           1        1 sally        mytree/foo.c
           1        1 sally        mytree/subdir/quux.h
           1        1 sally        mytree/subdir
           1        1 sally        mytree

Creating a branch is very simple—you make a copy of the project in the depot using the svk copy command. SVK is not only able to copy single files, but whole directories as well. In this case, you want to make a copy of the /calc/trunk directory. Where should the new copy live? Wherever you wish—it's a matter of project policy. Let's say that your team has a policy of creating branches in the /calc/branches area of the repository, and you want to name your branch my-calc-branch. You'll want to create a new directory, /calc/branches/my-calc-branch, which begins its life as a copy of /calc/trunk.

There are two different ways to make a copy. We'll demonstrate the messy way first, just to make the concept clear. To begin, check out a working copy of the project's root directory, /calc:

$ svk checkout //calc bigwc
Syncing //calc(/calc) in /Users/sally/bigwc to 78.
A   bigwc/trunk
A   bigwc/trunk/button.c
A   bigwc/trunk/Makefile
A   bigwc/trunk/integer.c
A   bigwc/branches

Making a copy is now simply a matter of passing two working-copy paths to the svk copy command:

$ cd bigwc
$ svk copy trunk branches/my-calc-branch
A   branches/my-calc-branch
A   branches/my-calc-branch/button.c
A   branches/my-calc-branch/Makefile
A   branches/my-calc-branch/integer.c
$ svk status
A   branches/my-calc-branch

In this case, the svk copy command recursively copies the trunk working directory to a new working directory, branches/my-calc-branch. As you can see from the svk status command, the new directory is now scheduled for addition to the repository. But also notice the “ ” sign in the third column. This indicates that the scheduled addition is a copy of something, not something new. When you commit your changes, SVK will create /calc/branches/my-calc-branch in the depot by copying /calc/trunk:

$ svk commit --message "Creating a private branch of /calc/trunk."
Committed revision 79.

And now the easier method of creating a branch, which we should have told you about in the first place: svk copy is able to operate directly on two DEPOTPATHs.

$ svk copy //calc/trunk //calc/branches/my-calc-branch \
      --message "Creating a private branch of /calc/trunk."
Committed revision 79.

There's really no difference between these two methods. Both procedures create a new directory in revision 79, and the new directory is a copy of /calc/trunk. This is shown in Figure 4.3, “Depot with new copy”. Notice that the second method, however, performs an immediate commit. ^[14] It's an easier procedure, because it doesn't require you to check out a large mirror of the depot. In fact, this technique doesn't even require you to have a working copy at all.

Figure 4.3. Depot with new copy

Now that you've created a branch of the project, you can check out a new working copy to start using it:

$ svk checkout //calc/branches/my-calc-branch
Syncing //calc/branches/my-calc-branch(/calc/branches/my-calc-branch) in /Users/sally/my-calc-branch to 79.
A   my-calc-branch/button.c
A   my-calc-branch/Makefile
A   my-calc-branch/integer.c
 U  my-calc-branch

There's nothing special about this working copy; it simply mirrors a different directory in the depot. When you commit changes, however, Sally won't ever see them when she updates. Her working copy is of /calc/trunk. (Be sure to read the section called “Switching a Working Copy” later in this chapter: the svk switch command is an alternate way of creating a working copy of a branch.)

Let's pretend that a week goes by, and the following commits happen:

There are now two independent lines of development, shown in Figure 4.4, “The branching of one file's history”, happening on integer.c.

Figure 4.4. The branching of one file's history

Things get interesting when you look at the history of changes made to your copy of integer.c:

$ pwd
/home/user/my-calc-branch
$ svk log --verbose integer.c
----------------------------------------------------------------------
r80:  sally | 2005-09-11 13:12:31 -0700
Changed paths:
  M  /calc/branches/my-calc-branch/integer.c

frozzled the wazjub.
----------------------------------------------------------------------
r79:  sally | 2005-09-11 13:04:13 -0700
Changed paths:
  A  /calc/branches/my-calc-branch (from /calc/trunk:78)

Creating a private branch of /calc/trunk.
----------------------------------------------------------------------

Notice that SVK is only tracing the history of your branch's integer.c to the point where it was copied. It shows the creation of the branch as an event in the history, because integer.c was implicitly copied when all of /calc/trunk/ was copied. If you want to see the history prior to the copy you need to supply the --cross (-x) switch to the svk log command:

$ svk log --verbose --cross integer.c
----------------------------------------------------------------------
r80:  harry | 2005-09-11 13:12:31 -0700
Changed paths:
  M  /calc/branches/my-calc-branch/integer.c

frozzled the wazjub.
----------------------------------------------------------------------
r79:  harry | 2005-09-11 13:04:13 -0700
Changed paths:
  A  /calc/branches/my-calc-branch (from /calc/trunk:78)

Creating a private branch of /calc/trunk.
----------------------------------------------------------------------
r45:  sally | 2005-07-23 14:49:11 -0700
Changed paths:
  M  /calc/trunk/integer.c

* integer.c: changed a docstring.
----------------------------------------------------------------------
r2:  sally | 2005-07-20 09:40:50 -0700
Changed paths:
  A  /calc/trunk/Makefile
  A  /calc/trunk/button.c
  A  /calc/trunk/integer.c

Initial import of calc.
----------------------------------------------------------------------

Now look what happens when Sally runs the same command on her copy of the file:

$ pwd
/home/sally/calc
$ svk log --verbose integer.c
----------------------------------------------------------------------
r82:  sally | 2005-09-11 14:03:03 -0700
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  fix a bunch of spelling errors.
----------------------------------------------------------------------
r45:  sally | 2005-07-23 14:49:11 -0700
Changed paths:
  M  /calc/trunk/integer.c

* integer.c: changed a docstring.
----------------------------------------------------------------------
r2:  sally | 2005-07-20 09:40:50 -0700
Changed paths:
  A  /calc/trunk/Makefile
  A  /calc/trunk/button.c
  A  /calc/trunk/integer.c

Initial import of calc.
----------------------------------------------------------------------

Sally sees her own revision 82 change, but not the change you made in revision 80. As far as SVK is concerned, these two commits affected different files in different depot locations. However, SVK does show that the two files share a common history. Before the branch-copy was made in revision 79, they used to be the same file. That's why you and Sally both see the changes made in revisions 45 and 2.

There are two important lessons that you should remember from this section.

In the previous section, we mentioned that both you and Sally made changes to integer.c on different branches. If you look at Sally's log message for revision 344, you can see that she fixed some spelling errors. No doubt, your copy of the same file still has the same spelling errors. It's likely that your future changes to this file will be affecting the same areas that have the spelling errors, so you're in for some potential conflicts when you merge your branch someday. It's better, then, to receive Sally's change now, before you start working too heavily in the same places.

It's time to use the svk merge command. This command, it turns out, is a very close cousin to the svk diff command (which you read about in Chapter 3). Both commands are able to compare any two objects in the repository and describe the differences. For example, you can ask svk diff to show you the exact change made by Sally in revision 82:

$ svk diff -r 81:82 //calc/trunk

=== integer.c
===================================================================
--- integer.c	(revision 81)
    integer.c	(revision 82)
@@ -147,7  147,7 @@
     case 6:  sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
     case 7:  sprintf(info->operating_system, "Macintosh"); break;
     case 8:  sprintf(info->operating_system, "Z-System"); break;
-    case 9:  sprintf(info->operating_system, "CPM"); break;
     case 9:  sprintf(info->operating_system, "CP/M"); break;
     case 10:  sprintf(info->operating_system, "TOPS-20"); break;
     case 11:  sprintf(info->operating_system, "NTFS (Windows NT)"); break;
     case 12:  sprintf(info->operating_system, "QDOS"); break;
@@ -164,7  164,7 @@
     low = (unsigned short) read_byte(gzfile);  /* read LSB */
     high = (unsigned short) read_byte(gzfile); /* read MSB */
     high = high << 8;  /* interpret MSB correctly */
-    total = low   high; /* add them togethe for correct total */
     total = low   high; /* add them together for correct total */
 
     info->extra_header = (unsigned char *) my_malloc(total);
     fread(info->extra_header, total, 1, gzfile);
@@ -241,7  241,7 @@
      Store the offset with ftell() ! */
 
   if ((info->data_offset = ftell(gzfile))== -1) {
-    printf("error: ftell() retturned -1.\n");
     printf("error: ftell() returned -1.\n");
     exit(1);
   }
 
@@ -249,7  249,7 @@
   printf("I believe start of compressed data is %u\n", info->data_offset);
   #endif
   
-  /* Set postion eight bytes from the end of the file. */
   /* Set position eight bytes from the end of the file. */
 
   if (fseek(gzfile, -8, SEEK_END)) {
     printf("error: fseek() returned non-zero\n");

The svk merge command is almost exactly the same. Instead of printing the differences to your terminal, however, it applies them directly to your working copy as local modifications:

$ svk merge -r 81:82 //calc/trunk
U  integer.c
$ svk status
M  integer.c

The output of svk merge shows that your copy of integer.c was patched. It now contains Sally's change—the change has been “copied” from the trunk to your working copy of your private branch, and now exists as a local modification. At this point, it's up to you to review the local modification and make sure it works correctly.

In another scenario, it's possible that things may not have gone so well, and that integer.c may have entered a conflicted state. You might need to resolve the conflict using standard procedures (see Chapter 3), or if you decide that the merge was a bad idea altogether, simply give up and svk revert the local change.

But assuming that you've reviewed the merged change, you can svk commit the change as usual. At that point, the change has been merged into your repository branch. In version control terminology, this act of copying changes between branches is commonly called porting changes.

When you commit the local modification, make sure your log message mentions that you're porting a specific change from one branch to another. For example:

$ svk commit -m "integer.c: ported r344 (spelling fixes) from trunk."
Sending        integer.c
Transmitting file data .
Committed revision 360.

As you'll see in the next sections, this is a very important “best practice” to follow.

$ svk diff -r 343:344 http://svk.example.com/repos/calc/trunk > patchfile
$ patch -p0  < patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done

A word of warning: while svk diff and svk merge are very similar in concept, they do have different syntax in many cases. Be sure to read about them in Chapter 9 for details, or ask svk help. For example, svk merge requires a working-copy path as a target, i.e. a place where it should apply the tree-changes. If the target isn't specified, it assumes you are trying to perform one of the following common operations:

If you are merging a directory and haven't specified a target path, svk merge assumes the first case above and tries to apply the changes into your current directory. If you are merging a file, and that file (or a file by the same name) exists in your current working directory, svk merge assumes the second case and tries to apply the changes to a local file with the same name.

If you want changes applied somewhere else, you'll need to say so. For example, if you're sitting in the parent directory of your working copy, you'll have to specify the target directory to receive the changes:

$ svk merge -r 343:344 http://svk.example.com/repos/calc/trunk my-calc-branch
U   my-calc-branch/integer.c

You've now seen an example of the svk merge command, and you're about to see several more. If you're feeling confused about exactly how merging works, you're not alone. Many users (especially those new to version control) are initially perplexed about the proper syntax of the command, and about how and when the feature should be used. But fear not, this command is actually much simpler than you think! There's a very easy technique for understanding exactly how svk merge behaves.

The main source of confusion is the name of the command. The term “merge” somehow denotes that branches are combined together, or that there's some sort of mysterious blending of data going on. That's not the case. A better name for the command might have been svk diff-and-apply, because that's all that happens: two repository trees are compared, and the differences are applied to a working copy.

The command takes three arguments:

Once these three arguments are specified, the two trees are compared, and the resulting differences are applied to the target working copy as local modifications. When the command is done, the results are no different than if you had hand-edited the files, or run various svk add or svk delete commands yourself. If you like the results, you can commit them. If you don't like the results, you can simply svk revert all of the changes.

The syntax of svk merge allows you to specify the three necessary arguments rather flexibly. Here are some examples:

      
$ svk merge http://svk.example.com/repos/branch1@150 \
            http://svk.example.com/repos/branch2@212 \
            my-working-copy
            
$ svk merge -r 100:200 http://svk.example.com/repos/trunk my-working-copy

$ svk merge -r 100:200 http://svk.example.com/repos/trunk

The first syntax lays out all three arguments explictly, naming each tree in the form URL@REV and naming the working copy target. The second syntax can be used as a shorthand for situations when you're comparing two different revisions of the same URL. The last syntax shows how the working-copy argument is optional; if omitted, it defaults to the current directory.

To complete our running example, we'll move forward in time. Suppose several days have passed, and many changes have happened on both the trunk and your private branch. Suppose that you've finished working on your private branch; the feature or bug fix is finally complete, and now you want to merge all of your branch changes back into the trunk for others to enjoy.

So how do we use svk merge in this scenario? Remember that this command compares two trees, and applies the differences to a working copy. So to receive the changes, you need to have a working copy of the trunk. We'll assume that either you still have your original one lying around (fully updated), or that you recently checked out a fresh working copy of /calc/trunk.

But which two trees should be compared? At first glance, the answer may seem obvious: just compare the latest trunk tree with your latest branch tree. But beware—this assumption is wrong, and has burned many a new user! Since svk merge operates like svk diff, comparing the latest trunk and branch trees will not merely describe the set of changes you made to your branch. Such a comparison shows too many changes: it would not only show the addition of your branch changes, but also the removal of trunk changes that never happened on your branch.

To express only the changes that happened on your branch, you need to compare the initial state of your branch to its final state. Using svk log on your branch, you can see that your branch was created in revision 341. And the final state of your branch is simply a matter of using the HEAD revision. That means you want to compare revisions 341 and HEAD of your branch directory, and apply those differences to a working copy of the trunk.

$ svk log --verbose --stop-on-copy \
          http://svk.example.com/repos/calc/branches/my-calc-branch
…
------------------------------------------------------------------------
r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   A /calc/branches/my-calc-branch (from /calc/trunk:340)

$

Here's the final merging procedure, then:

$ cd calc/trunk
$ svk update
At revision 405.

$ svk merge -r 341:405 http://svk.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svk status
M   integer.c
M   button.c
M   Makefile

# ...examine the diffs, compile, test, etc...

$ svk commit -m "Merged my-calc-branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.

Again, notice that the commit log message very specifically mentions the range of changes that was merged into the trunk. Always remember to do this, because it's critical information you'll need later on.

For example, suppose you decide to keep working on your branch for another week, in order to complete an enhancement to your original feature or bug fix. The repository's HEAD revision is now 480, and you're ready to do another merge from your private branch to the trunk. But as discussed in the section called “Best Practices for Merging”, you don't want to merge the changes you've already merged before; you only want to merge everything “new” on your branch since the last time you merged. The trick is to figure out what's new.

The first step is to run svk log on the trunk, and look for a log message about the last time you merged from the branch:

$ cd calc/trunk
$ svk log
…
------------------------------------------------------------------------
r406 | user | 2004-02-08 11:17:26 -0600 (Sun, 08 Feb 2004) | 1 line

Merged my-calc-branch changes r341:405 into the trunk.
------------------------------------------------------------------------
…

Aha! Since all branch-changes that happened between revisions 341 and 405 were previously merged to the trunk as revision 406, you now know that you want to merge only the branch changes after that—by comparing revisions 406 and HEAD.

$ cd calc/trunk
$ svk update
At revision 480.

# We notice that HEAD is currently 480, so we use it to do the merge:

$ svk merge -r 406:480 http://svk.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svk commit -m "Merged my-calc-branch changes r406:480 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 481.

Now the trunk contains the complete second wave of changes made to the branch. At this point, you can either delete your branch (we'll discuss this later on), or continue working on your branch and repeat this procedure for subsequent merges.

Another common use for svk merge is to roll back a change that has already been committed. Suppose you're working away happily on a working copy of /calc/trunk, and you discover that the change made way back in revision 303, which changed integer.c, is completely wrong. It never should have been committed. You can use svk merge to “undo” the change in your working copy, and then commit the local modification to the repository. All you need to do is to specify a reverse difference:

$ svk merge -r 303:302 http://svk.example.com/repos/calc/trunk
U  integer.c

$ svk status
M  integer.c

$ svk diff
…
# verify that the change is removed
…

$ svk commit -m "Undoing change committed in r303."
Sending        integer.c
Transmitting file data .
Committed revision 350.

One way to think about a repository revision is as a specific group of changes (some version control systems call these changesets). By using the -r switch, you can ask svk merge to apply a changeset, or whole range of changesets, to your working copy. In our case of undoing a change, we're asking svk merge to apply changeset #303 to our working copy backwards.

Keep in mind that rolling back a change like this is just like any other svk merge operation, so you should use svk status and svk diff to confirm that your work is in the state you want it to be in, and then use svk commit to send the final version to the repository. After committing, this particular changeset is no longer reflected in the HEAD revision.

Again, you may be thinking: well, that really didn't undo the commit, did it? The change still exists in revision 303. If somebody checks out a version of the calc project between revisions 303 and 349, they'll still see the bad change, right?

Yes, that's true. When we talk about “removing” a change, we're really talking about removing it from HEAD. The original change still exists in the repository's history. For most situations, this is good enough. Most people are only interested in tracking the HEAD of a project anyway. There are special cases, however, where you really might want to destroy all evidence of the commit. (Perhaps somebody accidentally committed a confidential document.) This isn't so easy, it turns out, because Subversion was deliberately designed to never lose information. Revisions are immutable trees which build upon one another. Removing a revision from history would cause a domino effect, creating chaos in all subsequent revisions and possibly invalidating all working copies. ^[16]

The great thing about version control systems is that information is never lost. Even when you delete a file or directory, it may be gone from the HEAD revision, but the object still exists in earlier revisions. One of the most common questions new users ask is, “How do I get my old file or directory back?”

The first step is to define exactly which item you're trying to resurrect. Here's a useful metaphor: you can think of every object in the repository as existing in a sort of two-dimensional coordinate system. The first coordinate is a particular revision tree, and the second coordinate is a path within that tree. So every version of your file or directory can be defined by a specific coordinate pair.

Subversion has no Attic directory like CVS does, ^[17] so you need to use svk log to discover the exact coordinate pair you wish to resurrect. A good strategy is to run svk log --verbose in a directory which used to contain your deleted item. The --verbose option shows a list of all changed items in each revision; all you need to do is find the revision in which you deleted the file or directory. You can do this visually, or by using another tool to examine the log output (via grep, or perhaps via an incremental search in an editor).

$ cd parent-dir
$ svk log --verbose
…
------------------------------------------------------------------------
r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines
Changed paths:
   D /calc/trunk/real.c
   M /calc/trunk/integer.c

Added fast fourier transform functions to integer.c.
Removed real.c because code now in double.c.
…

In the example, we're assuming that you're looking for a deleted file real.c. By looking through the logs of a parent directory, you've spotted that this file was deleted in revision 808. Therefore, the last version of the file to exist was in the revision right before that. Conclusion: you want to resurrect the path /calc/trunk/real.c from revision 807.

That was the hard part—the research. Now that you know what you want to restore, you have two different choices.

One option is to use svk merge to apply revision 808 “in reverse”. (We've already discussed how to undo changes, see the section called “Undoing Changes”.) This would have the effect of re-adding real.c as a local modification. The file would be scheduled for addition, and after a commit, the file would again exist in HEAD.

In this particular example, however, this is probably not the best strategy. Reverse-applying revision 808 would not only schedule real.c for addition, but the log message indicates that it would also undo certain changes to integer.c, which you don't want. Certainly, you could reverse-merge revision 808 and then svk revert the local modifications to integer.c, but this technique doesn't scale well. What if there were 90 files changed in revision 808?

A second, more targeted strategy is not to use svk merge at all, but rather the svk copy command. Simply copy the exact revision and path “coordinate pair” from the repository to your working copy:

$ svk copy --revision 807 \
           http://svk.example.com/repos/calc/trunk/real.c ./real.c

$ svk status
A      real.c

$ svk commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c."
Adding         real.c
Transmitting file data .
Committed revision 1390.

The plus sign in the status output indicates that the item isn't merely scheduled for addition, but scheduled for addition “with history”. Subversion remembers where it was copied from. In the future, running svk log on this file will traverse back through the file's resurrection and through all the history it had prior to revision 807. In other words, this new real.c isn't really new; it's a direct descendant of the original, deleted file.

Although our example shows us resurrecting a file, note that these same techniques work just as well for resurrecting deleted directories.

Version control is most often used for software development, so here's a quick peek at two of the most common branching/merging patterns used by teams of programmers. If you're not using Subversion for software development, feel free to skip this section. If you're a software developer using version control for the first time, pay close attention, as these patterns are often considered best practices by experienced folk. These processes aren't specific to Subversion; they're applicable to any version control system. Still, it may help to see them described in Subversion terms.

$ cd trunk-working-copy

$ svk update
At revision 1910.

$ svk merge http://svk.example.com/repos/calc/trunk@1910 \
            http://svk.example.com/repos/calc/branches/mybranch@1910
U  real.c
U  integer.c
A  newdirectory
A  newdirectory/newfile
…

Once again, svk copy comes to the rescue. If you want to create a snapshot of /calc/trunk exactly as it looks in the HEAD revision, then make a copy of it:

$ svk copy http://svk.example.com/repos/calc/trunk \
           http://svk.example.com/repos/calc/tags/release-1.0 \
      -m "Tagging the 1.0 release of the 'calc' project."

Committed revision 351.

This example assumes that a /calc/tags directory already exists. (If it doesn't, see svk mkdir). After the copy completes, the new release-1.0 directory is forever a snapshot of how the project looked in the HEAD revision at the time you made the copy. Of course you might want to be more precise about exactly which revision you copy, in case somebody else may have committed changes to the project when you weren't looking. So if you know that revision 350 of /calc/trunk is exactly the snapshot you want, you can specify it by passing -r 350 to the svk copy command.

But wait a moment: isn't this tag-creation procedure the same procedure we used to create a branch? Yes, in fact, it is. In Subversion, there's no difference between a tag and a branch. Both are just ordinary directories that are created by copying. Just as with branches, the only reason a copied directory is a “tag” is because humans have decided to treat it that way: as long as nobody ever commits to the directory, it forever remains a snapshot. If people start committing to it, it becomes a branch.

If you are administering a repository, there are two approaches you can take to managing tags. The first approach is “hands off”: as a matter of project policy, decide where your tags will live, and make sure all users know how to treat the directories they copy in there. (That is, make sure they know not to commit to them.) The second approach is more paranoid: you can use one of the access-control scripts provided with Subversion to prevent anyone from doing anything but creating new copies in the tags-area (See Chapter 6, Server Configuration.) The paranoid approach, however, isn't usually necessary. If a user accidentally commits a change to a tag-directory, you can simply undo the change as discussed in the previous section. This is version control, after all.

Sometimes you may want your “snapshot” to be more complicated than a single directory at a single revision.

For example, pretend your project is much larger than our calc example: suppose it contains a number of subdirectories and many more files. In the course of your work, you may decide that you need to create a working copy that is designed to have specific features and bug fixes. You can accomplish this by selectively backdating files or directories to particular revisions (using svk update -r liberally), or by switching files and directories to particular branches (making use of svk switch). When you're done, your working copy is a hodgepodge of repository locations from different revisions. But after testing, you know it's the precise combination of data you need.

Time to make a snapshot. Copying one URL to another won't work here. In this case, you want to make a snapshot of your exact working copy arrangement and store it in the repository. Luckily, svk copy actually has four different uses (which you can read about in Chapter 9), including the ability to copy a working-copy tree to the repository:

$ ls
my-working-copy/

$ svk copy my-working-copy http://svk.example.com/repos/calc/tags/mytag

Committed revision 352.

Now there is a new directory in the repository, /calc/tags/mytag, which is an exact snapshot of your working copy—mixed revisions, URLs, and all.

Other users have found interesting uses for this feature. Sometimes there are situations where you have a bunch of local changes made to your working copy, and you'd like a collaborator to see them. Instead of running svk diff and sending a patch file (which won't capture tree changes), you can instead use svk copy to “upload” your working copy to a private area of the repository. Your collaborator can then either checkout a verbatim copy of your working copy, or use svk merge to receive your exact changes.

There are some standard, recommended ways to organize a repository. Most people create a trunk directory to hold the “main line” of development, a branches directory to contain branch copies, and a tags directory to contain tag copies. If a repository holds only one project, then often people create these top-level directories:

/trunk
/branches
/tags

If a repository contains multiple projects, admins typically index their layout by project (see the section called “” to read more about “project roots”):

/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags

Of course, you're free to ignore these common layouts. You can create any sort of variation, whatever works best for you or your team. Remember that whatever you choose, it's not a permanent commitment. You can reorganize your repository at any time. Because branches and tags are ordinary directories, the svk move command can move or rename them however you wish. Switching from one layout to another is just a matter of issuing a series of server-side moves; if you don't like the way things are organized in the repository, just juggle the directories around.

Remember, though, that while moving directories may be easy to do, you need to be considerate of your users as well. Your juggling can be disorienting to users with existing working copies. If a user has a working copy of a particular repository directory, your svk move operation might remove the path from the latest revision. When the user next runs svk update, they'll be told that their working copy represents a path that no longer exists, and the user will be forced to svk switch to the new location.

Another nice feature of Subversion's model is that branches and tags can have finite lifetimes, just like any other versioned item. For example, suppose you eventually finish all your work on your personal branch of the calc project. After merging all of your changes back into /calc/trunk, there's no need for your private branch directory to stick around anymore:

$ svk delete http://svk.example.com/repos/calc/branches/my-calc-branch \
             -m "Removing obsolete branch of calc project."

Committed revision 375.

And now your branch is gone. Of course it's not really gone: the directory is simply missing from the HEAD revision, no longer distracting anyone. If you use svk checkout, svk switch, or svk list to examine an earlier revision, you'll still be able to see your old branch.

If browsing your deleted directory isn't enough, you can always bring it back. Resurrecting data is very easy in Subversion. If there's a deleted directory (or file) that you'd like to bring back into HEAD, simply use svk copy -r to copy it from the old revision:

$ svk copy -r 374 http://svk.example.com/repos/calc/branches/my-calc-branch \
                  http://svk.example.com/repos/calc/branches/my-calc-branch

Committed revision 376.

In our example, your personal branch had a relatively short lifetime: you may have created it to fix a bug or implement a new feature. When your task is done, so is the branch. In software development, though, it's also common to have two “main” branches running side-by-side for very long periods. For example, suppose it's time to release a stable calc project to the public, and you know it's going to take a couple of months to shake bugs out of the software. You don't want people to add new features to the project, but you don't want to tell all developers to stop programming either. So instead, you create a “stable” branch of the software that won't change much:

$ svk copy http://svk.example.com/repos/calc/trunk \
         http://svk.example.com/repos/calc/branches/stable-1.0 \
         -m "Creating stable branch of calc project."

Committed revision 377.

And now developers are free to continue adding cutting-edge (or experimental) features to /calc/trunk, and you can declare a project policy that only bug fixes are to be committed to /calc/branches/stable-1.0. That is, as people continue to work on the trunk, a human selectively ports bug fixes over to the stable branch. Even after the stable branch has shipped, you'll probably continue to maintain the branch for a long time—that is, as long as you continue to support that release for customers.

While SVK has different switches for its subcommands, all switches are global^[20]—that is, each switch is guaranteed to mean the same thing regardless of the subcommand you use it with. For example, --verbose (-v) always means “verbose output”, regardless of the subcommand you use it with.

You can specify a command line switch anywhere on the command line after the name of the subcommand itself. So it's OK to mix switches and options. SVK knows what is what.