Revisions: Numbers, Keywords, and Dates, Oh My!

Before we go on, you should know a bit about how to identify a particular revision in your depot. As you learned in the section called “Revisions”, a revision is a “snapshot” of the depot at a particular moment in time. As you continue to commit and grow your depot, you need a mechanism for identifying these snapshots.

You specify these revisions by using the --revision (-r) switch plus the revision you want (svk <subcommand> --revision REV) or you can specify a range by separating two revisions with a colon (svk <subcommand> --revision REV1:REV2). And SVK lets you refer to these revisions by number, keyword, or date.

Revision Numbers

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.

Revision Keywords

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:

Note

For every file and directory in your working copy SVK keeps track of the revision you last updated to. You can refer to this as the “BASE” revision.

HEAD

The latest revision in the depot.

BASE

The last revision an item in a working copy was updated to.

Note

BASE, can be used to refer to local paths, but not to DEPOTPATHs.

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.

Revision Dates

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.