Chris says, You are ever-so-slightly urged to read Episode One of the Not-So-Boring Guide to SVN before you read Episode Two. And no, I would not, could not, on a train.

Welcome back to the Not-So-Boring guide to SVN.  On the last episode, we learned about Checking Out files from the dark-scary Repository, making a commit-ment to the files if we make changes to them, and making sure we Update our files on occasion to verify that we are working with the latest-greatest code.

Creating your own Repository

All of the above options assume that you're working for an Open-Source project or a company where the SVN Repository is already set up and ready-to-go.  You, however, I know are different.  You've got your own ideas. You don't want to work for the man.  You want to be the man.   You've been watching the Apprentice, listening to Venture Voice, and are done and gets things smart.  Great.  Have I got the answer for you!

The create function creates a repository where-ever you want it.  You want it on the moon?  No Problem.

$ svn create /repos/on/the/moon

What about on an elephant?

$ svn create /repos/on/the/elephant

If you don't want to host it locally, you can always check out the plethora of hosting options.  Services like Beanstalk and Dreamhost making hosting a Subversion Repository easy cheesy.

Next, import your project into the Repository so it can be checked out and worked on by you and your army of programming minions that you will hire for paltry wages but that you will supply with unlimited free cokes, 30-inch monitors, and Aeron Chair's.

$ svn import ProjectFileTree file://repos/on/the/elephant/ProjectName

Once in the repository, you can use the check-out command to begin work on the project.

$ svn checkout file://repos/on/the/elephant/ProjectName

And while we're add it, go ahead and update those files.  You never know where they've been.

$ svn update

All Deer May Cough (On) Moles

Now you're ready to go ahead and edit those files to your little heart's content.  Subversion automatically detects which files have been changed (remember the secret .SVN files).  BUT (and this is a BIG BUT), if you intend to make any changes to the Project File Tree such as adding a new file, deleting a file, copying a file, moving a file to another location, or making a new directory, SVN needs a little guidance.  Thus, the following commands are provided.

Add a File or Directory to the Repository.

$ svn add VeryPracticalFileName

Delete a File or Directory from the Repository.

$ svn delete ExtreamlyPracticalDirectoryName

Copy a File and Add to the Repository

$ svn copy Roger CopyOfRoger

MkDir creates a new Directory in the Repository.

$ svn mkdir DirectoryName

Move is kind of wierd.  Strange even.  It moves a file from one part of the Repository to the other.

$ svn move Here There

is the exact same thing as as saying:

$ svn copy Here There
$ svn delete Here

Strange huh?  But it makes sense if you think long and hard about it.  Because if you were moving 'Here' to 'There,' it wouldn't be 'Here' anymore would it?  It would be 'There.'  Actually, think of the move command like the Cut command on your computer.  If you cut a file from a directory and paste it in another directory, you have essentailly moved it to the new directory.  Whew.

Break Time:  Here's a picture of My Dear Aunt Sally.  Stunning isn't she?

If you remember back to your years of golden locks and curls, Please Excuse My Dear Aunt Sally was a way to remember the Order of Operations: Parentheses, Exponents, Multiplication, Division, Addition, Subtraction.   To help you remember Add, Delete, Mkdir, Copy, and Move (the four things you may have to do if you intend to make any changes to the projects file tree), come up with your own Memory Jogging Device and write them in the blanks below!

ADD               DELETE           MKDIR              COPY             MOVE

____________     ____________   ____________   ____________   ____________

No, I don't care about the frequency.  What's the status Kenneth?

Before making a commitment to the Repository, it is in good form and fashion to run a status on your Working Copy.  Status gives you an overview of the changes you've made to your Working Copy since your last commit.

$ svn status
A    who/is/this/me.cpp
M   doing/this/synthetic.h

A is for Apple.  In Subversion speak,  'A' means that your file me.cpp is scheduled for addition.
M is for Moose. In Subversion speak, 'M' means that your file synthetic.h has been modified since your last commit.
C is for Cardigan.  In Subversion speak, 'C' means that your file is in a state of conflict!
D is for Done.  In Subversion speak, 'D' means that your file is scheduled for deletion.

There are several reasons why the status command should become your new best friend.

