Daring Fireball, as ever, with the wry commentary:

It strikes me as an odd coincidence that two serious Subversion clients would debut at a time when many developers are starting to switch away from Subversion to distributed revision control systems such as Git and Mercurial.

• Merge tracking (foundational)
• Sparse checkouts (via new –depth option)
• Interactive conflict resolution
• Changelist support
• Relative URLs, peg revisions in svn:externals
• Cyrus SASL support for ra_svn and svnserve
• Improved support for large deployments on FSFS, via sharding
• Improved FSFS optimizability, via immutable file isolation
• WebDAV transparent write-through proxy
• Improvements to copy and move
• Speed improvements, cancellation response improvements
• Easier to try experimental ra_serf DAV access module
• API changes, improvements, and much language bindings work
• More than 150 new bug fixes, enhancements

If you are still using subversion, or if subversion suits your needs better than distributed alternatives, then this is a must have release.

Will try to review it later. But one interesting feature is its integration with Beanstalk that provides one 20MB Subversion repository for free. Smart move for the casual user who might still be intimidated by the command line interface.

I am now in the process of transitioning my work over to Git. One salient difference is that, with Subversion, I kept all my mission-critical text files in a single structured directory; Git, however, wants to find relationships among everything in the repository, so it is important to keep unrelated projects in different repositories. (Fortunately setting up Git repositories is a snap.) This is important to bear in mind when migrating from Subversion. If, like me, you maintained a single Subversion repository with separate subdirectories for each of your projects, you need to migrate each of these into separate Git repositories.

Here is how I began my migration.

I decided to start with my remind files:

$ mkdir -p /tmp/remind
$ cd !$
$ git-svn clone http://markelikalderon.com/svn/TheHub/Remind --no-metadata

The command:

git-svn clone

calls init, which creates a new Git repository, and fetch, which fetches the contents and history of the directory. git-svn clone takes the options of both init and fetch. One useful option is –no-metadata which strips out the no longer needed Subversion metadata.

Now I needed to configure my new Git repository. I began by creating a file and opening it in my text editor, TextMate:

$ touch ~/users.txt && mate ~/users.txt

I then added the following to users.txt:

kalderon PhilGeek <eli@markelikalderon.com>

‘kalderon’ being my Subversion user name and ‘PhilGeek’ being my Git user name. There should be one line each with this syntax for each of the users. Now I was ready to configure git:

% git config svn.authorsfile ~/users.txt

The final step is to clone this new Git repository to rid ourselves of any remaining svn cruft. I created a new GitHub project and then within the Git repository:

$ git remote add origin git@github.com:PhilGeek/remind.git
$ git push origin master

Finally, I cloned the remote repository into the directory where my remind files were to live locally and deleted the /tmp/remind directory.

Not too bad. But you might consider automating the process with a shell or ruby script, if this needs doing several times over.

The version control bundle requires GNU awk. If gawk is not installed on your *nix system, this script will do it for you:

#!/bin/sh
#
# installgawk.sh
#
# A bash script to install the latest version of GNU awk. Be sure to set the variables to the desired values. 
#
# http://www.gnu.org/software/gawk/
#
# Mark Eli Kalderon 2008-03-22

# Gawk. Change to the desired version if necessary
VER="3.1.6"
GAWK="gawk-${VER}"

# Build directories. Change to the desired directories if necessary.
GBLDDIR=/var/tmp/${GAWK}-build

# Create gawk build directory, but save source files if they exist.
test -d ${GBLDDIR} || mkdir ${GBLDDIR}
test -d ${GBLDDIR}/${GAWK} && /bin/rm -rf ${GBLDDIR}/${GAWK}
cd $GBLDDIR

# Download and unpack gawk source.
curl http://ftp.gnu.org/gnu/gawk/${GAWK}.tar.gz -O
tar -xvzf ${GAWK}.tar.gz
cd ${GAWK}

# Configure and build gawk.
./configure
make
make check

# Install gawk (in /usr/local/bin/). Will prompt for password.
sudo make install

As of version 0.3, the vc bundle supports bazaar, git, and subversion and runs on Windows and unices. Within the vc directory there are subdirectories for each of these cases:

• bzr-unix/
• bzr-windows/
• git-unix/
• git-windows/
• svn-unix/
• svn-windows/

Each of these subdirectories contains a pair of scripts. As I am on OS X and wanted to see how well this would work with git, I used the scripts in git-unix/:

