These suggestions on using Subversion are taken from the book Version Control with Subversion. This is a simplified view of using Subversion, and I've included page/section references where the Subversion book addresses an issue more completely.
1. Choosing a repository layout scheme.
Before adding projects to the repository, it's worth choosing how you'd like to organize the repository layout. On the other hand, thanks to the ease of moving and renaming directories in Subversion, it's easy to rearrange things later. I'll recommend one simple layout taken directly from the Subversion book (see page 81: Choosing a Repository Layout).
This layout is based around tracking three aspects of each project:
- Trunk -- the 'main line' where active development is managed.
- Branches -- where a copy of the project can be managed without affecting the main line - useful for testing out big changes that may or may not be later integrated into the main line (see page 39: Branching and Merging).
- Releases (or tags) -- where snapshots (usually corresponding to an official release of the project) of the source tree are kept so that it can be restored, examined and rebuilt if needed (see page 51: Tags).
The following example demonstrates how this layout would work for two projects, ProjectA and ProjectB.
2. Importing a project into the repository.
ProjectA/ trunk/ ... project files ... branches/ CustomClientBuild ... project files ... releases/ v0.9b/ ... project files ... v1.0/ ... project files ... ProjectB/ trunk/ ... project files ... branches/ ... project files ... releases/ ... project files ...
So this is the big event -- actually taking one of your projects and adding it to the repository. Using the repository layout described above, here's how you would add ProjectWidget to the repository. (Note, the
svn importcommand and all arguments must be entered on the same line, the \ is used to indicate line continuation.)
% svn import -m "my import message" <path_to_project> \ http://<svn_server>:<apache2_port>/svn/<project_name>/trunk
% svn import -m "Importing project widget" \ ~/MyWorkArea/ProjectWidget \ http://localhost:8008/svn/ProjectWidget/trunk
By default, your Unix login/user name is used to choose the HTTP/Apache2 account associated with a change to repository. To specify another account use the --username <user> option.
Note that importing ~/MyWorkArea/ProjectWidget simply adds the project to the repository, the directory that the files were imported from is unaffected. To put the local directory under the control of Subversion you need to check it out first (see 3. Checking out a project).
If you are importing a project from CVS, you can preserve the full revision history of your project with cvs2svn.
3. Checking out a project.
To get access to a project that is in a Subversion repository, you need to check it out from the repository. (If you're checking out a project you just imported, move the original directory out of the way:
mv ProjectWidget ProjectWidget_preSVN).
Then check out the source from Subversion:
svn checkout http://localhost:8008/svn/ProjectWidget/trunk ProjectWidget
This will create a new ProjectWidget directory in the current working directory you issued the command from.
4. Managing your project with subversion.
For the most part Subversion just lets you work the way you normally would, but in some cases you need to directly inform Subversion of the change (adding, deleting, renaming), or when reconciling conflicting changes between your local copy and an updated version in the repository.
4.1 Checking the status.
From within the ProjectWidget directory, you can perform Subversion commands like
svn status to see if any of the files in the project have been changed locally, or
svn update to update files in your work area with anything newly added or modified in the repository.
To check if the status of files has changed both locally and/or in the repository, use
svn status ľu.
Files that are unchanged will not be mentioned at all - this list (extracted from the svn help status output) provides the basic codes for describing the status of a file:
'A' Added 'C' Conflicted 'D' Deleted 'G' Merged 'I' Ignored 'M' Modified 'R' Replaced 'X' item is unversioned, but is used by an externals definition '?' item is not under version control '!' item is missing (removed by non-svn command) or incomplete '~' versioned item obstructed by some item of a different kind
For example (after editing README.txt in ProjectWidget's top level directory):
% svn status M README.txt
4.2 Adding, deleting, and renaming files/directories.
When you add a new file or directory to your work area, use the command
svn add <file_or_dir> to let Subversion know that you've added it.
When you delete a file or directory from your work area, use the command
svn delete <file_or_dir> so that the repository is updated with the change.
When you want to rename a file or directory, use the command
svn rename <oldname> <newname>.