1. All the other kids are doing it and it's better then jumping off a cliff.
2. By seeing the changes you have made, you will have a better idea of how to document those changes in your -m flag once you decide to commit those changes.
3. The status can alert you to potential conflicts between the changes you have made and the local changes in your working copy.
4. You don't have to have a network connection.
5. See Number One.  (Oh no, infinite loop!)

I'm not going to spend my life being Burnt Sienna either.

I used to love Michael Jackson.  I listened to 'Dangerous' like a million times growing up.  One of my favorite Michael Jackson videos was "Black or White."  You know the where Macaulay Culkin is punk teenager and at the end all these people from different backgrounds and ethnicities morph into each other.  Like a man from African becomes an Indian woman.  And that woman becomes a Chinese Man, who then turns into a New Yorker from the bronx. This is the same video in which Michael sings, "I'm not gonna spend my life being a color" which I think it a great thing to say because we I too think that we should not spend our lives being "green" or "acqa" or "mother-of-pearl," but instead be human beings.  Anyway, the entire premise of the video was great because it preached that we should look past our differences and embrace our collective similarities.

Thankfully, Subversion doesn't see it this way.  It does not look past our differences.  In fact, it keeps record of them.   Using the Diff command, one can see the differences between your working copy and the last version that has been committed.

$ svn diff
Index: ThreatenAnimal.rb
===================================================================
--- ThreatenAnimal.rb    (revision 5)
+++ ThreatenAnimal.rb    (working copy)
@@ -1,2 +1,2 @@
-puts 'Stop Looking At Me Pignot Noir!'
+puts 'Stop Looking At Me Pignot Grigio!'

It seems as if i changed 'Stop Looking at me Pignot Noir' to 'Stop looking at me 'Pignot Grigio.'  The Diff command prints the differences to the console window in a very easy-to-understand format.  Are you ready?

• Lines that have '-' at the beginning are removed.
• Lines that have '+' at the beginning are added

Instead of printing all this useful information to the console where it could possibly be lost forever, why not print it to a file?

$ svn diff > thedifferencefile

Now you can E-mail the file to your friends, IM it to your significant other, facebook it just "because you can", or print it for religious reasons.

We all Make Mistakes

When I was six grade I got caught shop-lifting a yin-yang chain from the spectacular Spencer's gifts.  I put it in my hat.  The store-man saw me in the security mirror.  He took me to the back and called my parents.  My dad came and yelled at me.  He took me home.  My mom yelled at me.  I was ashamed.  What I am saying is that we all make mistakes, but unfortunately, unlike Subversion, real-life doesn't have a revert command.

Above, in ThreatenAnimal.rb I changed the line 'Stop looking at me Pignot-Noir' to 'Stop looking at me Pignot-Grigio' which, in hindsight, was kind of dumb.  I mean, I really don't want Pignor-Noir to look at me, but the bottom line is that Pignot-Grigio,  with it's fantastic flavorings of citrus and rutabaga, can look at me all day long if it wants to.  I made a mistake.  How can I possibly go back to how things used to be?

$ svn revert ThreatenAnimal.rb
Reverted 'ThreatenAnimal.rb'

Simple.  The Revert command reverts the file to it pre-modified state by overwriting it with the cached version of the file in the secret-hidden .svn folder.  NOTE:  This can only be done if the file has not-yet been committed.

Conflict Resolution 101

The situation is as follows:  You are driving down the left-lane of a two-lane highway when traffic comes to a stand-still.  You see that this is because your lane is coming to an end up ahead because of construction and everyone in your lane is merging into the right lane.  You think of yourself as a nice-guy good-citizen type, so instead of waiting till the very last second to merge, you put your right-blinker on, and merge your way into the right lane whenever you can get someone to let you in.  I found out this week that this is stupid way to merge.  In fact, you think you are doing the correct thing, the morally-upright thing, but really you are slowing down traffic even more.  If no one were to merge until the very last second, you would save upwards of 20% or more time.  But there's nothing to tell people this.  No sign or indication.  In fact, it is counter-intuitive to wait until the very last second to merge and if you wait till the very last second everyone else thinks you are a jerk.

Merging files in Subversion in tricky.  It's not easy, and, like on the highway, you could come off looking like a big jerk.  Let me demonstrate.  You edit ThreatenAnimal.rb one more time changing "Pignont Noir" to "Madame Bovary."  At the same-time, your teammate Jake Gyllenhaal checks-out, edits, and commits ThreatenAnimal.rb to look like the following:

