Using Trac and Subversion

This page gives a quick guide on the basics of using both Trac and SVN. SVN use is given first since the first task that will be performed is probably importing source data; Adding bug/enhancement tickets via Trac will come later. Windows users should consider using TortiseSVN, an SVN client that integrates with Windows Explorer. Another option is Synchro SVN Client, a GUI based SVN client that is available for Windows, Mac OS X, and Linux. For those who prefer to use the command line interface, the instructions below are for you.

In all instructions below, "/path/to/working/copy" should be replaced with the actual directory containing the current working directory, "yoursvnsite" is the URL of the server, and "theproject" should be changed to the path to the project.

Importing Initial Source Code

The initial import is performed as follows:

svn import /path/to/working/copy https://yoursvnsite/svn/theproject

NOTE: SVN will add every single file, first clean your project to remove all files that should not be included (e.g., execute "make clean" if using GCC makefiles).

Checking Out Source Code from the Repository

To obtain a fresh copy of the code from the SVN repository, execute the following command:

svn checkout https://yoursvnsite/svn/theproject

Updating to the Latest Revision

If another developer has committed changes to the repository, it is necessary to update the local working copy to incorporate the latest changes. Simply enter:

svn update

This update will merge the latest revision with your local changes. Occasionally there may be conflicts (e.g., two people modify the same code). If so, SVN will provide a warning, and it will be necessary to examine the files containing conflicts and resolve them, typically by selecting the correct code, and deleting the other version from the source file.

Adding/Deleting Source Files to/from the Repository

Files are not automatically added to the repository when they are created. This is because it is pointless to track revisions of object files, which typeically also reside in the same directory. To add a file/directory to the repository:

svn add <filename>

to delete a file/directory:

svn delete <filename>

NOTE: Calling svn delete will delete the actual file too

Committing Source Code to the Repository

Once work has been done on the source code that needs to be preserved, it is time to commit the changes to the repository. This is achieved as follows:

svn commit -m "<message regarding thechanges for this revision"

If the "-m" option is left out, SVN will open a text editor that will allow a more extensive message to be written for the revision.

Examining Source-Code History

Trac provides a very easy to use interface to the source code, the revisions, and the differences between the revisions. These are available via the "timeline" and "browse source" pages (e.g., visit https://yourtracsite/projects/theproject/timeline).

Reverting to an Older Source Revision

Occasionally someone may screw up an older revision, and it is necessary to revert to an older revision of the source code. This is exactly the kind of task that SVN is designed to do. There are several possible scenarios:

Using Trac

Since Trac is web based, and has a fairly intuitive user interface, there is no need to explain how to use it in detail. The timeline page lists the latest revisions to both the code and the Trac pages. Bugs/enhancements are posted as tickets. Tickets can be assigned to a "milestone" (i.e., future version of the program). The road map page lists the milestones whilst the wiki pages can be used for documentation. Finally, the browse source page provides a very easy method to browse the source code.

Exactly which parts of Trac are used is a matter of personal taste. Personally, I find that I do not use the wiki pages much for personal projects, but the other features are extensively used. I also create tickets for bugs that someone (including me) finds that cannot be solved immediately.

Recommendations

Here are a list of recommendations: