Category Archives: Versioning

Subversion Keywords and LaTeX

Update 2008-05-08: Please note that this post was written before I started using svninfo, and I highly recommend it if you are dealing with multiple source files. You still need to set the Id keyword property on each source file, but the double dollar trick is not really needed. See the \svnInfo command.

For each file in a Subversion repository, we can specify a list of name-value pairs which are called “properties”. Properties can be used for any purpose (useful for automation scripts), and they are versioned just like the content of the files.

Some properties, however, have special meanings in Subversion. For example, the automatic end-of-line conversion feature relies on the svn:eol-style property. And in this post, we will look at another one: svn:keywords.

To use the svn:keywords feature, you insert special tags like $keyword$ into your file. There are currently five keywords in Subversion: Date, Rev, Author, URL, Id. The idea is when you commit a file, Subversion will automatically expand the keywords inside the file.

To use this feature, first add the svn:keywords property to the files that you want keyword expansion. For example, svn propset svn:keywords "Date Rev" *.tex will add two keywords to all the TeX files in the current directory.

Then, inside the TeX files, you can insert text fragments like:

Last committed as $ $Rev$ $ on $ $Date$ $

(The extra pairs of dollar signs are added to “eat” the dollar signs that surround Subversion keywords.)

The five keywords are more or less self-explaining. But if you want to dig deeper into advanced features like fixed-width keywords, you can read it here.

P.S. Again it is very convenient to have the properties set automatically for all TeX files in your repository. To do so, here is an example config file that you can use. Any file added after you changed the config file will automatically have their properties set.

End-of-Line Conversion in Subversion

One nice feature of Subversion is its automatic end-of-line conversion capability. Regardless of what’s in the repository, you can ensure that files in your local working copy use the native EOL style.

That is, if you have it set up properly. :P

The trick is to use the properties feature of Subversion. For each file, Subversion allows us to attach a list of properties (key := value). Some properties have special meanings and svn:eol-style is the key that we are interested in today.

When the value of its key is set to native, Subversion will ensure that the file is in the native EOL style every time you update the file in your working copy. And when you check in the file, the conversion will happen automatically so that there are no accidents.

But isn’t it too tedious to have to setup this property for every file that you want automatic EOL conversion to apply? Well, this is when the Subversion local config file comes in.

The config file that I ask my fellows to use contains an auto-property section. Basically, Subversion allows us to automatically attach a property to files of any extension. For instance, to have all my TeX files to use native EOL:

*.tex = svn:eol-style=native

Lovely.

P.S. The auto properties are added when you add a file to version control. So, just replacing the config file will not affect the files that are already under version control. In that case, assuming you have the command line client, use

svn propset -R svn:eol-style native *.tex

to set the property on all TeX files (or other appropriate file types) in the current directory and its descendants.

Subversion Server Rollout

After several months of beta-testing, our Theory group’s Subversion server is now open to host any of our projects. If you want to start using this server for a project, please contact me via email so that I can open a repository for you and setup its access control. Note that our server has been configured to support non-SCS collaborators (anyone who doesn’t have an account in the SCS) and so it is very easy to host your papers.

To download and install the required Subversion client, start from this page.

Please read Chapters 1 to 3 of this online book if you are not familiar with the concept of version control and concurrent development. And even if you are already familiar with the basic operations of CVS, it may help to refresh your memory and learn the subtle (but usually not important) differences between Subversion and CVS. If you have questions, feel free to post a comment here.

P.S. My strategy for this rollout is “let it be” for the first couple months. In the past I have struggled to get the beta-testers do everything “right” when none of these seemingly arbitrary subtleties is critical. Therefore, it seems wiser to let everyone use the server and correct the common mistakes later (in future posts and talks).