13.2 ⁑Version Control

[Version control using RCS, CVS or the like] Version control (also known as revision or source control) is a system that tracks changes to documents and source code. This makes it possible to revert to an earlier version or restore files that are accidentally overwritten or deleted. Typically, the system requires a location where the version control database (repository) is stored (usually password-protected). The authors working on the document pull the latest version of the source code from the database, which creates their own local version of the document files. They can then modify these local files, commit their changes, and push the changed files back to the database.

The version control system tracks these changes, who made the changes and when they were made. In the event that two or more authors have made conflicting changes to the same piece of text, the version control system will flag the conflict, and the authors need to decide whether to reject their change or overwrite the other author's change.

For example, if Mabel edits section 1 while Fred edits section 2, when they commit their changes there won't be a conflict. The version control system is able to merge their changes so that the source code on the database contains both the new section 1 and the new section 2. Fred and Mabel can then pull this file to update their own local copy. If they decide they don't like the changes, they can revert to an earlier version of the document. If they accidentally delete their local copy, they can pull a fresh copy from the database.

There are a number of different version control systems, some of which are open source, such as CVS, Subversion (SVN) and Git. Once you have decided which system to use, you need to install the software on your computer and find a location for the database.

In the case of a single author who's only interested in using the version control system as a means of backup, then a local directory can be used. For example, I keep my version control database on an external hard drive. The contents of the external hard drive are periodically backed up to a secondary external device, as an additional precaution. This means that if my primary hard drive fails (which it has done) I can pull all my source code from the database on the external hard drive and I only lose the most recent changes that haven't been committed to the repository. If my external hard drive fails (which it has done) I can restore the repository from the secondary external device and commit my local files. In this case I lose any of the revisions that haven't been backed up, but I still have the latest version of the document.

In the case of multiple authors, a server will be needed. The choice then comes down to a trade-off between document security and budget. There are free options available for public projects, but private projects usually require payment to a third party hosting service, or a secure server within your institution's firewall can be set up (assuming that all the authors are located within the institution). Some hosting services may be supported by advertisements. Bitbucket allows private hosting for up to 5 users under their free plan and GitHub provides private repositories under their paid plans [37].

Although Fred and Mabel can track all the document changes through the version control system, these changes aren't automatically added to the document and can't be viewed from the resulting PDF. This is often desired, but sometimes it's useful to include some of the revision information, particularly when a document is periodically updated and republished. In this latter case, there are some LaTeX packages that can do this, listed in the version-control topic.

For Git users, there's the gitinfo2 package [55] (which replaces the now deprecated gitinfo). For Subversion users, there are four packages available: svn [52], svninfo [9], svn-multi [81] and svn-prov [79]. This last package (svn-prov) is designed for package authors. These packages are all available on both TeX Live and MiKTeX. There's also the vc package [35] that supports Git and Subversion, but this isn't on either TeX Live or MiKTeX and requires awk. For CVS users, there are packages such as rcs [86], rcsinfo [113] or rcs-multi [80], which are available both on TeX Live and MiKTeX.

⚠

Version control systems usually create hidden files or directories. If you need to bundle up your document and send it to, say, a journal or conference proceedings, make sure you exclude all the hidden files. For example:

$ zip -r ⟨name⟩.zip ⟨directory⟩ -x "*/\.*"

For Windows users, there's a command line zip program available in GNU On Windows (GOW).

Example 66. Accessing Subversion Revision Information

This book and the accompanying example documents and exercise solutions are in a Subversion repository. In order to insert version control information into one of these documents, I need to add a keyword anchor. This is just a bit of text in the form

$⟨KeywordName⟩$

The ⟨KeywordName⟩ indicates the information you want to insert and (for Subversion) may be one of [66]:

Date: The last time the file was known to have been changed in the repository.
Revision: The last known revision in which the file was changed in the repository.
Author: The last known user to change this file in the repository.
HeadURL: The full URL to the latest version of the file in the repository.
Id: A compressed combination of the other keywords.
Header: Similar to Id but contains the full URL of the latest revision.

For example:

$Id$

In addition to adding this text to the file under version control (called, for example, svninfo-sample.tex) you also need to tell Subversion to perform a keyword substitution whenever the file is committed. This is done using:

$ svn propset svn:keywords "Id" svninfo-sample.tex

Now, after I next commit the file svninfo-sample.tex, the keyword anchor $Id$ will be changed to the revision information. For example:

$Id: svninfo-sample.tex 383 2014-12-12 19:23:03Z nlct $

This will cause a problem when I build my document as LaTeX will interpret those dollar $ symbols as the maths shift special character, so the information won't be typeset correctly. However, recall from §2.1.1 Macro Definitions that you can use \def to define a command with a particular syntax. For example:

\def\svnInfo$#1${%
  % do something with #1
}

Now I can have

\svnInfo$Id: svninfo-sample.tex 383 2014-12-12 19:23:03Z nlct $

and the $ symbols are part of the syntax and aren't interpreted as the maths mode shift. The svninfo package provides a command called

\svnInfo ␣$⟨Id⟩$␣

which is defined in a similar manner. Note that the trailing space is part of the syntax. This command parses the Id keyword anchor and gathers the information for later use in the document. By default this information is placed in the page footer.

For example, here's my original document called svninfo-sample.tex:

\documentclass{article}

\usepackage{svninfo}

\svnInfo $Id$

\author{Nicola Talbot}
\title{A Sample Document}

\begin{document}
\maketitle

This is a sample document.

\end{document}

If I build this document using pdflatex, the resulting PDF file contains the footer

This is because there's currently no version control information in the file, just the keyword anchor $Id$ . Next I need to add this new file to my Subversion repository:

$ svn add svninfo-sample.tex

(See the Subversion user manual [66] for information on setting up a repository.) Also, I need to indicate that this file contains the Id keyword anchor:

$ svn propset svn:keywords "Id" svninfo-sample.tex

Now I can commit these changes to the repository:

$ svn commit -m "Add svninfo example"

This not only commits the new file svninfo-sample.tex to the repository, but also modifies the file so that it now looks like:

\documentclass{article}

\usepackage{svninfo}

\svnInfo $Id: svninfo-sample.tex 385 2014-12-15 11:45:51Z nlct $

\author{Nicola Talbot}
\title{A Sample Document}

\begin{document}
\maketitle

This is a sample document.
\end{document}

If I rebuild this document, the PDF file is now as shown in Figure 13.2. The footer now contains the revision number and the filename. You can download or view this example.

**Figure 13.2:** Subversion Revision Information
⇩

In addition to \svnInfo, the svninfo package provides a way to gather information from a different keyword, such as Revision, using

\svnKeyword ␣$⟨value⟩$␣

For example:

\svnKeyword $Author: nlct$

Remember that you need to include these extra keywords in the svn:keywords property to ensure they are also expanded. For example, if you want to access the Author and Date rather than the Id, then you need to set the keywords using

$ svn propset svn:keywords "Date Author" svninfo-sample.tex

(Keywords are case-sensitive.) The footline can be removed using the nofancy package option

\usepackage[nofancy]{svninfo}

The Subversion information can be accessed using any of the following commands:

\svnInfoFile

for the name of the source file or --sourcefile-- if unknown;

\svnInfoRevision

for the revision number of the checked out file or --revision-- if unknown;

\svnInfoDate

for the date in the form ⟨YYYY⟩-⟨MM⟩-⟨DD⟩ when the file was checked out or the current date if unknown;

\svnInfoTime

for the time when the file was checked out or --time-- if unknown;

\svnInfoOwner

for user name of the file owner or --owner-- if unknown;

\svnInfoYear

for the year when the file was checked out or the current year if unknown;

\svnInfoMonth

for the month (in ⟨MM⟩ form) when the file was checked out or the current month if unknown;

\svnInfoDay

for the day (in ⟨DD⟩ form) when the file was checked out or the current day if unknown;

\svnInfoLongDate

for the date in the form of \today when the file was checked out or the current date if unknown.

A summary of the Subversion information can be obtained using

\svnId

which uses the same format as the Id keyword anchor. In addition to the above commands, the svninfo package also provides commands for multi-file documents. Every file of the document must include either \svnInfo or \svnKeyword with the Revision keyword. Two LaTeX runs are required.

\svnInfoMinRevision

displays the minimum revision number for all the files in the document, and

\svnInfoMaxRevision

displays the maximum revision number for all the files in the document. (If unknown, the defaults are --minrevision-- and --maxrevision--.) The date from the latest Subversion revision (in the same format as \today) is obtained using:

\svnInfoMaxToday

If you want the URL to the file in the repository, you need the HeadURL keyword

\svnKeyword $HeadURL:$

and you can then use:

\svnInfoHeadURL

to access this information.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).