• vc
• vc-git.awk

Copy these to the root directory of your repository. vc is a shell script that extracts version control information and writes it to a new file, vc.tex. vc does this by calling vc-git.awk to process the output of git status and git log. To use these scripts, put the following in the preamble of your LaTeX document:

\immediate\write18{sh ./vc}
\input{vc}

\write18 allows you to call shell scripts when running LaTeX. Most TeX installations has \write18 disabled by default for security reasons. That’s a good thing. Rather than enabling this globally, you can enable this on an as needed basis, by running pdflatex or xelatex with the -shell-escape argument.

vc.tex defines the following macros which can now be used in your LaTeX document:

• \VCRevision current (maximum) working copy revision number
• \VCRevisionMod as \VCRevision, but with an additional note if the working copy contains modified files
• \VCAuthor author of the last check-in operation
• \VCDateRAW date of last check-in in native format of the VCS software
• \VCDateISO date of last check-in in ISO format YYYY-MM-DD
• \VCDateTEX date of last check-in in TeX format YYYY/MM/DD
• \VCTime time of last check-in
• \VCModifiedText contains the note shown in macro \VCRevisionMod if there were modified files. This macro can be redefined by the user.
• \VCModified 0 if there are no modified files in the working copy directory; 1 or 2 if there are modified files. In general you don’t need this macro.

These macros can be called wherever appropriate. I wanted my version control information discretely tucked away in a footer:

\usepackage{fancyhdr}
\lfoot{\tiny{Revision: \VCRevision ; Author: \VCAuthor ; Date: \VCDateISO}}
\cfoot{}
\rfoot{}

The result:

If you want the version control information in draft mode only, Stephan Hennig, vc bundle’s maintainer, suggests using the ifdraft package.

#!/bin/sh
#
# installgit.sh
#
# A bash script to install the latest version of Git. Be sure to set the variables to the desired values. 
#
# http://git.or.cz/
#
# Mark Eli Kalderon 2008-03-15

# Git. Change to the desired versions if necessary
VER="1.5.4.4"
GIT="git-${VER}"
GITMAN="git-manpages-${VER}"

# Build directories. Change to the desired directories if necessary.
GBLDDIR=/var/tmp/${GIT}-build

# Create Git build directory, but save source files if they exist.
test -d ${GBLDDIR} || mkdir ${GBLDDIR}
test -d ${GBLDDIR}/${GIT} && /bin/rm -rf ${GBLDDIR}/${GIT}
cd $GBLDDIR

# Download and unpack Git source.
curl http://kernel.org/pub/software/scm/git/${GIT}.tar.gz -O
tar -xvzf ${GIT}.tar.gz
cd ${GIT}

# Configure and build Git.
./configure --prefix=/usr/local 
make

# Install Git. Will prompt for password.
sudo make install

# Install documentation. Will prompt for password.
curl -O http://kernel.org/pub/software/scm/git/${GITMAN}.tar.bz2
sudo tar xjv -C /usr/local/share/man -f ${GITMAN}.tar.bz2

Call the script installgit.sh and run it with:

$ ./installgit.sh

Installing Git with documentation is another matter. The brave should consult this document. The timid might content themselves with the online Git User’s Manual. Updated script to include SubtleGradient’s sane instructions on how to install Git documentation.

*.aux
*.log
*.out
*.pdfsync
*.bbl
*.blg
*.brf
*.svn
*.dvi
*.toc
*.bak
*.nav
*.snm

(Your helper files may differ depending on the programs you are running. Thus for example, *.bbl files are generated by BibTeX and *.nav files are generated by Beamer. If you are using neither program, they won’t show up on your system.) If you are keeping your LaTeX source in version control with subversion, you don’t want to commit these to your repository. But then, running svn status returns all these “?”s since subversion doesn’t know about these files. If there are a lot of them, this can make it hard to to spot the files that genuinely need to be added. Wouldn’t it be great if there were a way that subversion could just ignore these? Well, here are two.

Method One: Put the list of auxiliary files in a text file called temp. Then in the directory containing your LaTeX source run:

svn propset svn:ignore . -F temp

After this subversion will ignore these files in the directory and stop bugging you about files that you don’t care about. Pretty cool. But it works on a directory by directory basis. If you have a lot of directories of LaTeX files, then this can get tedious.