puts 'Stop Looking At Me Pignot Noir!'
puts 'But, I mean, you can look look look'
puts 'If you really really want to'

Jake obviously has some feelings for Pignot Noir.  Which I think is a little strange.  But you don't know about these changes yet.  So before you commit your changes, you decide to do a final update to make sure everything is in tip-top order.

$ svn update
C    ThreatenAnimal.rb
Updated to revision 7.

The 'C' next to TheatenAnimal.rb stands for Conflict!

When a Subversion Conflict happens three new files are created in the same directory as TheatenAnimal.rb.

$ ls
ThreatenAnimal.rb    ThreatenAnimal.rb.r6
ThreatenAnimal.rb.mine    ThreatenAnimal.rb.r7

• ThreatenAnimal.rb now contains special markers like <<<<<<<< and ====== and >>>>>>>> which "visibly demonstrate" the differences between between your copy and Jake's to help you make a decision about how to merge both files.
• TheatenAnimal.rb.mine contains the your file as it existed in your Working Copy before you did the update.  Ex.  puts 'Stop Looking at me Madame Bovary!'
• ThreatenAnimal.rb.r6 contains the file as it looked when you originally checked it out from the Repository.  Ex. puts 'Stop Looking at me Pignot Noir'
• TheatenAnimal.rb.r7 contains Jake's version of the file that he committed to the Repository

At this stage you've got choices.

1. Merge the conflict by hand.  Open up TheatenAnimal.rb, look at the markers.  Make decisions.
2. Copy one of the temporary files on top of your working file.
3. Run svn revert TheatenAnimal.rb to throw away all of your changes
4. Freak out.

While #4 seems incredibly promising, option #1 is possibly more satisfying.  But who I am to judge?  So you open up TheatenAnimal.rb in your favorite text editor and see the following:

<<<<<<<<< .mine
puts 'Stop Looking At Me Madame Bovary!'
=======
puts 'Stop Looking At Me Pignot Noir!'
puts 'But, I mean, you can look look look'
puts 'If you really really want to'
>>>>>>>>>> .r7

The text between <<<<<<<<.mine and ===== shows your copy
The text between =======  and >>>>>>>>> .r7 shows Jake's copy

