Examining History

As we mentioned earlier, the depot is like a time machine. It keeps a record of every change ever committed, and allows you to explore this history by examining previous versions of files and directories as well as the metadata that accompanies them. With a single SVK command, you can check out the depot (or restore an existing working copy) exactly as it was at any date or revision number in the past. However, sometimes you just want to peer into the past instead of going into the past.

There are several commands that can provide you with historical data from the depot:

svk log

Shows you broad information: log messages attached to revisions, and which paths changed in each revision.

svk diff

Shows you the specific details of how a file changed over time.

svk cat

This is used to retrieve any file as it existed in a particular revision number and display it on your screen.

svk list

Displays the files in a directory for any given revision.

svk log

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 diff

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:

  • Examine local changes

  • Compare your working copy to the depot

  • Compare depot to depot

Examining Local Changes

As we've seen, invoking svk diff with no switches will compare your working files to the revision from the depot that your working copy is based on:

$ 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
$

Comparing Working Copy to Repository

If a single --revision (-r) number is passed, then your working copy is compared to the specified revision in the repository.

$ 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
$

Comparing Repository to Repository

If two revision numbers, separated by a colon, are passed via --revision (-r), then the two revisions are directly compared.

$ 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
$

Not only can you use svk diff to compare files in your working copy to the depot, but if you supply a depotpath argument, you can examine the differences between items in the depot without even having a working copy. This is especially useful if you wish to inspect changes in a file when you don't have a working copy on your local machine:

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

svk cat

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.

svk list

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.

A Final Word on History

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
…


[13] See? We told you that SVK was a time machine.