This article explains how to create projects and repositories in a free, open source version control system called Subversion. The online documentation for Subversion is excellent, but the information found here may help people who are still getting up to speed with the product. I will assume that you have already installed Subversion and TortoiseSVN.
I run Subversion on a Linux box, but frequently use it from Windows. However, in this article I will describe how to create both the repository and your projects while running on Windows or on Linux. In general, any commands you give from the command line will work on both Wndows and Linux, while the commands you give from inside TortoiseSVN will work only on Windows. This is not a shortcoming in TortoiseSVN, but simply reflects the fact that TortoiseSVN is a Windows only tool which runs as a shell extension to the Windows Explorer.
If you want to learn both how to create a repository, and how to create a project in the repository, then read this whole article. If your repository already exists, and all you want to do is create a project inside the repository, then please skip ahead to the section of this article on adding projects to a repository. There you will learn about the trunk, tag and branch directories and why they should be part of all Subversion projects.
This article also describes the svn, svnadmin and svnserve command line programs that ship with the default installation of Subversion. If you are running on Linux or if the Subversion\bin directory is on your path, you should have no trouble running these programs from the command line. I discuss none of the programs in detail, but the context in which they are discussed in this article should make their purpose clear to you. In particular, if you want to access Subversion from the client side, then you should be sure to read carefully the sections of this text that describe the svn program. The other two programs are server side tools.
Creating the Repository
Repositories are created by a user who has direct access to the server. If you are using Windows as a server, then the simplest way to create the repository is with TortoiseSVN. Open the Windows Explorer, browse to the place where you want to create the repository. Use the explorer to create the directory where you repository will reside. Right click on the new directory and choose TortoiseSVN | Create repository here. The Create Repository dialog will appear, as shown in Figure 1. Select the default Native FileSystem (FSFS) option and click the OK button. The repository will be automatically created.
Figure 1: Choose the Native file system for best performance. If you like working with databases, then you can choose Berkeley DB.
If you want to create the repository from the command line on Windows, simply type something similar to the following:
svnadmin create c:\MyRepository
This command will first create the directory called MyRepository, and then set it up properly as a Subversion repository. On Linux, you might issue this command:
svnadmin create /usr/local/repository
Regardless of whether you created the repository with TortoiseSVN or with svnadmin, the end result is a directory with the following structure:
10/26/2005 15:39 <DIR> conf
10/26/2005 15:39 <DIR> dav
10/26/2005 15:39 <DIR> db
10/26/2005 15:39 <DIR> hooks
10/26/2005 15:39 <DIR> locks
10/26/2005 15:39 2 format
10/26/2005 15:39 388 README.txt
To start the Subversion service running on your machine, go to any directory on the drive on which you created the repository, and type svnserve -d. For instance, if you created your repository on the C drive, then move to any directory on the C drive, and type svnserve -d. It might make a certain sense to start svnserve from inside your repository, but that is not necessary.
Now go to another machine and try to access your repository. Assuming you created your repository in C:\MyRepository, then you might type something like this:
svn info svn://MyServer/MyRepository
If you created your repository in the D:\Temp\Info\MyRepository directory, then you would start svnserve on the D drive, and type something like this:
svn info svn://MyServer/Temp/Info/MyRepository
The point is that svnserve will look on the drive in which it is started for your repository. There is no need to specify a drive letter. In fact, I have never had any luck trying to pass drive information via svn. Instead, I just start svnserve on the appropriate drive, and then assume the path to the repository automatically references the relavant drive. Needless to say, all this talk about drives is not relevant if you are running the server on Linux.
The result of the svn info command should be something at least vaguely like the following:
[D:\temp\Tort2]svn info svn://rohan/usr/local/repository/CodeFez
Repository Root: svn://rohan/usr/local/repository
Repository UUID: b062d7d2-2303-0410-96a2-dd3f728f4100
Node Kind: directory
Last Changed Author: Charlie
Last Changed Rev: 13
Last Changed Date: 2005-10-16 16:28:59 -0700 (Sun, 16 Oct 2005)
If you get an error when you run svn info, then it is possible that your firewall is blocking port 3690. If you are using the standard Windows built in firewall, then the install of Subversion should have opened up the port for you. However, if you have an external firewall, then you may need to punch a hole in it.
NOTE: If the info command returns absolutely nothing, then the repostory is probably fine. Subversion is simply saying that there is nothing to report. Had there been an error to report, it would have been reported. If you are querying a repository that already has at least one project in it, you can try issueing the list command instead. If there is something in your repository, then you should get a list of the contents. In general, however, Subversion is a well behaved Linux application that returns nothing if everything is okay, and an error message if there is a problem. Immediately after you create a respository, however, you should get a listing like the one shown above.
At this stage, you should have your repository set up correctly and you should be able to access it. The next step will be to set up permissions in your repository.
Setting up Permissions in Your Repository
By default, you will be able to read your repository, but not write to it. Here are the steps necessary to give password protected, read or write access to your repository. In the conf directory of your repository, you will find a file called svnserve.conf. You should edit this file so that it looks like this:
anon-access = read
auth-access = write
password-db = users
realm = My First Repository
The actual file on your drive will have some comments demarcated by ### signs. I have omitted those comments here so as to make it easy for you to see the important parts of this file. In your version of the file, you will want to keep the comments, as they are useful. But be sure to remove the comments in front of the lines shown above.
NOTE: Change anon-access=read to auth-access=read if you want the user to have to sign in before reading from the repository. Otherwise, anyone will be able to read from the repository, but only those with proper rights will be able to write to it.
The next to the last line in svnserve.conf looks like this:
password-db = users
This line represents a contract with Subversion in which you promise to create a file called users, placed in the conf directory, with the following format:
user1 = foobar
user2 = foobar
The name of the subversion user is on the left, and the password for the user is on the right. When you attempt to write to this subversion repository, you will automatically be prompted for a user name and password. In this case, if you entered user1 as the name, and foobar as the password, then you would be granted permission to write to the repository.
Adding Projects: Branches, Tags and Trunk.
Subversion supports advanced version control features called branching and tagging. In this article, I will not have room to explain the simple steps for branching or tagging your source in Subversion. Nevertheless, I will take a moment to make sure you understand what a branch is, and what it means to tag a version of your source.
- Tagging: You might tag your project when you reach Version 1.0. Then you can go on making changes to your project, but if you need to get back to Version 1.0, you can always use the tagged version of your project to retrieve all the source files exactly as they looked when your reached Version 1.0.
- Branching: If you are working on a project, and want to try some experiments, but you aren’t sure you want to keep them, then you can branch the project. After branching, you will have two copies of your project: the main trunk, and the branched version. Work can then continue on both the main trunk, and the branch. Changes to the branch will not be seen in the main trunk, and changes to the trunk will not appear in the branch. Both branches of the code will have acecss to any changes that occurred before the project was branched. As I will explain below, branching is handled in a way to insure that only a minimum amount of server side disk space will be used.
Now that you understand branching and tagging, you are ready to create a project. Here are the basic steps to add a project to a repository when working from the command line:
$ mkdir MyProject
$ mkdir MyProject/trunk
$ mkdir MyProject/branches
$ mkdir MyProject/tags
svn import MyProject svn://rohan/usr/local/repository/MyProject -m "info"
As you can see, you create three directories under your main project branch. These directories are called branches, trunk and tags. You then create the repository itself by issuing the svn command shown in the last line.
svn import MyProject svn://rohan/usr/local/repository/MyProject -m "info"
The last bit of this code, that reads -m "info," is simply a place for you to enter a comment that will be recorded in the log. If you don’t provide this information, then Subversion will prompt you to load an editor and write a comment inside of it. I definitely prefer to add the -m command to my import statements so as to avoid any unnecessary fuss with an editor.
It is nearly as simple to create a project using TortoiseSVN as it is to create it from the command line. First open up the Windows Explorer. Now create an empty directory. Give the directory the name of your project, such as MyProject. Inside the directory create three subdirectories called trunk, branches and tags. Now select the MyProject directory, right click, and choose TortoiseSVN/Import from the menu. A dialog like the one shown in Figure 2 will appear. In this dialog, type in the URL of the project you want to create in the repository. Add a message that explains something about your import. This last step parallels the -m "info" portion of the command line import statement shown above.
Figure 2: Importing a project into the repository using TortoiseSVN. Specify the complete URL where you want to place the repository, and add a brief comment in the Message section.
In the URL section, I have included both the path to the repository, and the name of the project that I want to create in the repository. Don’t be fooled into thinking that because you right-clicked on the name of directory you wanted to import, that a directory of that name will be created for you automatically. Instead, specify the name of the project in the URL.
NOTE: In the examples I show, I prefer to put the name of the repository in the URL. However, you could also create a series of nested directories, and end up with much the same result. In short, there is more than one way to achieve the result shown here. It seems to me that neither technique is perfect, but the one shown here is most intuitive to me. In any case, if you don’t like the structure you created in the repository, just delete those directories and try again. It is easy to delete directories in the repository browser, shown in Figure 3. Later in this article I will describe how to launch the Repository Browser.
When you are done with your import, the repository should have a structure that looks like the image shown in Figure 3.
Figure 3: Viewing the structure of your project in the repository. I will show you how to pop up this dialog later in this article.
Don’t put the files directly in the MyProject directory, instead them in MyProject/trunk:
If you want to branch or tag your project, then you will use the directories called branches or tags:
NOTE: Subversion makes a "light" copy for the branched and tagged versions of your source. It doesn’t really copy all the files, it only copies the changes to the branches directory. So that keeps the repository small. From the client point of view, however, it appears that the branches and tags directories contain full copies of your project.
Checking Files into the Repository
You now have access to both a repository and a project. Unfortunately, your project is currently empty, and contains no files.
To put files in your project, you need to take a step which is somewhat counter-intuitive: you need to check out the project that you just created. The MyProject directory that you created in the previous section is no longer useful. To get your hands on blessed, completely approved, and fully loaded Subversion directory, you need to check it out from your repository.
From the command line, navigate to the place in your system where you want to place your project. For instance, if you want the project to be in C:\Src\MyProject, then you should navigage to C:\Src. Now type the following command:
svn co svn://rohan/usr/local/repository/MyProject
The project will be checked out into the C:\Src\MyProject directory.
If you prefer to work from TortoiseSVN, the process is equally straightforward. If you want your project to be in D:\temp\MyProject, then use the Windows Explorer to navigate to D:\temp. Right click on the temp directory, and choose SVN checkout. A dialog will appear, as shown in Figure 4. Fill in the URL of your repository: svn://rohan/usr/local/repository/MyProject.Also fill in the name of the directory where you want the project to reside.
Figure 4: Checking out from the repository. But the URL of the project you want to check out on top, and the directory where you want the project to reside beneath it.
When you are done, you should have directory called C:\Src\MyProject that contains three subdirectories called tags, branches and trunk.
To copy files into your repository, either create the files one by one in the c:\Src\MyProject\trunk directory, or else copy the whole source tree of an existing project into the trunk directory. You are now ready to check your source files into the repository.
Suppose you added a complex directory called dbo that had many subdirectories to your c:\Src\MyProject\trunk directory. From the command line, navigate to the C:\Src\MyProject\trunk directory and issue the following command:
C:\SrcMyProject\trunk]svn add dbo
NOTE: In the command shown here, you no longer need to specify the path to your directory when calling svn. The information about the path to your server and your repository is kept in a series of hidden directories inside your project called .svn. You need not concern yourself with those directory in most cases. But if you want to explore them, just go the command line, enter a directory of your project, and type cd .svn. You will find yourself in a directory where the information about your subversion repository is stored in a series of files and directories.
After add the files to the repository, you need to commit your work:
[C:\Src\MyProject\trunk]svn commit -m ""
Now the dbo directory, and all the files in it, will be added to your repository.
You can also add files to a repository from inside the Windows Explorer by navigating to the C:\Src\MyProject\trunk directory and right clicking on the dbo directory. Choose TortoiseSVN/Add from the pop up menu. The dialog shown in Figure 5 will appear. You can check or uncheck the files listed in this dialog depending on whether or not you actually want to place them in the repository. When you have things set up they way you want, click the OK button.
Figure 5: Adding files to the repository using TortoiseSVN.
After adding the files to the repository, right click again in the Windows Explorer and choose SVN commit. The dialog shown in Figure 6 will appear.
Figure 6: The commit dialog prompts you for a short string that will be added to the repository as a log message. In the lower window you can specify which files you wish to commit by ensuring that there is a check mark before them.
You now know two ways to add files or directory trees to your repository. It probably comes as no surprise to learn you could have added files during the initial import process described in the previous section. However, I wanted to show you the process of adding files to a repository after you had created a project.
If you make any changes to the files that you have added to the repository, then they will have a little red icon next to their name in the Windows Explorer. Just choose SVN Commit from TortoiseSVN to post your changes. Choose SVN Update from TortoiseSVN to check files out of the the repository that may have been changed by other users. Needless to say, the command line versions of these commands are svn commit and svn update. More details on managing files that are part of a repository will be explained in future articles. But these simple commands should be enough to get you up and running.
You now know how to create a repository, add a project to it, and how to add one or more files to the project in your repository. In the final section of this article. I will add a few useful tips, most of which concern viewing the files in your repository.
Viewing the Repository, A Comment on the Repository
To view your repository and its projects, use the list command:
[D:\]svn list svn://rohan/usr/local/repository/trunk/MyProject32trunk
Here we see the listing of the MyProject2/trunk directory. As you can see, it contains one directory, called dbo. If you do the same thing in TortoiseSVN, you get a somewhat clearer view of what is going on. Select the directory on your system that you want to browse in the repository. Right click and choose TortoiseSVN/Repo-Browser, the dialog shown in Figure 7 appears.
Figure 7. The TortoiseSVN/Repo-Browser option gives you good view of your repository and its contents.
In the image shown in Figure 7, you can see the URL input control at the top of the dialog. In this case, the information in this control was filled in automatically because I picked a directory on my system that was checked out from a Subversion repository. Had I just brought up the browser from a random location on my harddrive, I probably would have had to type in the URL, or else pick it from the drop down list.
I want to end by explaining one peculiarity of Subversion. Each time the repository is changed, the version number of all the files in the repository is updated. In other words, the version number of your project as a whole gets updated, not just the version number of a particular file. This behavior is a bit odd, but there is at least some form of reason behind it. In a project, if one source file changes, it can affect the whole project. So the version number of the whole project is updated if even one file changes. For detailed information about the history of a particular file, right click on it in TortoiseSVN, and choose TortoiseSVN | Revision Graph.
Here is quote from the TortoiseSVN manual: "For unrelated projects you may prefer to use separate repositories. When you commit changes, it is the revision number of the whole repository which changes, not the revision number of the project. Having two unrelated projects share a repository can mean large gaps in the revision numbers. The Subversion and TortoiseSVN projects appear at the same host address, but are completely separate repositories allowing independent development, and no confusion over build numbers."
In this article you have had a chance to see how Subversion works. You have learned how to create repositories, how to create projects, how to check in code, and how to view the code you have checked in. I also briefly discussed updating files that have been changed. I have tried to lay things out here as clearly as possible, if you have more questions, the docs give a good overview of these subjects and provide more detail than I give here. In future articles I will discuss subjects such as branching and tagging, as well as techniques for updating your source and running diff operations on files that have been changed by two users.
Subversion is an excellent version control system that provides all the tools that most programmers will need to manage their code. This article hopefully gives you enough information to get over some of the initial hurtles that can confuse new users.