Method Two: The second method makes this change globally. Subversion comes with a config file. Two actually: /etc/subversion/config and ~/subversion/config. The former configures options for the use of subversion for all users, the latter configures options for the use of subversion on a user by user basis. Let’s modify ~/subversion/config. The config file is divided into sections. Be sure to read ~/subversion/README.txt for the syntax of the config file. In the section [miscellany] I have the following:

global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store *.aux *.log *.out *.pdfsync _rev.tex *.bbl *.blg *.brf *.svn *.dvi *.toc *.nav *.toc *.bak *.snm

These files will now be ignored in all of your working copies.

Suppose you have a document that you are writing and that you are considering restructuring that document. Suppose, further, you are unsure the restructuring will come off in the end. If the document is being kept in a subversion repository, then it is natural to create a branch. The trunk is the directory where the document in its main or current line of development is being kept. The branch is the directory where the alternaitive line of development is being kept. A minimal example of the directory structure would look like this:

|-- mylatexproject\
    |-- trunk\
        |-- mydocument.tex
    |-- branch\
        |-- mydocument.tex

(The diagram is in one way misleading—the trunk and branch directories can contain multiple files.) To create a branch, simply copy trunk\mydocument.tex into branch\ (using the subversion commands, so that subversion knows what’s happening).

If after restructuring your document, you are happy with the changes, then you merge these changes into the trunk. This is done with the command:

svn merge

This command does two things:

1. It compares the differences between two files
2. It applies the differences to a location in the working copy

The command thus takes three arguments. The first two arguments are the locations of the files to be compared (where these can be specified, for example, with their urls in the repository), and the path of the file in the working copy where these changes are to be applied. Notice that the changes are applied to a file in your working copy, so you will need to commit these changes after the merge. For more information see the subversion book or use the command:

svn help merge

Sounds easy. It is. But there are limitations to subversion’s merge command. Let me discuss two.

The first limitation becomes apparent when you repeatedly merge changes. It can happen that you merge the same change twice over. Sometimes this is not a problem. If subversion sees that the relevant file already has the relevant change then it does nothing. But suppose the change has been made but has been further modified. Merging a second time will produce a conflict. The problem arises because subversion doesn’t remember what changes have already been merged into the trunk and so attempts to merge these again.

The second limitation is the inability to exclude a previous revision form being merged. This is particularly relevant to writers. Suppose you are writing a paper and have been invited to give a talk based on that material. It is natural to create a branch. It is also natural to eliminate some things from the talk like footnotes. You do this and commit the change. But suppose in writing the talk you hit upon things that should be in the paper. Suppose commit these changes as well. You would now want to merge these changes into the paper, which is in the trunk. However, you cannot tell svn merge to merge only those changes, and to not merge the previous changes. So with svn merge you would end up losing the footnotes in the original paper.

It is partly for these reasons that Linus Torvalds regards subversion as broken by design. It is true that these problems do not arise in distributed models of version control such as Git and Mercurial.

Fortunately, for subversion users, these and related limiations are being addressed in the next major releas of subversion (1.5.0). But if you cannot wait until then, the script svnmerge.py can help. svnmerge.py is a tool for automatic branch management that addresses these problems. It remembers which changes have already been merged and does the right thing by only merging the new changes. And it lists changes available for merging so that some, but not all, of these can be merged. I have been playing around with svnmerge.py, and will post more about is use.

Subversion is a great command line utility waiting for decent GUI. While the GUI’s supplanting the command line represents the triumph of the Image over the Word, the GUI has its place—even in text editing. With respect to subversion, there’s cognitive utility in being able to visualize the structure of your repository or working copy. While there are GUI front ends to subversion, none are perfect. While on OS X svnX works reasonably well, a compelling solution to graphically representing subversion repositories and working copies has yet to be found. The ideal hybrid app has yet to be written. (The situation is not unlike MP3 players before the iPod.) Fortunately, competition is good, and competition is emerging on the Mac platform. Versions promises a clean look and simple approach without compromising on functionality. A collaboration between João Pavão and madebysofa.com, the beta of Versions is soon ready for a private trial. You can sign up for the private beta at versionsapp.com.

• Subversion

• Subversion, Serendipity, and Discipline

• Subversion and the Single User

• LaTeX and Subversion

• Circle Six Subversion

• Subverting Difference

• Subversion and TextMate

have ended, but I wanted to make one last observation. For authors producing complex documents whose development they need to track, what’s important is version control, not necessarily subversion. There are a variety of version control systems on the market, and while subversion suits my present needs, others may suit your needs better.

