Note 1: this writeup mostly refers to Version 1 of Superversion, and some of the material may not apply to Version 2. Still, it should be useful as a gentle introduction to the concepts.
Note 2: this writeup has been salvaged from the PC days of this site. Sadly the screenshots did not make it through. I'll try to put some together at some point but for now I've removed the references to the graphics. Sorry!
A Note On Terminology
If you're familiar with other source configuration management (SCM) and version control systems (VCS), you probably recognize such terms as version, merging, etc. Superversion uses slightly different terminology in some cases, and so it's worth a quick look at terminology. Especially since I tend to alternate back and forth in this tutorial. :)
- Project: the collection of files that together are used to build the finished product.
- State (a.k.a. Version): a snapshot of the project as it existed at a given point in the development process.
- Work Area: the directory you use to work on your project. A project may have more than one work area. For instance, you might want to open up a second work area in order to fix a bug in an older release.
- Work Area State: the project state associated to the work area during the last update or commit. Version control systems usually remember which state this was to keep track of the changes you are making in the work area.
- Commit (a.k.a. Check-In): the process by which we accept the project's condition as it currently exists, and create a new State of the project based on said condition.
- Update State (a.k.a. Check-Out): the process by which a given State of the project is made the Work Area State.
- Branching: the process of "forking" (splitting) the project into different development paths, e.g. to test experimental features of the project without affecting the main, stable State.
- Merging: comparing two branches, resolving any conflicts, and ultimately combining them into a single State. In many ways the opposite of Branching.
Getting Started
To begin, if you haven't already, go and download the latest and greatest version of Superversion. As a Java application installation is simple (assuming you've already got a JRE); the easiest way to get started is to use Java Web Start. Feel free to ignore any security messages that pop up-it's just a warning to let you know that a web app (Superversion) is trying to gain I/O access to your local computer. But of course you should be expecting that access, considering you plan on handing over your source code to Superversion's care.
Since we don't have any projects yet defined, we'll start with that. Select 'New project...' and enter a name for your new project in the popup dialog box. Since Superversion is going to create a folder with this project name, make sure you limit yourself to using characters that can be part of a valid filename. We'll call our project Hello.
Now we have to define a work area for our project, a location where we'll do our editing--Superversion monitors this location, and reports on any file changes it finds. You can use any location you like; we'll use c:\source\hello\ as ours. If you use *BSD or Linux, feel free to substitute ~/src in your head. :)
And that's it for getting Superversion version control set up for our project. If you're coming from another SCM/VCS system, it might be a pleasant experience to have the initial system up and running so quickly. Now we have to populate our work area for the tutorial. Open your favourite text editor and write the ubiquitous 'Hello, World!' program (here I'm using C, feel free to substitute your own language of choice):
#include <stdlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
printf("Hello, world!\n");
return(0);
}
Now save the file as hello.c. If you now switch back to the Superversion window, you should see that your new masterpiece has not gone unnoticed: Superversion has noted the change in the file.
At this point we can check in our code. If you're new to version control, checking in the code acknowledges the changes we've made to a file, and puts the new version of the file into the Superversion project. To check in hello.c, right click on its filename and select Acknowledge and commit..., or highlight the file and press the double arrows in the upper right corner of the Work Area window. Go ahead and enter a brief description and comments on the particulars of this check in. You should notice then that the History Window now has some more detail to it.
Committing Changes
Now, let's put Superversion through its paces. Open hello.c in your favourite editor again, and change the code as follows:
#include <stdlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
printf("This is Hello! The Superversion tutorial program.\n");
printf("Hello, world!\n");
return(0);
}
Save the changes, and switch back to the Superversion screen. Superversion's noticed the changes in hello.c of course, and depending on your editor and whether it saves backup files or not, it may have also noticed the backup file as well by showing it as a new file in the work area.
Superversion's also noticed that this particular editor keeps a swap file. Since we aren't interested in keeping version information for backup files or swap files, we'll have Superversion ignore them. Right click on the file name and select Ignore.... The dialog that comes up offers several suggestions: ignore the hello.c~ specifically in this directory, ignore hello.c~ files in all directories, or ignore all .c~ in all directories. Here we'll ignore all .c~ files by double clicking **/*.c~ and clicking Add. You can repeat this process for all the files you want Superversion to ignore-generally speaking, you'll want to ignore most backup files, swap files, etc. Depending on your project, it may have other files to ignore. GNU GCC users will probably want to ignore **/*.o files; if you're developing Windows applications **/*.exe can be added to this list as well (UN*X developers will most likely want to ignore the final executable produced during compilation, e.g. hello binary files instead of **/*.exe). As another example, Python developers will probably want to ignore **/*.pyc files, and so on.
With that out of the way, we can go ahead and commit your changes to hello.c as you did before (Acknowledge and commit... or clicking on the double arrows), and add a new description and comment. But before that, let's take a look at the differences between the current version of hello.c and our previous version. Right click on the file, and select Show differences. A new window opens, and shows the previous and current versions of hello.c side-by-side, highlighting the differences between the two.
Now proceed with checking the new version of your killer app into the Hello repository, again with a brief description and comment. Superversion asks for confirmation to check the file in, click Ok to proceed. You'll also notice that the entry for hello.c allows you to insert a comment; a very handy feature to leave yourself file-specific notes. Your Project History window now shows even more detail, showing our path from version 1.2 to the current 1.3.
Although we won't cover all of Superversion's features in this quick tutorial, you should take the time to explore on your own. In particular, be sure to take a look at Superversion's Reconstruct feature for project states. Ever accidentally delete a file you really need? If it happens with a Superversion project, Reconstruct is your new best friend. :)
Branching
Now let's explore a useful feature found in most version control systems, branching. Branching is used to, well, branch off a version of your code from the main trunk. It's a useful feature to have for investigating experimental changes to your code that you don't want in your main codebase until you know they're ready. To begin, right click on the 1.2 circle in the Project History window and select Update work area to state..., or select it and press the left arrow in the upper right corner of the Project History window. Incidentally, this step also illustrates how you can check out previous versions of your project, an important feature of a version control system. Superversion will give you two chances to change your mind, answer in the affirmative for both dialogs to proceed. Now version 1.2 is our work state-you can confirm this if you like by right clicking on hello.c and selecting View file. If your editor of choice is still open, it might ask you if you want to load the new version of hello.c; if not, you should reload the file yourself. In either case, you'll recognize that we're now back to version 1.2 of the file. Change the code to read:
#include <stdlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
char *revision="$Revision$";
printf("This is Hello! %s.\n",revision);
printf("Hello, world!\n");
return(0);
}
And save the new version. Here we're demonstrating another Superversion feature, that of keywords. Superversion recognizes the $Revision$ comment in hello.c as a variable; in this case, a placeholder for the current revision number. Superversion will automatically update this variable with the current revision number with each commit; a useful feature if you need to keep track of versions of the final product. Now switch back to the Superversion screen, and Acknowledge and commit... as usual. Superversion warns you that proceeding will create a new branch of your project; go ahead and accept the new branch. Now our Project History has a little more horizontal activity to it-Superversion has recorded the new branch.
As of 1.0RC1, Superversion recognizes several other keywords that may be of interest. You can use them in exactly the same way as you used $Revision$. Here is the full list of keywords:
| $Revision$ | Current project's revision number |
| $RCSfile$ | Current file's name in the repository (not including path) |
| $Source$ | Current file's name in the repository (including path) |
| $Date$ | Date of current file's last (saved) modification in repository |
State Markers
Now that we have more than one version of our project, we can discuss one of the other important features Superversion has to offer. Depending on how you choose to structure your project, you may want to make use of Superversion's marker feature. Up until this point, we have mainly referred to specific versions of our project by their version numbers, e.g. 1.2, 1.3, etc. Sometimes it's useful to use a more descriptive term to describe the various states of our project.
For example, it's common for many projects to define three basic states: Stable for the latest released version of the project, Unstable for the most up-to-date version which has yet to be released, and Testing for the most experimental version. With state markers, you can label specific states of the project as Stable, Unstable, and Testing. Superversion makes this labelling fairly straightforward: from the Work Area menu, select Choose default marker... and a new dialog opens. From this dialog, you can define the state markers for your project: choose New marker... to define a new marker, and in the new dialog that appears enter a name for your new project marker and a state to be bound to the marker.
As your project progresses, you can use the same dialog of Figure 11 to move your markers to follow your project. Superversion will also optionally progress markers for you automatically: when you check in a new version of your project from a work state with a marker, for example, Superversion will automatically move the marker to the new work state if you check the corresponding checkbox in the Commit dialog.
Merging
Development can continue in both branches, switching back and forth as we like. Each branch can itself be branched as well, but for this tutorial let's assume we're satisfied with our new branch and want to merge it back into the main trunk. You might want to merge your Unstable branch into your Stable, for example, once you're satisfied with Unstable's stability.
Merging can be a fairly complicated process for a version control system to carry out for complex projects or if the branches differ significantly, but in this simple example it won't be very taxing to Superversion. To begin, let's illustrate how we jump back and forth between branches: in this case, let's move back to our main trunk by right clicking on version 1.3 in the Project History window and selecting Update work area to state..., or by selecting version 1.3 and pressing the left arrow in the upper right corner of the Project History window. As before, Superversion will ask us if we really want to switch branches, and we'll answer in the affirmative.
Let's now assume that you're finished with your efforts in the 2.1 branch-let's see how to merge the 2.1 branch into our main 1.3 trunk: select the 2.1 branch (left click on 2.1), and from the History menu, select Merge state into work area.... To merge the two branches, Superversion needs a reference state, a place in our project's history where it can compare how the two branches diverge and how to bring them back together. A new window will pop up asking you to choose this state: generally speaking, a good choice is to use the version where the branching occurs, and in fact that's the suggestion Superversion makes to you. In our case, Superversion suggests using version 1.2 as our reference state.
Once we give the go-ahead to merge, Superversion warns us that we'll have conflicts between versions of hello.c if we proceed; we'd expect this to be true in the case of branches so it isn't anything to be concerned about. In our simple example, Superversion is able to help us resolve the conflicts automatically; in more complex merges, we might have to make a backup of the file, delete it, and attempt to resolve the conflicts ourselves. Tools such as diff and patch in UN*X platforms are useful here; Windows users might be interested in the WinMerge utility as well. Here, Superversion is able to help us and offers to add markers to the hello.c file to indicate where the differences are and how to resolve them. When we select Update anyway, Superversion reports back that no additional actions are necessary. When we look at the hello.c file in our favourite editor again, it now looks like this:
#include <stdlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
printf("This is Hello! The Superversion tutorial program.\n");
printf("Hello, world!\n");
return(0);
}
Superversion automatically resolved the differences between the two versions, and more or less kept the original 1.3 version of hello.c intact. Granted, maybe not the best example of merging, but it did illustrate how to do it, didn't it? :)
Exporting
We have one more thing to demonstrate in this tutorial. From the Project History window, right click on your favourite version of the project, and select Export state.... Superversion brings up a dialog box asking where and under what name to export this state-a ZIP archive containing all the files of the project as they were under the version you selected. Choose a location to save the file, and if you prefer, change the name of the ZIP file. Superversion defaults to naming it based on the date and time this particular state was recorded, but of course you can name it anything you like. Now if you open the ZIP file, it should have a copy of the hello.c file as it existed in that state. Very useful feature if for example you want to share the most recent versions of your projects, or for your own archival purposes.
And that's it! There's a lot more to Superversion than we've covered in this tutorial, and as we mentioned as a work in progress it will have new features added all the time. Hopefully this tutorial explored enough of the basics to help you get started using Superversion, and mastering it on your own. Be sure to visit the Superversion website often to keep up on the latest and greatest, and of course feel free to ask any questions on the Superversion mailing list.