5.4 Adding Projects

Once your repository is created and configured, all that remains is to begin using it. If you have a collection of existing data that is ready to be placed under version control, you will more than likely want to use the svn client program's import subcommand to accomplish that. Before doing this, though, you should carefully consider your long-term plans for the repository. In this section, we offer some advice on how to plan the layout of your repository, and how to arrange your data in that layout.

5.4.1 Choosing a Repository Layout

While Subversion allows you to move around versioned files and directories without any loss of information, doing so can still disrupt the workflow of those who access the repository often and come to expect things to be at certain locations. Try to peer into the future a bit; plan ahead before placing your data under version control. By laying out the contents of your repositories in an effective manner the first time, you can prevent a load of future headaches.

There are a few things to consider when setting up Subversion repositories. Let's assume that as repository administrator, you will be responsible for supporting the version control system for several projects. The first decision is whether to use a single repository for multiple projects, or to give each project its own repository, or some compromise of these two.

There are benefits to using a single repository for multiple projects, most obviously the lack of duplicated maintenance. A single repository means that there is one set of hook scripts, one thing to routinely back up, one thing to dump and load if Subversion releases an incompatible new version, and so on. Also, you can move data between projects easily, and without losing any historical versioning information.

The downside of using a single repository is that different projects may have different commit mailing lists or different authentication and authorization requirements. Also, remember that Subversion uses repository-global revision numbers. Some folks don't like the fact that even though no changes have been made to their project lately, the youngest revision number for the repository keeps climbing because other projects are actively adding new revisions.

A middle-ground approach can be taken, too. For example, projects can be grouped by how well they relate to each other. You could have a few repositories with a handful of projects in each repository. That way, projects that are likely to want to share data can do so easily, and as new revisions are added to the repository, at least the developers know that those new revisions are at least remotely related to everyone who uses that repository.

After deciding how to organize your projects with respect to repositories, you'll probably want to think about directory hierarchies in the repositories themselves. Because Subversion uses regular directory copies for branching and tagging (see Chapter 4), the Subversion community recommends that you choose a repository location for each project root the topmost directory that contains data related to that project and then create three subdirectories beneath that root: trunk, meaning the directory under which the main project development occurs; branches, which is a directory in which to create various named branches of the main development line; and tags, which is a directory of branches that are created, and perhaps destroyed, but never changed.

For example, your repository might look like:

/    calc/       trunk/       tags/       branches/    calendar/       trunk/       tags/       branches/    spreadsheet/       trunk/       tags/       branches/    ...

Note that it doesn't matter where in your repository each project root is located. If you have only one project per repository, the logical place to put each project root is at the root of that project's respective repository. If you have multiple projects, you might want to arrange them in groups inside the repository, perhaps putting projects with similar goals or shared code in the same subdirectory, or maybe just grouping them alphabetically. Such an arrangment might look like:

/    utils/       calc/          trunk/          tags/          branches/       calendar/          trunk/          tags/          branches/       ...    office/       spreadsheet/          trunk/          tags/          branches/       ...

Lay out your repository in whatever way you see fit. Subversion does not expect or enforce a layout schema in its eyes, a directory is a directory is a directory. Ultimately, you should choose the repository arrangement that meets the needs of the people who work on the projects that live there.

5.4.2 Creating the Layout and Importing Initial Data

After deciding how to arrange the projects in your repository, you'll probably want to actually populate the repository with that layout and with initial project data. There are a couple of ways to do this in Subversion. You could use the svn mkdir command (see Chapter 9) to create each directory in your skeletal repository layout, one by one. A quicker way to accomplish the same task is to use the svn import command (see Section 3.7.2). By first creating the layout in a temporary location on your drive, you can import the whole layout tree into the repository in a single commit:

$ mkdir tmpdir $ cd tmpdir $ mkdir projectA $ mkdir projectA/trunk $ mkdir projectA/branches $ mkdir projectA/tags $ mkdir projectB $ mkdir projectB/trunk $ mkdir projectB/branches $ mkdir projectB/tags ... $ svn import . file:///path/to/repos --message 'Initial repository layout' Adding         projectA Adding         projectA/trunk Adding         projectA/branches Adding         projectA/tags Adding         projectB Adding         projectB/trunk Adding         projectB/branches Adding         projectB/tags ... Committed revision 1. $ cd .. $ rm -rf tmpdir $

You can verify the results of the import by running the svn list command:

$ svn list --verbose file:///path/to/repos 1 harry May 08 21:48 projectA/ 1 harry May 08 21:48 projectB/ … $

Once you have your skeletal layout in place, you can begin importing actual project data into your repository, if any such data exists yet. Once again, there are several ways to do this. You could use the svn import command. You could check out a working copy from your new repository, move and arrange project data inside the working copy, and use the svn add and svn commit commands. But once we start talking about such things, we're no longer discussing repository administration. If you aren't already familiar with the svn client program, see Chapter 3.