One important conceptual difference between version control systems is whether they use a centralized or distributed model. Subversion uses a centralized model. There is a central repository from which local working copies may be checked out. Intriguingly, other version control systems use a distributed model. Git and Mercurial are examples. If you are interested in a version control system based on a distributed model have a look at Mercurial and Mark Adams post about Mercurial and the single user. And if you have a spare hour (and a thick enough skin to persist through his abusive personality—apparently subversion users are stupid and ugly), here is Linus Torvalds explaining the virtues of git’s distributed model:

Update Forgot to mention, if you are using TextMate and are curious about Mercurial, there is a Mercurial bundle that you might try.

Another post in my series on subversion, a free, open source version control system:

• Subversion
• Subversion, Serendipity, and Discipline
• Subversion and the Single User
• LaTeX and Subversion
• Circle Six Subversion
• Subverting Difference

Today we’ll look at three ways that subversion interacts with my favorite text editor, TextMate:

1. TextMate’s subversion repository
2. TextMate’s subversion integration
3. Keeping local modifications to TextMate in sync across multiple computers with subversion

TextMate’s Subversion Repository

In Prefences → Software Update you can set TextMate to automatically check for updates (recommended). You can also set it to watch for cutting edge updates. Cutting edge updates add advanced functionality and some bundles require this setting. In a way, the label is misleading, since the cutting edge updates tend to be very stable. If, however, you want the bleeding edge of TextMate development, you will have to access TextMate’s subversion repository, http://macromates.com/svn/Bundles/trunk/. There you will find bundles, plugins, support files, themes, tools, and more. Instructions about how to checkout bundles from the subversion repository can be found in the manual (RTFM, baby), and the wiki. These should definitely be read. But above all check out Haris Skiadas’ excellent tutorial.

TextMate’s Subversion Integration

