Subversion Perversions

I normally work alone. Creating a web project from start to finish in a completely self-contained manner. If I make a mistake, then it's my problem. However, I am just starting a new project, with another developer. So already my previous working model is out of sync, it should read, "we are starting a project". See the difference? Our project is also my first Ruby on Rails Web App, so it is vital that my noobie mistakes don't rock our team boat too greatly. Already even the way I approach the venture is different. My iron fist needs to unclench and open up like a lotus flower to welcome my new collaborator warmly. So that our sparks of creativity, will flow freely and easily. We need to allow a creative exchange that allows us both to express ourselves in harmony. So, how do we do it, how can we create and manage this collaborative utopia?

Subversion

Well in the first example of the benefits of working as a team, my co-worker suggested we use Subversion, a magical "time machine" to harness and direct our creativity without damping or stifling our efforts. Once set up, Subversion will be the conduit that tracks and controls our work. Allowing me to make mistakes, but then swap back to any previous untainted revision. If I had a bad day on Tuesday, I can start again from Monday's version.

Subversion Concepts

What follows are some notes, that I have scavenged from the online Subversion Manual. Just pointers to the concepts and terminology used by the open source version control system, that will hopefully help lead me safely in my first tentative steps with Subversion. If you too are just starting out with Subversion, I hope you find them useful, but be warned, I have no real idea where this is going to take me. So if you are feeling brave, floor your Delorean and brace yourself as we hit the critical 88mph.

Subversion, the book

I am getting to grips with Subversion using the online book.. So, my first suggestion is to download it and get reading. Seems like a good place to start.

The Repositry

This is the hub of the project, this is the databank where all your work is deposited and maintained. Files are checked in and out of here. Kept magicaly in sync by Subversion

Check out

This is process of grabbing a set of files from your central Repositry and "checking them out" to your local working copy. i.e: $ svn checkout http://svn.example.com/repos/calc

Commit/ Checking in

The act of publishing your changes is known as committing (or checking in) changes to the repository. i.e: $ svn commit
button.c -m "Fixed a typo in button.c."

Update

So how does my partner, update their working copy with my changes? By using the "update" command, they can update their working copy to the same state as my last commit. $ svn update
U button.c
Updated to revision 57.

Revisions

From the manual: "An svn commit operation publishes changes to any number of files and directories as a single atomic transaction. In your working copy, you can change files' contents, create, delete, re-name and copy files and directories, and then commit a complete set of changes as an atomic transaction. By 'atomic transaction', we mean simply this: either all of the changes happen in the repository, or none of them happen." And: "Each time the repository accepts a commit, this creates a new state of the filesystem tree, called a revision. Each revision is assigned a unique natural number, one greater than the number of the previous revision. The initial revision of a freshly created repository is numbered zero, and consists of nothing but an empty root directory."

The Four States

By talking to the repository, Subversion can tell which of the following four states a working file is in:

1. Unchanged, and current The file is unchanged in the working directory, and no changes to that file have been committed to the repository since its working revision. An svn commit of the file will do nothing, and an svn update of the file will do nothing.
2. Locally changed, and current The file has been changed in the working directory, and no changes to that file have been committed to the repository since you last updated. There are local changes that have not been committed to the repository, thus an svn commit of the file will succeed in publishing your changes, and an svn update of the file will do nothing.
3. Unchanged, and out-of-date The file has not been changed in the working directory, but it has been changed in the repository. The file should eventually be updated, to make it current with the latest public revision. An svn commit of the file will do nothing, and an svn update of the file will fold the latest changes into your working copy.
4. Locally changed, and out-of-date The file has been changed both in the working directory, and in the repository. An svn commit of the file will fail with an “out-of-date” error. The file should be updated first; an svn update command will attempt to merge the public changes with the local changes. If Subversion can't complete the merge in a plausible way automatically, it leaves it to the user to resolve the conflict.

Getting Data into your Repository

From the manual: "There are two ways to get new files into your Subversion repository: svn import and svn add."

Import

"The svn import command is a quick way to copy an unversioned tree of files into a repository, creating intermediate directories as necessary. svn import doesn't require a working copy, and your files are immediately committed to the repository. This is typically used when you have an existing tree of files that you want to begin tracking in your Subversion repository. For example:" $ svnadmin create /usr/local/svn/newrepos $ svn import mytree file:///usr/local/svn/newrepos/some/project \ Note that after the import is finished, the original tree is not converted into a working copy. To start working, you still need to svn checkout a fresh working copy of the tree.

Recommended Repositry Layout

It is recommend that one creates a:

1. trunk directory to hold the 'main line' of development.
2. branches directory to contain branch copies.
3. tags directory to contain tag copies.

example:
$ svn list file:///usr/local/svn/repos
/trunk
/branches
/tags

Important Note

This looks like being an important point to bear in mind: "You must tell Subversion about everything else that you do. For example, if you want to copy or move an item in a working copy, you should use svn copy or svn move instead of the copy and move commands provided by your operating system."

Basic Work Cycle

• Update your working copy svn update
Make changes svn add svn delete svn copy svn move
• Examine your changes svn status svn diff
• Possibly undo some changes svn revert
• Resolve Conflicts (Merge Others' Changes) svn update svn resolved
• Commit your changes svn commit

Status

Apparently the most frequently used Subversion command is status: "svn status will give you all the information you need regarding what has changed in your working copy-without accessing the repository or potentially incorporating new changes published by other users." When you run the command, you get a list of the changes, and each line is given a letter to denote the state of the change:

• A - The file, directory, or symbolic link item has been scheduled for addition into the repository.
• C - The file item is in a state of conflict. That is, changes received from the server during an update overlap with local changes that you have in your working copy. You must resolve this conflict before committing your changes to the repository.
• D - The file, directory, or symbolic link item has been scheduled for deletion from the repository.
• M - The contents of the file item have been modified.

Dealing with Conflicts

Do one of three things:

1. Merge the conflicted text 'by hand' (by examining and editing the conflict markers within the file).
2. Copy one of the temporary files on top of your working file.
3. Run svn revert to throw away all of your local changes.

Once resolved, let Subversion know by running svn resolved

Commit Your Changes

Finally! Your edits are finished, you've merged all changes from the server, and you're ready to commit your changes to the repository. The svn commit command sends all of your changes to the repository. When you commit a change, you need to supply a log message, describing your change. Your log message will be attached to the new revision you create. If your log message is brief, you may wish to supply it on the command line using the --message (or -m) switch: $ svn commit -m "Corrected number of cheese slices." Sending sandwich.txt Transmitting file data . Committed revision 3.

Conclusion

The above concepts all come from the online manual, and now I understand a little of the theory, I am ready to practice Subversion. As I develop on a Mac, I decided my first task is to download a copy of SVNx, which is Subversion with a GUI, and built for Mac OS X. I'll post back with my experience of using SVNx at a later time.