SVN version control for MS Office documents

A time ago I had to deal with Office documents managed by SVN. In search for better productivity, I asked myself if I can make MS Office and SVN work together.
The answer is YES! With this post you will learn how to:

• Interact with SVN from inside MS Office
• See the differences between two versions of the same file
• Write the current revision and other useful SVN info inside a document

Why SVN ?

SubVersioN is a great way to “store” and track files that are subject to change regularly. It is a cool VCS (Version Control System – see my post on file storage solutions) and TortoiseSVN – a SVN graphical interface for Windows – is at least as cool.
SVN was not primarily designed for Office documents but it does the job right because it manages binary files quite well out-of-the-box.

What benefits?

I don’t use SVN or any Version Control System for the moment
Gain serenity about how your files are stored. No matter if you work alone or in a team, you would always be able to rollback any changes and track all modifications.

I already use SVN but not for MS Office documents
Unleash the full power out of version control by using it for Office documents!

I already use SVN with MS Office documents + TortoiseSVN
Be more productive using a quick access to SVN right from MS Office.

Interact with SVN from the Office Suite

Several third party tools integrate well inside the MS Office user interface to give you shortcuts to standard SVN commands. Here is a list of plug-ins, starting with my preferred one:

1. MSOfficeSVN (open source) – uses TortoiseSVN in the background, through the SubWCRev’s COM interface
2. OfficeSVN (open source)
3. MagnetSVN (paid, never tested) – probably not distributed any more

A quick insight of MSOfficeSVN

MSOfficeSVN gives you a new section in the ribbon menu. An image is worth a thousand words:

Installation instructions are available from the project website.
Office 2007 and more recent are supported (tested up to version 2019, 64-bit) as well as Office 2003 and older. This menu is compatible with Word, Excel and PowerPoint. Read the instructions carefully because the installation procedures are different for each of the three pieces of software!
You can also customize the shortcut keys if you want/need to!

Here are the instructions for installation with MS Office 2007 and above, just in case the official website goes inaccessible someday.

Word
Copy the files wordsvn.* to %APPDATA%\Microsoft\Word\STARTUP\ (create the folder if it doesn’t exist)
-> Open MS Word, the Subversion ribbon should appear.

Excel
Copy the files excelsvn.* to %APPDATA%\Microsoft\AddIns\
Start Excel and go to [File]/[Options]/[Add-Ins] (or [Office button]/[Excel Options]/[Add-Ins] depending on your version)
Then select “Excel Add-Ins” from the “Manage” drop-down list and click “Go”.
Select “Excelsvn” in the list and close.
-> The Subversion ribbon should appear.

PowerPoint
Copy the files pptsvn.* to %APPDATA%\Microsoft\AddIns\ (same as for Excel)
Start PowerPoint and go to [File]/[Options]/[Add-Ins] (or [Office button]/[PowerPoint Options]/[Add-Ins] depending on your version)
Then select “PowerPoint Add-Ins” from the “Manage” drop-down list and click “Go”.
Select “pptsvn” in the list and close.
-> The Subversion ribbon should appear.

Alternative download link

Difference between two versions of a file

Don’t you ever need to compare two revisions of a same document? It’s so straightforward with TortoiseSVN! Right-click, TortoiseSVN, Diff [what you want].
With the MS Office SVN menu you can click the “Diff” button to get the same result.

Click the below image to see it in action on a Word document:

With an Excel document:

This particular feature is done through scripts which are packaged with TortoiseSVN. They simply download the needed versions from the SVN server and call the existing “Compare” function in the background.
You can notice that the equivalent scripts also exist for OpenOffice/LibreOffice documents. Nice!

Your TortoiseSVN diff/merge configuration should be OK by default to use the diff scripts. If you’re unsure you can open the TortoiseSVN settings and check the “Advanced” configuration under “Diff viewer”.

The exact same feature may exist with TortoiseGit if you use Git under Windows, but I have never tested it. You could also find other tentatives if you are interested.
Simul is an online service which is a lot like GitHub but for Word documents. I didn’t know this website before today but you can give it a shot freely if you’re not afraid about having your docs stored by a third party online service.

Revision numbers inside documents

For easier tracking you would need to write the SVN revision number right inside the document content. This is probably the best way to avoid any mess because it would be managed automatically by the version control system.

SvnProperties4MSOffice

The simplest solution to date is SvnProperties4MSOffice, an open source VB Macro from Tobias OETIKER. Even if it’s only compatible with MS Word, it should be fairly easy to adapt it to Excel or other MS Office tools.
It is based on:

• MS Office “fields” and macros
• TortoiseSVN (version 1.5 and above) ; install it if not done yet
• The SubWCRev tool included with TortoiseSVN, accessed through its COM interface

To insert SVN information inside the document, use the macro as follows:

1. Download SvnProperties4MSOfficeV2 and uncompress it
2. Create a new document or open an existing one
3. ALT+F11 to open the Visual Basic editor
4. File > Import and select the previously downloaded file “SvnProperties4MSOfficeV2.bas”
5. Exit the editor
6. View > Macros > AutoOpen > Run (or simply ALT+F8) to create the SVN-related properties ; this avoids to close and re-open the document
7. Insert > Quick parts > Field (or simply ALT+I,F), choose DocProperty then something beginning with “svn” ; the following list should be available: svnRev, svnUrl, svnDateLocal, svnAuthor, svnHasModifications
8. Save as a *.docm, close, commit your document, re-open it with macro enabled and observe how the fields have been automatically updated

For convenience in the deployment of a company-wide process, you could import the macro into a Word template file. All new documents based on this template would then embed the macro automatically.

Here is my example:

This “TSVN + macro” approach has many advantages over “standard” alternatives:

• No need to set the “svn:keywords” property on each MS Office document.
• No post-processing needed or external program to call.
• Customizable rendering without unwanted dollar characters.

Alternatives

For reference, alternative solutions consist in:

1. Using the standard SVN keywords with some well chosen SVN properties, possibly with auto-properties. (the “SVN way”)
2. Using TSVN keywords with a post-commit routine based on SubWCRev and a client-side hook script. (the “TortoiseSVN way”)

Polarion applies the first one with MS Word.
Generally speaking, I find those alternatives either more difficult to deploy or less robust. In particular it could corrupt newer format of documents (2007 and above) because the Office XML format could be broken.

Always use locks!

Thanks to MSOfficeSVN you now have the auto-lock feature available (unless you have previously disabled it). “What are locks? Are they useful?” you may ask.

Do you remember this message from MS Word saying that “the document – stored on a shared network – is already open for edition by an other user”? Because SVN implies that all the work is done locally, you need a similar mechanism to not get into conflicting file versions. That is what Lock is for.
SVN Lock is a manual action, you need to “Get Lock” each time you want to work on a file. For this reason I strongly recommend to use the “svn:needs-lock” property on each binary file. SVN auto-props can be very useful for that.

Remember: the auto-lock feature of MSOfficeSVN is involved only if “needs-lock” is used. If the “needs-lock” property is not enforced, don’t forget to “Lock” your document before working on it.

I will soon write a post on the management of binary files through SVN, describing the locking workflow in more details. Stay tuned 😉