TextMate, like other advanced editors on OS X such as BBEdit and Aquamacs, enjoys subversion integration. So instead of working with subversion from the command line or with a subversion front end like svnX, it is possible to work with subversion directly from your text editor. ⌃ ⇧ A brings up a menu with common subversion commands. If you have opened your working copy as a TextMate project, then selecting the root of that directory and selecting `status’ will bring up an HTML window with the output of the command:

svn status

Click on the thumbnail below for a picture.

As you can see, the HTML window not only shows the relevant files and their status, but it allows you to perform certain actions—you can add, revert, diff, and commit. The diff command displays line differences—not great for prose, as I have emphasized here and here. Fortunately, selecting commit brings up the following dialogue window:

Notice that you can diff from here as well. However, this will use whatever diff program you have assigned as the value of the shell variable

TM_SVN_DIFF_CMD 

in Preferences → Advanced → Shell Variables. Setting the value of this variable to fmdiff will allow you to display word differences graphically in FileMerge.

Keeping TextMate in Sync

One of the great things about TextMate is how easily configurable it is. Even if you are not a programmer, after a while you will find yourself writing snippets, commands, and maybe even entire bundles. Suppose, however, you work on more than one machine—say, at home and at work. It would be great if you could keep these local modifications in sync. (Frustration is an essential tab trigger that works on one but not another copy of TextMate.) Fortunately there is an easy solution. Just commit:

~/Libray/Application Support/TextMate

and

svn up

will keep you up to date on whatever machine you are on.

Subversion allows you to compare the differences between revisions of a given document with the command:

svn diff

Let’s begin with the simplest and most common use of this command. But first a bit of terminology. Each time a change is committed to the repository its revision number increments. Revision keywords can be used instead of revision numbers. BASE is a revision keyword and refers to the pristine copy of an item in a working copy. The pristine copy of a file is a copy of your file as it was the last time your working copy was updated. It resides in the .svn directory within your file’s directory. So if your file is foo and it resides in directory bar, then running:

ls -a

in directory bar will reveal:

.svn
foo

.svn is an administrative directory that subversion makes use of and you should never modify it. Other useful revision keywords are:

• HEAD—the latest revision in the repository
• COMMITTED—the last revision in which the file changed before BASE
• PREV—the revision that precedes the last revision in which the file changed before BASE, that is, COMMITTED - 1.

The command:

svn diff foo

will compare the foo with BASE, that is, its pristine copy. So it will reveal the changes you have made to foo since you last updated your working copy. This is one of the more common uses of svn diff since it provides information necessary to write an informative commit message.

That’s pretty useful. But sometimes you may want to do something more. Fortunately, svn diff comes with a slew of options that allow for a fair amount of flexibility.

First, suppose you want to compare the modifications that you made to your file with an older revision, say, revision 17. The command:

svn diff -r 17 foo

allows you to do just that. It compares foo as it was in revision 17 with foo as it presently is in your working copy.

Second, suppose you want to compare the differences between to older revisions, say revisions 17 and 23. The command:

svn diff -r 17:23 http://url/of/your/repository/foo

will display these differences.

One really useful option is –diff-cmd. This option allows you to pass arguments to an external diff program. Why is this useful? Well svn diff only displays line differences. If you are writing prose in a text editor, paragraphs are long lines. What would be more useful is for word differences to be displayed. The option –diff-cmd allows you to use an external diff program that displays word differences.

I like to use Apple’s FileMerge, a graphical diff program that can be opened from the command line with:

opendiff

Unfortunately, opendiff and svn diff use different arguments. So to get opendiff to work with subversion requires a shell script wrapper. Fortunately, Bruno De Fraine has done the heavy lifting. His script fmdiff is just such a wrapper. fmdiff can be downloaded (or checked out) form this link. If you install fmdiff in /usr/local/bin or ~/bin as is your preference and make it executable, you could then run the command:

svn diff diff-cmd fmdiff foo

to reveal the differences between foo and its pristine copy in FileMerge.

Bear in mind, if you want to use an external diff program, say, GNU wdiff, you may very well need to write a wrapper script to accommodate a difference in arguments.

LaTeX is great for complex documents. (Of course, other forms of markup are good as well. DocBook comes to mind.) When working on a complex LaTeX document, it is important, nay, imperative to keep it in some form of version control. (The necessity may not be apparent until you actually use version control—if you don’t, well, just trust me, at least for now.)

I have been posting about a popular, open source form of version control, subversion. If you are keeping your complex LaTeX document in a subversion repository, it would be useful to include information about the current revision, the “Who?”, “What?”, “When?”, and “Where?” of the last committed change, within your document. You could enter this information by hand, but this would be tedious and unreliable. Fortunately, there are LaTeX packages that can help. There are three:

1. svn

2. svninfo

3. svn-multi aka svnkw

The svn package doesn’t work if your LaTeX document comprises multiple files. So that’s out. The svninfo and svnkw packages happily do not share this limitation. The svninfo package, however, has a terrible limitation IMHO. It only registers revision information when you check out the document. This means if you create a LaTeX document, add it to your working copy, and commit the addition, the revision information, the “Who?”, “What?”, “When?”, and “Where?”, will never be registered. So that’s out. That leaves svnkw—which worked well for me. Let me detail how I use it.

In the preamble, I have the following:

\usepackage{svnkw}

\svnidlong

{$HeadURL$}

{$LastChangedDate$}

{$LastChangedRevision$}

{$LastChangedBy$}

\svnRegisterAuthor{kalderon}{Mark Eli Kalderon}

The first line:

\usepackage{svnkw}

should be familiar to LaTeX users—it loads the svnkw package. The command:

\svnidlong

{$HeadURL$}

{$LastChangedDate$}

{$LastChangedRevision$}

{$LastChangedBy$}

gets the url of the file in the repository, the date of the last revision, the last revision number in which the file was changed, and who made the change, from subversion.

Update Sorry, missed a crucial step here. To get this to interact with subversion, you need to enter the following in the Terminal:

svn propset svn:keywords 'HeadURL LastChangedDate LastChangedRevision LastChangedBy' foo.tex

where foo.tex is the name of your LaTeX source. Once this is set, when you commit a change to your repository or receive a change by updating your working copy, this information will be registered. Apologies for the oversight.

Who made the change is the username of the commiter. You might want to include the real name of the commiter. The command:

\svnRegisterAuthor{username}{real name}

registers this information.

The commands:

\svnidlong

and

\svnRegisterAuthor

registers the information described above. Now we want to use this information. There are different ways to do this. See the package documentation for sknkw for more details. I find it useful to include this information in a footer. Here’s how I do it. In the preamble, I include the following:

\usepackage{fancyhdr}

\pagestyle{fancy}

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

\cfoot{}

\rfoot{}

The first line:

\usepackage{fancyhdr}

loads the fancyhdr package. This package allows you to format headers and footers. The second line:

\pagestyle{fancy}

loads the default pagestyle of the fanchdr package. fancyhdr divides footers into three fields:

1. the left field

2. the center field

3. the right field

To place content in these field you use the commands:

\lfoot{}

\cfoot{}

\rfoot{}

respectively. Whatever is between the brackets is inserted in the relevant field. If nothing is between the brackets, then the field is blank. Since there is a lot of information to be placed in the footer, it makes sense to have it flush left, and so I left the center and right fields blank. Let’s take a closer look at the line that is doing all the work:

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

That’s a little daunting, so let’s build up to it, step by step. I want the information in the left field so, of course, I use the command:

\lfoot{}

In the left field I want to include the url of the file, the date of the last change, the revision number of the last change, and the author of the revision. Let’s begin with the url. The command:

\svnkw{HeadURL}

yields the value encoded by:

{$HeadURL$}

in the preamble. LaTeX provides the means of nicely formatting urls. To do this we use the url package loaded in the preamble with:

\usepackage{url}

and we use the command:

\url{}

This gives us:

\url{\svnkw{HeadURL}}

Next the date of the last revision. This is easier. The command:

\svndate

yields the value encoded by:

{$LastChangedDate$}

in the preamble. The revision number is easy as well. The command:

\svnrev

yields the value encoded by:

{$LastChangedRevision$}

in the preamble. The command:

\svnauthor

gives the value encoded by:

{$LastChangedBy$}

in the preamble. Remember, this is the username of the commiter. But, I wanted the full name of the commiter. The command:

\svnFullAuthor*{\svnauthor}

gives the full name of the author registered with:

\svnRegisterAuthor

and the asterisk is a switch that gives both the username and the full name of the commiter. So far, we now have:

\lfoot{\url{\svnkw{HeadURL}} \svndate \svnrev \svnFullAuthor*{\svnauthor}}

Three further refinements are called for.

First, it is useful to label this information. Thus, for example, the value of:

\svnrev

is just a number. A label would provide some useful context for understanding what the number represents. Similarly for the rest of this information. Moreover, it would be useful to clearly distinguish this information, so lets separate them with semicolons. This gives us:

\lfoot{URL: \url{\svnkw{HeadURL}} ; Last changed on: \svndate ; Revision: \svnrev ; Author: \svnFullAuthor*{\svnauthor}}

Second, if you typeset your document at this point, a small problem will become evident. For some reason, the svnkw does not insert spaces between the values of its commands even if you have spaces between them in your document. To correct this we use the command:

\space

and get the following:

\lfoot{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}

Third, this information is really of editorial interest only. I want it to be there, but not in the way. So let’s make it really small. To do this we wrap the content with the command:

\tiny{}

to get the final product:

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

One last thing. Suppose you are using pdflatex as your typesetting engine to directly generate a PDF of your LaTeX document. pdflatex is usefully used in conjunction with the hyperref package that does a lot of nifty things not least of which is turning urls into functional hyperlinks. If you do, then clicking on the url of the file will open that file in your browser. Of course, your browser will ask you for your username and password if it hasn’t already saved that information for you.

Here is a screen shot of the final result:

As promised, a post about subversion workflow, but first some basic concepts.

Commit

Remember being taught journalism in high school English class? A good story must provide answers to four questions: “Who?”, “What?”, “When?”, and “Where?” Or so we were taught.

When you commit a change, subversion records four pieces of information:

1. Subversion records WHO committed the change
2. Subversion records WHAT the change was (a description of the change)
3. Subversion records WHEN the change was committed
4. Subversion records WHERE the change was made (which files or directories in your working copy were changed)

With each change, subversion increments the revision number of the repository. You can then diff against a particular revision or retrieve a particular revision as you like.

The command:

svn commit --message "Description of change" foo.txt

will record your change to foo.txt in your working copy and the “Who?”, “What?”, “When?”, and “Where?” of this change to your subversion repository.

Update

Not only will you want to sync revisions in your working copy to your repository, but sync revisions in your repository to your working copy. The command:

svn update

allows you to do just that. Suppose that foo.txt has been changed since your last update, and it is the seventeenth revision of the repository, then the command will yield:

U foo.txt
Updated to revision 17

This means that your working copy has been modified to reflect the changes to foo.txt and that it now reflects revision 17 of the repository. The letter code U is one of several codes that can be issued. These include:

• U foo—file foo has been updated
• A foo—file or directory foo has been added
• D foo—file or directory has been deleted
• G foo—file foo has been updated but you have made local changes in your working copy not reflected in the repository but these changes do not intersect
• C foo—file foo in your working copy has changes that conflict with the changes to foo in the reposiroty

Cha-Cha-Cha-Changes

So far we have discussed committing changes to the repository, and updating the working copy to reflect the changes to the repository, but how do we make these changes.

There are two kinds of changes:

1. Changes to individual files
2. Changes to the structure of the directory

Changes to individual files is easy. Just make the changes in the appropriate editing program. You don’t need to issue in any subversion specific commands.

Changes to the structure of the directory, however, requires subversion’s help. Fortunately, the relevant commands are easy to understand.

The command:

svn add foo

schedules the file or directory foo to be added to the repository next time you make a commit.

The command:

svn delete foo

schedules the file or directory foo for deletion from the repository next time you commit.

The command:

svn copy foo bar

creates a copy of foo called bar and bar is scheduled for addition to the repository next time you commit

The command:

svn move foo bar

creates a copy of foo called bar and schedules bar for addition and schedules foo for deletion.

Reviewing Changes

Before committing your changes, it is a good idea to review the changes you made. Helpfully, subversion has provided some useful tools for ding this.

First up is the command:

svn status

If this command is issued at the root of your working copy it will yield a description of all the changes that you have made since last updating. The command yields a list of files and directories preceded by letter codes indicating the nature of the changes made. These include:

• M foo—foo has been modified since last updating
• A foo—foo is scheduled for addition
• D foo—foo is scheduled for deletion
• C foo—foo has conflicts with an update
• ? foo—subversion doesn’t know about foo. You may want to add it or remove it.

If svn status indicates that foo.txt has been modified, you may want to examine these changes in detail in order to write a helpful commit message. The command:

svn diff

run at the root of the working copy will print out a list of changes to modified files in diff format. As I observed in a previous post, diff format displays line differences, not word differences. This is not great for prose since paragraphs in text files are long lines so multiple differences in a paragraph will not be adequately represented. Fortunately, subversion allows you to use external diff programs. I will make a separate post about this later.

One more tool. The command:

svn revert foo

will roll back the changes you made to foo to the state foo was in when the working copy was last updated.

The Workflow

With these basic concepts in mind, we can now describe your workflow:

1. Update your working copy
2. Make changes to your working copy
3. Review your changes
4. Resolve any conflicts (to be described in a separate post)
5. Commit your changes.

Subversion was designed for multiple programmers to work on a given project. What benefits does all this provide the single user? Besides providing a database of all changes and a record of these, the workflow really comes into its own when working from multiple locations. Suppose you are working both at home and at work on different machines. Adhering to this workflow will make sure that you are always in sync. This is a vastly more efficient and non-ad hoc framework for keeping your mission critical files in sync than emailing them or keeping them on a flash drive. These methods are helpful, yes. But their ad hoc nature is ultimately a recipe for confusion.

One final thought. GUI front ends such as svnX are helpful, but you should try to master the command line basics. And always remember, the command:

svn help

is your friend.

Most academics might wonder what the big deal is. After all, many save versions of their latest research in an ad hoc fashion, say, with multiple Word files (shudder). The problem is that it is ad hoc and unreliable. Version control is not magic, it requires discipline, but it provides the framework for keeping track of revisions in a non-ad hoc manner. It may well save you a lot of grief.

In subversion, your files are kept in a subversion repository that can either reside locally on your machine or, ideally, on a server. Directories of files can be checked out. This is your working copy, and it resides locally on your machine. You edit the files in your working copy, and when satisfied, you commit your changes to the subversion repository. The working copy can also be updated to propagate the current state of the repository.

There are two aspects of committing that require discipline.

First, nothing is forcing you to commit your changes, and it is easy to get lazy. Personally, I commit and commit often. Remember, commits are free, and the more commits you make, the more detailed record you have of the revisions that you are making. I definitely commit before deleting anything, be it a section, a paragraph, or a memorable if misplaced line—just in case I want to access that material at a later time.

Second, subversion tracks changes to a directory of files. Each time you commit the revision number of the entire repository is incremented. When you commit you enter a commit message. If you commit changes to multiple files, your message must detail the changes to each of these. Fortunately, subversion provides tools to make this easier. Suppose you have been editing the files in your working copy and want to remind yourself what you have done. The command:

svn status

will provide you with detailed information about how your working copy differs from its state when last updated, including which files have been modified, which have been added, and so on. Suppose you want to remind yourself of the changes made to a modified file. The command:

svn diff

will reveal the local modifications in the working copy.

Remember, the more detailed your commit messages, they more useful they will be to you. At first the discipline can seem onerous. But beyond the utility of providing a detailed record of revisions, it is an occasion to reflect on what you have achieved, and what needs to be done. Like the confessional for Catholics, or the weekly review for GTD geeks, the exercise of formal reflection can be good for you.

Next time, I will detail a few more basic concepts of subversion and outline a typical single-user workflow.

In my first post, I reported my discovery that a lot of tools that programmers use are, in fact, readily adaptable to the task of writing. In a previous post I discussed diff programs—programs for comparing differences between text files. In this post, I will be discussing version control.

Programmers and writers face at least one common problem. In writing a complex program, programmers need to track small changes over time. In writing a complex document, writers need to track small changes over time. Programmers, being programmers, have written software to meet this particular need, software that can meet the writer’s corresponding need.

There are a variety of version control systems currently available, but I will be talking about subversion, a popular open source replacement for CVS. Subversion tracks changes to a directory, saving the differences in a database. Wish you hadn’t deleted that paragraph and somehow didn’t save it in the ad hoc versions of the paper you created? With subversion it is just a:

svn cat

away.

This post will be covering installing subverion on Mac OS X. Subsequent posts will cover usage, and integration with the diff program of your choice.

Installation:

STEP ONE: Martin Ott of Coding Monkeys has helpfully provided a binary for OS X. (One cool feature of the OS X version is its keychain integration.) Download the Subversion.pkg.

STEP TWO: Unzip the subversion.pkg, click the pkg-installer and follow the instructions to install Subversion.

STEP THREE: OK, let’s test it out. Open the Terminal (located in /Applications/Utilities), and type:

svn help 

If successfully installed, you should see a helpful usage message. If not, then chances are that subversion is not in your path. (Don’t worry if you do not know what this means.) To add the relevant path do the following: Type:

cd

in Terminal and hit return to navigate to your home directory. Type:

ls -a 

and hit return to see the contents of your home directory (including the files beginning with a ‘.’ normally hidden from the Finder). If a file called ‘.profile’ exists open it up in your favorite text editor. If it doesn’t exist, create it. Now just add the following line:

export PATH=$PATH:/usr/local/bin

Save .profile and type

source .profile

and hit return.

svn help

should now return the help message.

STEP FOUR: First a bit of terminology. A subversion repository is where all your files are stored. Your working copy is a local copy of its contents where changes are made. If you are happy with them, you commit them to the repository. It is possible to have a local repository on your machine, but having your repository on a server allows for some interesting possibilities (such as syncing your files on multiple machines). OpenSVN is a free subversion server. It worked well for me. (Though now mine is on TextDrive which isn’t free.) A comprehensive list of subversion servers can be found on this page of the subversion website. If you are using OpenSVN, click on the link called ‘Create a New Project’ and follow the instructions.

STEP FIVE: Subversion can be managed on the command line. You should take the time to learn how to do so. However, like diff programs (and arguably text editing), there’s a point to using a GUI environment. There are several GUI front ends for subversion. None of the interfaces are ideal. (The killer GUI front end for subversion has yet to be written.) However, svnX is by far the best I have seen on OS X. And it is free. Download it here.

STEP SIX: When you open up svnX you will see two windows. In the window entitled ‘Repositories’, add the url and login name and password from your subversion server.

STEP SEVEN: OK, you are in the home stretch now. You have installed subversion, created a subversion repository on a subversion server, and have a GUI program to manage your subversion repository and working copy. Now all that you have to do is import your project directory into your subversion repository. Once more to the Terminal. (After this, most everything can be handled through svnX.) Type:

svn import -m "import message" /path/to/your/project/directory /url/of/your/repository

(making the appropriate substitutions for the import message and path and url) and hit return.

STEP EIGHT: Now we need to create the working copy. Move your project directory to the Trash. (Don’t worry, you don’t have to empty the trash just yet.) In svnX, click on the name of your repository in the repository window. This will open a new window. Select root and click on ‘svn checkout’. In the dialogue window, select where you want your working copy to live and click ‘open’. Now in the window entitled ‘Working Copies’ add the path of the working copy you just created and the login information from the subversion server.

Congratulations! You are now set up. Subsequent posts will describe usage and integrating with the diff tool of your choice. I you can’t wait check out the tutorial at O’REILLY macdevcenter.com and the subversion book.