Code || Theory

Here's something I wrote up at work to start getting people up to speed on subversion. It's very basic, but you have to start somewhere.

With many people editing a site, it can be easy to lose track of who is editing what and what version of each file is in any given place. Let's imagine that we have a live site and a testing site which are both checked in to svn (subversion). We'll also imagine three developers, A, B, and C.

The live and test sites start out completely in sync with the repository.
A makes a change to live/index.php
B makes a change to test/monkey.php

Now, A should have made the change in test/index.php, tested it, and then pushed the changes to the live site, but perhaps it was a real emergency, so we can overlook it. More importantly, C has come along and wants to know if test/ is up to date. C can do an "svn status" to check.

test $ svn status
M monkey.php

The "M" stands for "modified." Here's a cheat sheet: http://knaddison.com/sites/knaddison.com/files/svn_codes.png

So, C does an "svn update"

test $ svn update
M monkey.php

However, C hasn't gotten the changes from the live site. This is A's fault. If A edits a file on the live site (surely only in an emergency), then A should check those changes in.

live $ svn commit index.php

An editor should open giving A the chance to explain their changes. A, being a thorough developer, types out a clear explanation.
"Fixed the spelling of our product name in the header."

Oh, I can see why we'd want that changed right away.

Now, A or C can go back to test and do an svn update to get the changes from the live server. No copying or backups are needed.

test $ svn update index.php

It's worth noting here that index.php was specifically updated. You can also do an svn update and get the updates for all of the subdirectories and their files.

What about monkey.php? Did that just get overwritten? No! Subversion will do its best to resolve simple conflicts. monkey.php was not changed on the live server, so there are no changes to merge back into the test server. Let's imagine that more development is going on, and C changes monkey.php on the live site. In this instance, it was not an emergency, so C's manager should yell at C for not following procedures -- but it isn't the end of the world. Lots of places work this way, and while they are not making the best use of svn, they are at an advantage to the same situation without svn. C can at least recover.

live $ svn commit monkey.php

In the editor, C gives the following reason for their edit: "Added blink tag to body text." Wow, C, really? C should be in extra trouble for that. Now let's go to the test site:

test $ svn update monkey.php
OMGWTFBBQLOLCANHASCONFLICTS!

That's not the actual error message. The actual error message is more subtle:

test $ svn update monkey.php
C monkey.php

C is for conflict, it's good enough for me. There are also some new files in test/ now:

monkey.php.mine
monkey.php.r30
monkey.php.r31

So, you've got all you need to figure out what happened. You can also just edit monkey.php and see what the conflict looks like. It will look something like this, except with version numbers interspersed.

<<<<<<<
<blink>We are awesome!</blink>
====
<marquee>We are awesome!</marquee>
>>>>>>> .r4040

Obviously, the blink tag is superior to the marquee tag, so C removes the other line and all of svn's conflict junk, leaving just the finished product. It's a good thing that this was done on test/ and not live/, since the extra angle brackets break html and/or php. With it fixed, C can do this:

test $ svn resolve monkey.php

and then

test $ svn commit monkey.php

Assuming that there were other changes, they should now be checked in.

== Some questions and answers ==

Whew, that's a lot of stuff to digest!
Can't A and B just make C do all the work, getting everything checked in and out in all the right places? Yes and no. They are the only ones who know what they have changed.

Should I make backups before making changes? No, you probably shouldn't, and if you do, they should *not* be in svn-controlled directories.

Can I put my log files right there in the svn controlled directory? You can, but you shouldn't. For one thing, we're svn controlling the web root, and you shouldn't put your log files in the web root. Just don't do it. Beyond that, it is possible to ignore files based on filename patterns, but those patterns require maintenance.

Is svn magic? No. It won't do things for you.

Can we make our live site off limits to users so that they can only edit the test site and then push their changes to the live site? Yes! We sure can, but first we have to make the live site amenable to that style of management. That means that our team has to first manage its own changes in a professional, responsible way. We are all responsible for committing our own changes to svn and generally cleaning up the cruft that has been collecting on our customer-facing web sites for years.

That means finding a new home adhoc and regular log files, ad hoc backups, and temp files. Every change on live and test need to be checked in atomically, and we need to make use of svn's tools for manipulating files. "svn rm" and "svn mv" allow svn to make the same changes to files on the live and test servers and track those changes for us.

WHERE IS THE SVN MAGICK YOU PROMISED?!?!?!?!!?!?!?!!????!?!!!!!!QUESTION MARKS!!!!!! I told you, it's not magic, but in not too long we can make some nice stuff happen automagically for us. :)