Now, this is where you have to be careful.  A "big jerk" would just delete all the changes Jake made (which would be sad because he's a very busy man between programming and his full fledged acting career) and keep all of your own changes.  But you aren't a jerk, are you?  So you call up Jake, and the following conversation takes place.

Jake: "Hello?"
You:  "Jake!"
Jake:  "Oh hey man."
You:  "Hey, uh yeah.  Just a quick question.  I know you are busy making Donnie Darko II."
Jake:  "Yeah, it's cool man.  What's up?"
You:  "Well, you know TheatenAnimal.rb?  I know you are in love with Pignot Noir, but I really need it to be Madame Bovary.  She's, well, theatening, but classic.  You know?  Is that cool?"
Jake:  "Oh yeah man.  I totally understand.  I'm in love with Madame Bovary too, but don't really want her to loook at me.  It's complicated."
You:  "So, you trust the changes I'll make?"
Jake:  "Do it Doug."

So, you merge both Jake's file and your file together.  The final outcome is below.

puts 'Stop Looking At Me Madame Bovary!'
puts 'But, I mean, you can look look look'
puts 'If you really really want to'

The conflict between You and Jake is now resolved.  Tell subversion that.

$ svn resolved ThreatenAnimal.rb
Resolved conflicted state of 'ThreatenAnimal.rb'

The resolve command resolves the conflict and deletes all the temporary files created when the whole conflict between you and Jake started.

You are now ready to commit the merged file.

$svn commit -m "My compromise with Jake with a strange fear and a love of Madame Bovary"
Sending        ThreatenAnimal.rb
Transmitting file data .
 
Committed revision 8.

Version Control can be complicated sometimes especially when celebrities are involved.  Jake's cool, but most of them are a bunch of babies.

And now a conversation between Present me and Past me.

Yo.  (Present Chris)

What's going on? (2003 Chris)

Not much.  Hey, what's with the Robot arms?

Oh.  These?  Yeah.  You were really into dancing the Robot back in 2003.  You thought it was hilarious.

Well you look dumb.  Stop.  It's definitely not cool to dance in the Robot in 2008.  Mouse ears are cool now.  And V-Neck tees.  Look into them.

Got it.  Hey, quick question.  If you could go back to, uh, me and give you err me one piece of career/programming advice.  What would it be?

Find a cute chick and marry her because you won't meet any more girls after college in your predominately male work-place.

Got it.  Jotting it down.  "Get married…"  OK.  Anything else?

Version Control, dude.

Wha..?  Version Control?  Why?

It's like time travel, dude.

…and, you're in love with it.

Welcome to the Not-So-Boring Guide to Subversion.

I created this guide because in the process of reading the Official Guide To SVN I feel asleep.  Three times. The following is the result of trying to keep myself amused enough to stay awake and learn Version Control  Which, I am told, is like Time Travel minus the Terminator nakedness.

Check-It-Out

To start, let's say you wanna work on an Open Source Project that you keep hearing all these kids talk about around the water cooler.  It's a really cool project too.  Lots of lasers.

Most of the files for open-source projects are stored in something called a Repository.  Everytime I hear the word Repository, I think Dungeon.  When I say Repository, you say Dungeon.  Repository.  (Dungeon).  Repository.  (Dungeon)  The Repository is the creepy, spooky, wet and dank place all the files are kept.

So, first of all, if you wanna get files out of the Reposoitory, you have to check them out.  Like library books.     Go ahead, try it.

$ svn checkout http://www.codingwithcomments.com/SubversionTest/trunk/

These files that you've checked out, are what they refer to in the "biz" as a Working Copy. Some secret files are kept in our Working Copy directory in a secret folder ominously named ".svn."  If you put a period before a folder name, it hides it.  In your folder preferences, you need only enable "show hidden files" to see these secret monstrosities.  These files help subversion keep track of all the unpublished and out-of-date files with respect to to all the folks who are publishing their changes.

$ svn checkout http://www.codingwithcomments.com/SubversionTest/trunk
A    trunk/ThreatenAnimal.rb
Checked out revision 1.

Two Ruby files.  Sweet.  What?  Did you think we'd have you checkout some Cobol?  Heck no.

Now type:

$ ls -A trunk
.svn  ThreatenAnimal.rb

Look, you can see the .svn directory!  Appending '-A' to 'ls' lets you see all the secret hidden files.  It's like your asking '-Aren't you going to show me all the secret files?"

Now run ThreatenAnimal.rb.

$ ruby trunk/ThreatenAnimal.rb
Stop Looking At Me Swan!

Adam Sandler is not a friend to animals.  OK, now open ThreatenAnimal.rb in your favorite text editor and change 'Swan' to 'Adam Sandler'.  My favorite editor is called 'Emacs Vim'  It's a special brew of the two best text editors lumped into one.  (This is a joke.  There is no such editor.  Some programmers find this sort of joke funny.)

Make a Commit-ment

So now you and ThreatenAnimal.rb have been going steady for awhile.  You've been on several dates, and you are even thinking about asking it to prom in a few weeks.  You are ready for a bigger commitment.  You are ready to 'commit' your changes to the repository.

$svn commit ThreatenAnimal.rb -m "Adam Sandler != funny"
Sending        ThreatenAnimal.rb
Transmitting file data .
Committed revision 5.

'-m' appends a commit note.  You should do this when you commit a file so everyone knows what changes you made.  When I decide to commit to someone, I write them a note.  "Do you want to be my girlfriend?  Check yes or no."  This way, they know what's up.

Note:  Each file doesn't have to be commited individually.  For example, if there was more than one file in the trunk directory, they could all be commited at once with a single command.

$svn commit trunk

I need an update, pronto!

Uh oh.  But there could be a problem.  Say you are working on this project with the dreaded Ebeneezer Scrooge.  Ebenezzer Scrooge checked out ThreatenAnimal.rb when you were still trying to decide if you wanted to make a commitment.  His TheatenAnimal.rb file still threatens swans instead of Adam Sandler.  Oh Ebeneezer, you're such a card.  Simply type,

$svn update
U  ThreatenAnimal.rb
Updated to revision 5.

The update command brings Ebeneezer's files up to date.  Ebeneezer is happy now.  So happy, he sends me a message on google chat, 'No, you still can't have a lump of coal.'  Oh frostbite!

Q and A

Question:  What's with all the revision numbers?

Answer:  Each time you make a 'commit' it updates something called a Revision Number.  These numbers start at zero and go to infinity.  Even If you 'commit' only one file in the repository, it creates a completely new file tree and updates the revision numbers of all the files in the repository.  It's all or nothing.  Think of it this way.  If you make a commitment to a girl (or a guy), you are making a commitment to not just the girl (or guy) but to their friends, parents, and pets.  It's an all or nothing deal, right?  You can't just take one without taking all the rest.  This sucks, I know, but that's why these Suversion guys refer to it as an Atomic Transaction.  Because you feel like you've just been nuked.

There's a picture of how this works in the famous SVN book.  It's pretty boring and drab but it gets the point across I suppose.  0 through 3 are the revision numbers.

However (comma) although all the revision numbers are updated for all the files in the Repository, your Working Copy (the copy of the project on your hard-drive) contains Mixed revision numbers.

Scandalous Revision Numbers

OK.  Let's see an example shall we?  Let's say you've got three files, you've recently done an svn Update, and all the files in your Working Copy and Repository are at Revision 5.

BlackBear.rb           (Revision #5)
Santa.rb                 (Revision #5)
ElephantMan.rb      (Revision #5)

We then make a change to ElephantMan.rb and Commit him to the Repository (where every Elephant-type man deserves to go).  Just like we talked about, all the files in the Repository are at Revision #6.

BlackBear.rb           (Revision #6)
Santa.rb                 (Revision #6)
ElephantMan.rb     (Revision #6)

BUT, the files in your Working Copy have MIXED revision numbers.

BlackBear.rb           (Revision #5)
Santa.rb                 (Revision #5)
ElephantMan.rb     (Revision #6)    <== the oddball

This is NORMAL.  In fact, sometimes you want to purposefully backdate certain files of your Working Copy to an earlier revision.  This makes Subversion, you know, kind of like a Time Machine.  To understand the Time Machine, I suggest you rent '12 monkeys.'  It is the definitive movie on Time Travel.  Whatever you do, don't watch the Back To The Future movies.  These are silly and Oedipal.  How can those two adjectives co-exist?  Only with the help of Steven Spielberg.

Just Remember: Commit != Update

A Commit does not equal an Update.  An Update doesn't equal a Commit.  You can Commit all day long, but until you run an update, you aren't going to incorporate anyone else's Commit(s) into your Working Copy.

Hello! (in french)

I think everyone that starts blogging inevitiably writes things like, "This is my first blog, um, i don't know what to say, um, oh this is awkward isn't it.  Hello world!"  But, unlike everyone, I do actually have something (somewhat interesting) to say.  Which is strange, but nice I suppose.

The idea for this post started when I was reading a post on Stackoverflow, the new joint venture between Joel Spolsky and Jeff Atwood, entitled 'How you can tell you are ready to start your own blog?'

The post went as follows:

class Report
  def initialize
    @title = 'Monthly Report'
    @text = ['Things are going', 'really, really well.']
  end
 
  def output_body
    @text.each do |line|
      output_line(line)
    end
  end

Geshi isn't limited to wordpress, but can be used to "highlight code on ASP pages, numerous blogs, wikis and forums."

2.  Use Windows Live Writer with the Insert Code plugin. The problem with this option is that you are limited to blogging on a Windows (sic) Machine, and it only formats the the following languages:  C#, HTML, MSH, JavaScript, Visual Basic and TSQL.

3.  SyntaxHighlighter is a Javascript based Code Formatting mechanism that can easily integrate into most blogging systems.  It supports the following languages: C++, C#, CSS, Delphi, Java, JavaScript, PHP, Python, Ruby, Sql, VB, XML/HTML.  Ellis Web posted a great article on Using Syntax Highlighter to Format Code in Wordpress.

4.  If using the blogging engine Chyrp, Geshify or Feather can be used for Code Formatting.

5.  Mango Blog and BlogCFC both support code blocks out of the box.

6.  CodeHTMLer is a simple program that translates plain text code into a colorized HTML version of the code.

7.  If you use TextMate in Mac OSX, BitButter has a great post on how to display your TextMate code (formatting included) in WordPress.