The CAPE Subversion System serves as both a version control system and a central repository for important design documents and software. The basis of this system is the database driven Subversion (sometimes referred to as SVN) software. Subversion provides both the host and client software for creating and accessing a local or remote repository. The Subversion host software automatically handles version incrementing as well as maintaining a history of the repository. Need to take a look at a file from three days ago that has been changed seven times since? Subversion can handle it.
Terminology
Before getting started with Subversion, some basic terminology used in most version control systems including the CAPE Subversion Repository must be understood. In most version control systems there are three folders or directories, the trunk, branches and tags.
Trunk
The trunk is where the main work is done. The latest version of any file which is part of the system should be stored here even and especially if it is incomplete. In a normal version controlled workflow the files in the trunk are constantly being modified, renamed, created, deleted or otherwise manipulated. Since subversion can handle both plain-text files such as source code and binary files, the files stored in the trunk subdirectories of the CAPE repositories should include schematics, layouts, block diagrams, source code and any other design document. The internal structure and organization of the CAPE Repository is discussed under the Organization subheading in the CAPE Repository section below.
Branches
Branches occur when development leaves the trunk for some reason. The best way to explain this is through examples. The first example is the RFBoardRevCTest branch under the Communications/Software/branches directory in the CAPE Repository. The RFBoardRevCTest branch was created so that the firmware for the communications board could be modified by adding test procedures that should not be used in the final flight version. By branching from the trunk to do this, the main code is left untainted and if any changes made to the new branch should need to be made in the trunk the changes can be merged where appropriate.
The second example is fairly common in software development where multiple people are working on the same project and rely on the same codebase. Say developer X wishes to implement feature “foo” which may take a long time and requires modification of files which cause the overall build to not work even though developer Y still needs a working copy of the repository for his work. In this case, developer X could create a branch to develop feature “foo” allowing developer Y to continue to work in the main trunk. After developer X has finished developing “foo,” he can then merge the branch back into the trunk.
Tags
Tags are somewhat self-explanatory. The Subversion version control system automatically increments the revision number everytime a change is committed to the repository. This, however, is not the same as “Diagnostic Connector Rev 1.3” document. In the case of the Diagnostic Connector, there should be a running copy in the trunk directory of the Documentation folder and “Diagnostic_Connector_Rev1_3_2006_05_31.doc” would be in the tags folder not to be changed. Of course there is nothing to prevent someone from changing a file within the tags folders, but TortoiseSVN will warn anyone who tries. In addition, there is always a historical record of change which the repository or any file in it can be reverted to.
Another example of using tags is the “RFBoardRevC” directory under the Communications->Hardware->tags directory in the CAPE Repository. In this example RFBoardRevC contains the schematic and PCB layout of the latest Communications board as it was ordered and received. The benefit of using tags is they provide a quick reference point to important releases even while the trunk is being modified.
Methods
There are two basic methods of accessing and modifying the repository under Microsoft Windows. The officially supported and most documented is using the Command Line Interface or CLI. Subversion is a multiplatform product and while there are different GUI tools for each platform the command line syntax is the only tool guaranteed to remain consistent (with a few caveats not relevant to the discussion here. The other method is to use a GUI based application such as TortoiseSVN. TortoiseSVN is one of the nicest Windows clients for subversion with direct integration in Windows Explorer. This tutorial will mostly focus on using TortoiseSVN while presenting the CLI equivalent commands.
There is also a third method for accessing the Subversion repository. Subversion can provide a web-based browsing environment which is enabled on the CAPE Repository. Simply visit http://svn.jonathanwagner.net/cape/ with any web browser to peruse and even download any file in the repository. The only major caveat is that only the most recent revision can be seen, which is another reason to use tags when versioning a document.
CLI Version
The CLI version of Subversion is the official release version and includes several tools in the package. The most important ones are the actual svn executable and the svnadmin executable. The svn executable is the base command for most daily-use operations. The svn command is never called without parameters. Examples of use for the CLI version use include “svn checkout http://svn.jonathanwagner.net/cape C:\WorkingCopy” and the like. The first parameter is usually the actual svn command desired and the following commands are the directories and files affected.
TortoiseSVN
TortoiseSVN is a GUI based version of Subversion which is tightly integrated into Windows Explorer. All of TortoiseSVN based operations are accessible from within the right-click menu inside Windows Explorer. Also, TortoiseSVN only provides access to the commands which are valid for the context. For example, there is no option to commit a change to the repository if either no repository has been checked out and modified. This is helpful because it prevents wasted time spent trying invalid commands. TortoiseSVN is the easiest method for using a Subversion repository in Windows.
TortoiseSVN also uses icon overlays in Windows Explorer to differentiate between repository files and local files as well as flag whether a file has been modified, added or deleted since the “checkout” of the local working copy.
Download and Install
Whichever method is used, the software must be downloaded and installed on the working computer. I recommend installing at least TortoiseSVN. Ideally both TortoiseSVN and the official Subversion packages should be installed especially if the MPLAB IDE integration is to be used. The download locations for the two packages:
Working with Subversion
Before describing the specifics of the CAPE Repository there are a few commands/actions which are required for average use of the repository. These actions apply to any Subversion repository and have similar counterparts in any modern version control system. Since this tutorial is geared toward the use of the CAPE Repository it is assumed that a repository already exists. Therefore the actions of creating or importing a repository will not be covered.
To get furthur help on any command in TortoiseSVN refer to the Help item in the TortoiseSVN submenu available when right-clicking anywhere within Windows Explorer. For the CLI version typing “svn help” will display a list of available commands. Typing “svn help command” where “command” is the appropriate command from the list will offer a detailed description of the function and proper use of said command.
Checkout a Repository
Before beginning work in any file or directory in the repository, there needs to be a local working copy. This is achieved by “checking out” a copy from the repository. Before starting, a preferably empty “working copy” directory is needed to store the local version of the repository.
TortoiseSVN
TortoiseSVN makes checking out a repository extremely simple. First, open the folder which will hold the local working copy of the repository in Windows Explorer. Many people literally call this folder “Working Copy” or “wc.” Next, right-click anywhere in the open window and select the “SVN Checkout…” button.
In the dialog window that appears, type the Repository URL in the appropriate field. For the CAPE repository, the URL is http://svn.jonathanwagner.net/cape/. The Checkout directory should contain the path to the appropriate working copy directory. If it is incorrect, it can be changed by either typing the correct path or clicking the “…” button and browsing to the appropriate directory.
The browse button also works for the Repository URL if only a subdirectory of the repository is needed. After entering the base repositroy URL (i.e. http://svn.jonathanwagner.net/cape/), clicking the “…” button brings opens the TortoiseSVN : Repository Browser. From there all subdirectories are accessible and simply browsing to the appropriate subdirectory and clicking the “OK” button will load the URL into the appropriate field of the previous window.
At the bottom of the TortoiseSVN : Checkout window there are two radio buttons and a text field. Selecting the “HEAD revision” radio button chooses the latest revision of the repository. Optionally, checking the plain “Revision” option and entering a revision number in the nearby text field will select that revision.
After all appropriate options and fields are completed clicking the “OK” button will cause the checkout process to begin. The window that appears contains information on all files added to the working directory and the current revision of the repository checked out.
CLI
To checkout a repository using the Windows command prompt, simply type “svn checkout ‘path/to/repository'” in an open command prompt window after first changing your working path to the appropriate working copy directory.
C:\Documents and Settings\username>cd C:\WorkingCopy
C:\WorkingCopy>svn checkout http://svn.jonathanwagner.net/cape/
There is no fancy repository browser, but there is a way to view the directories and structure of the repository using the ‘ls’ command with Subversion.
C:\WorkingCopy>svn ls http://svn.jonathanwagner.net/cape/
Communications/
Documentation/
OBC/
Power/
C:\WorkingCopy>svn ls http://svn.jonathanwagner.net/cape/Communications/
Hardware/
Software/
C:\WorkingCopy>svn ls http://svn.jonathanwagner.net/cape/Communications/Software
branches/
tags/
trunk/
Another way to do this is to use the recursive swith, “-R” after the ls command.
C:\WorkingCopy>svn ls -R http://svn.jonathanwagner.net/cape/
Since this recursively enters each directory and subdirectory listing every file in the repository, often more data is generated by the command than can be displayed in the command prompt window. To remedy this pipe the data to the more command.
C:\WorkingCopy>svn ls -R http://svn.jonathanwagner.net/cape/ | more
Using “| more” at the end of the command will allow the output to be viewed one screenful at a time by pressing the space bar to scroll through the output. Once the full path of the directory needed is detemined running the “svn checkout” with that path will check out only the directory desired.
C:\WorkingCopy>svn checkout http://svn.jonathanwagner.net/cape/
If the working copy is to be stored somewhere other than the current working directory the path to that directory should be specified.
C:\>svn checkout http://svn.jonathanwagner.net/cape C:\WorkingCopy
Update
If a working copy of the repository already exists on the local machine, the repository does not need to be checked out again. Instead it only needs to be updated to the latest revision. One of the great things about Subversion is rather than storing a copy of each revision, it uses a database to store the file once with the addition of any revisions to that file. If only one line is changed in one file then only that one line has to be stored along with information about where that line belongs. This means when the local working copy of the repository is updated only the information about that one line in that one file needs to be downloading making the Subversion very bandwidth and time efficient.
TortoiseSVN
To update a repository using TortoiseSVN, right-click either the working copy directory icon or anywhere inside the working copy and select “SVN Update….” A window similar to one which appears when checking out a repository shows any changes made to the working copy and gives the revision number.
CLI
To update a working copy from the command prompt, type “svn update” inside the working copy directory.
C:\Documents and Settings\username>cd C:\WorkingCopy
C:\WorkingCopy>svn update
Commit
After making changes to the files or directories in within the local working copy of the repository those changes must be committed to the actual repository. This updates the revision of the repository and incorporates any changes made to the local working copy. Immediately after a commit, the repository will be an exact copy of the local working copy.
TortoiseSVN
Committing a change with TortoiseSVN is as simple as right-clicking the directory or file which has been modified and selecting the “SVN Commit…” menu item. Enter a concise but thorough description of the changes made in the “Message” field of the window which appears. This message will be printed in the log and is the easiest way to tell revisions apart. Make sure all files and repositories to be committed are selected in the lower half of the window and click the “OK” button. Enter a repository username and password to complete the commit action.
A file which is different from the original checked out version will have an exclamation mark over the icon. This indicates that the file is different and possibly should be committed. It is possible to see the differences between the original downloaded file and the modified version using the Diff command discussed below.
CLI
Using the command prompt to commit is similar to the update action. Simply type “svn commit” from within the local working copy directory.
C:\Documents and Settings\username>cd C:\WorkingCopy
C:\WorkingCopy>svn commit -m “Descriptive log message here.” –username username
Password for ‘username’ : ********
…
Changes described here
…
Committed revision 3
Add, Delete, Relocate, Rename
Occasionally a new directory or file will need to be added, deleted, moved or renamed in the repository. An example of this may be a new test procedure or software library. To add a file or directory to the repository it must first be created or copied into the local working copy. The file or directory is then added to the local working copy via the Subversion “Add” action and then the local working copy is committed. The other actions should be used sparingly but are needed sometimes.
TortoiseSVN
After the directories and/or files have been created and placed in the desired organizational structure, right-click the directory or file and select the “Add…” menu item under the “TortoiseSVN submenu. A dialog showing which directories and files were added. If an entire directory containing subdirectories and/or files is added all subdirectories and files will be added as well. A plus sign overlay will appear on the icons of all directories and files added. After an “Add” the local working copy must be committed for the repository to show the changes.
Delete, Relocate and Rename are accomplished the same way. Right-click on the file or directory to be deleted, moved or renamed and select the appropriate option under the “TortoiseSVN” submenu. A commit is needed after any of these actions.
CLI
After creating the directories or files in the working copy directory a “svn add blah” must be executed followed by a “svn commit” to commit the changes to the repository.
C:\WorkingCopy\Communications>mkdir Software
C:\WorkingCopy\Communications>svn add Software
or
C:\WorkingCopy\Communications>svn add C:\WorkingCopy\Communications\Software
A Software
C:\WorkingCopy\Communications>svn commit -m “Adding Communications/Software directory” –username username
Adding Software
Password for ‘username’ : ********
Committed revision 12
The syntax for deleting a file from the repository is the same as adding a file
C:\WorkingCopy\Communications>svn delete C:\WorkingCopy\Communications\Software
D Software
To rename a file the syntax is “svn rename OldName NewName” and “svn relocate OldPath NewPath” iis used to move a file or directory. After any of these actions a commit needs to be executed for the changes to take place in the repository.
Revert
Revert can be used to undo any changes to the local working copy since checkout. This can be handy when a mistake renders a piece of code to become inoperable. Simply reverting to the previous version restores a working copy to the local computer.
TortoiseSVN
The Revert option is available through the “TortoiseSVN” submenu under the normal right-click menu. The Revert option is only available when the local working copy is different from the one checked out earlier (i.e. there is a red exclamation point icon overlay).
CLI
To revert to the most recently checked out version using the command prompt, the command looks like “svn revert C:\path\to\directory” or if the current working directory is the appropriate directory “svn revert .” will accomplish the same.
C:\WorkingDirectory>svn revert C:\WorkingDirectory
or
C:\WorkingDirectory>svn revert .
Diff
Diff shows the differences between the current local copy and the last checked out copy. This is helpful for determining what changes have been made since the last checkout and whether those changes should be committed to the repository.
TortoiseSVN
TortoiseSVN automatically labels modified files through the use of icon overlays such as the exclamation mark overlay. To view the differences between the modified files and the original files, right-click on any of the files and select “Diff…” from the “TortoiseSVN” submenu. This will start TortoiseMerge, an application which is typically used for selectively merging differences between files, but in this case is used for simply showing the differences between two files. TortoiseMerge has a two-pane view with the original copy of the file in the left pane and the modified copy in the right pane by default. Each difference between the version is highlighted. The arrow icons in the toolbar are used to quickly jump to the next or previous difference.
CLI
Rather than a side-by-side comparison like TortoiseMerge, the CLI version shows each change inline placing a ‘+’ in front of every line added in the modified file and a ‘-‘ in front of every line removed. A changed line shows up as a removal of the old line and an addition of a new line. To execute a diff for a particular file type the command “svn diff filename” where “filename” is the path to the file.
C:\WorkingCopy\Communications\Software\trunk>svn diff comm.c
Index: comm.c
===================================================================
— comm.c (revision 8)
+++ comm.c (working copy)
@@ -1,5 +1,7 @@
#define DEBUG
+// a change for testing SVN
+
/**
* @mainpage CAPE1 Communications Firmware
*
To see all changes of all files leave off the file name.
C:\WorkingCopy\Communications\Software\trunk>svn diff
With either of these commands it is very likely that the amount of output will exceed what the command prompt will show. Therefore adding “| more” to either command is almost required for the output to be useful.
C:\WorkingCopy\Communications\Software\trunk>svn diff | more
Creating a Tag or Branch
When a tag or branch is needed the method for creating either is to create a copy of the trunk into a new directory within the tag or branches directory. The only difference between a tag and a branch is tags should never change and branches provide a method for working on a project in parallel with the main development without adverse effects. After executing the copy a commit is needed to finalize the creation of the branch or tag.
TortoiseSVN
To create a branch in TortoiseSVN right-click on the trunk folder of the project the tag is to be created from . Select the “Branch/Tag…” menu item from the TortoiseSVN submenu. The default URL for the branch or tag is the source of the working copy’s repository location. This must be changed to an appropriate name in the tags or branches directory. Since tags are usually created to signify versioned releases the new folder name will often be the name of the project followed by a version number (i.e. RFBoard_v3.0). Add a meaningful log entry in the given text field and check the “Switch working copy to tag/branch” check box if this a branch. Otherwise leave the check box unchecked and click the “OK” button to create the tag or branch.
Because the copy takes place on the repository server and not the local copy a “SVN Update…” is needed to update the local copy to reflect the new tag or branch. A tag is supposed to serve as a “snapshot” of the project and therefore remain unchanged. When working with a branch, only the branch should be checked out so that there is no chance of accidentally committing a change to the trunk.
CLI
The CLI way to create a tag or branch is to issue the command “svn copy” with the local directory to copy and the destination url for the repository as parameters. Follow it up with the “-m” option and a meaningful log entry.
C:\WorkingCopy\Power\Hardware>svn copy trunk http://svn.jonathanwagner.net/cape/Power/Hardware/tags/test -m “Testing”
Committed revision 16.
C:\WorkingCopy\Power\Hardware>svn update
A tags/test
Updated to revision 16.
CAPE Repository
The CAPE Subversion repository is a versioning system as well as a central location for design files. The repository also allows multiple people to work on the same files concurrently. The CAPE repository is available to the public for reading and is only modifiable by CAPE members with a username and password. There is also a web interface available at http://svn.jonathanwagner.net/cape/ where any file can be downloaded for viewing.
Organization
The CAPE repostiory is organized into five main directories: Communications, Documentation, Mechanical, OBC and Power. Those directories are further subdivided into categories such as Software, Hardware, TestProcedures, etc. Each bottom-level contains directories for branches, tags and the trunk. The trunk contains undated, unversioned (other than Subversions internal revisioning) working copies of documents, code, schematics or any other file. Versioned files are located in a version subdirectory of the appropriate tags directory (i.e. InterboardConnector-Rev2.3.doc is in the CAPE1/Documentation/InterboardConnector/tags/InterboardConnect-Rev2.3 directory). To explore the repository structure, visit http://svn.jonathanwagner.net/cape/
Maintaining the Repository
It is important to maintain the repository by adhering to the basic versioning control system layout. Always keep the latest working copy of a file in the appropriate trunk folder and only create tags when a new version number is appropriate. Anytime a commit or other change which requires a log message is made, make the message concise yet informative so that a quick glance at the log shows the history of the repository and its files. Ask questions if unsure about a procedure or the proper place to store a file or directory. Overall, try to keep the repository neat and easy to browse and work with.