Part 1: The Setup

Step 1: install subversion

Linux

Debian/ubuntu:

# apt-get install subversion

Mac

First, you must download the universal binary package of subversion. You can find this on the official subversion website here or if you are using OSX you can find the .dmg here. Be sure to download the correct file for your operating system. To install subversion, just run the downloaded file and follow the steps it describes.

Chances are, once you install subversion the executable programs won’t be in your path. What does this mean? When you login to the terminal, you won’t be able to type the command “svn” because it won’t know where to look. To fix this, create a file called .bashrc and save it in your home directory. Put this code in it:

codetitle. ~/.bashrc

export $PATH="/usr/local/bin:/usr/local/sbin:$PATH"

Then run source .bashrc. You should be able to run the svn command now.

You may also want to install SvnX, a graphical interface for svn on macs.

Step 2: add the rails project to subversion

To add your rails project to subversion, you need to know the url of your subversion repository. You either had to previously set this up, or someone else set this up for you. Examples of the subversion repository url include:

https://giip.ucsc.edu/svn/<repo name>
svn+ssh://giip.ucsc.edu/svn/<repo name>
svn://localhost/svn/<repo name>
file:///svn/<repo name>

To import a rails project into an empty repository, do this:

cd rails_project
svn import . repository_url -m "initial import" --username your_username

This code is importing everything in the current directory (by using a period, you could replace that with whatever specific files you were importing into subversion), logging this import with the message in quotes (after -m) and recording what user is making this change to the subversion repository.

If the everything is working correctly, you should see many files being added to subversion and it should say “Committed revision 1.” when it is finished. You are now ready to begin using subversion!

Step 3: removing a few files from subversion

In order for subversion to work properly, there are certain files that should be ignored by subversion. These include the log files and certain files associated with the database. The easiest way to do this is to create a file called svn.rake, just like how we made bash.rc, as follows:

codetitle. lib/tasks/svn.rake

desc "Configure Subversion for Rails"
task :configure_for_svn do
  system "svn remove log/*"
  system "svn commit -m 'removing all log files from subversion'"
  system 'svn propset svn:ignore "*.log" log/'
  system "svn update log/"
  system "svn commit -m 'Ignoring all files in /log/ ending in .log'"
  system 'svn propset svn:ignore "*.db" db/'
  system "svn update db/"
  system "svn commit -m 'Ignoring all files in /db/ ending in .db'"
  system "svn move config/database.yml config/database.example"
  system "svn commit -m 'Moving database.yml to database.example to provide a template for anyone who checks out the code'"
  system 'svn propset svn:ignore "database.yml" config/'
  system "svn update config/"
  system "svn commit -m 'Ignoring database.yml'"
  system "svn remove tmp/*"
  system "svn commit -m 'Removing /tmp/ folder'"
  system 'svn propset svn:ignore "*" tmp/'
  system "svn update tmp/"
  system "svn commit -m 'Ignoring all contents of tmp/'"
end

desc "Add new files to subversion"
task :add_new_files do
   system "svn status | grep '^\?' | sed -e 's/? *//' | sed -e 's/ /\ /g' | xargs svn add"
end

desc "shortcut for adding new files"
task :add => [ :add_new_files ]

To make all of these changes, run this file the first time you check out your project from subversion. To run this file, use this code:

rake configure_for_svn

Step 4: Globally exclude weird files

If you are using Appleshare, it will dump all sorts of files throughout your rails project. Here is how you can globally exclude those files

codetitle. /etc/subversion/config

[miscellany]
global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store :2eDS_Store :2eTemporaryItems .AppleDouble

Part 2: Using Subversion

Step 1: check out your rails project through subversion

To check out a local copy from the repository, you use the “svn co” command:

shell> cd
shell> svn co svn://myproject

This will check out all of your project’s files from your subversion repository.

To confirm that your local checkout is a valid you can run “svn info” like so:

shell> cd myproject
shell> svn info

Step 2: using migrations

if you have used ruby on rails previously, you should already be familiar with the basics of using migrations, and you can skip this step

In order to edit the database for your rails project, you are going to need to use migrations. To use migrations, you must first create a model.

script/generate model item -c

The -c option automatically adds any files created by the command to subversion (you will probably always want to pass script/generate the -c flag while using subversion). You can make sure this worked by doing an

svn status

and making sure there is an “A” for add next to all of the files. The script/generate command created our first migration file, and you can find it by following this path:

project_directory/db/migrate/001_create_items

Open up this file in your favorite text editor. Edit the migration so that the database it creates or edits will fit the needs of your project. You now need to run the migration with this code:

rake db:migrate

If this worked successfully, you should now check your subversion status

svn status

If any of the files have question marks next to them, subversion does not know what to do with them. This most likely happened with the db/schema.rb file. To add this file to subversion, use this code:

svn add db/schema.rb

Do this with any of the files that have question marks next to them, and then you have completed your first migration!

Step 3: checking in your changes

Once you have made your changes to the rails project, you need to check in your changes back to the repository. This is a very simple step, and is done through this code:

svn ci -m "your_message" --username your_username

Replace your_message with a message to let everyone else working on your project know what changes you made with this revision.

Step 4: tagging revisions

Before you learn how to tag a certain revision, it is important to understand the trunk-tags-branches system of development that is commonly used with subversion. The trunk is your main project that is still under development, or at least still being updated. In this tutorial prior to this step, you have been dealing entirely with the trunk of your project.

Tags are specific revisions of the project that have a special purpose. For example, when you get to a point where the project is somewhat usable, it may be useful to create a “beta” tag on that revision. This will allow people to easily check out the working version while others continue to make changes and improvements to it. Another reason to use tags is when you have a version that is qualified to be released to the public, but you still want to continue developing your application.

Branches are basically tags that are being developed differently than the trunk. For example, if you are updating a project to use a new version of a certain software, you probably want to create a branch. You can continue to update this branch, but not update it with the code requiring the newer software. This allows you to not lose a lot of your users when you make a large update.

Now that you understand the basics of this system, here is how you would tag the current version of your project:

svn copy repository_url \
           repository_url/tag_name \
      -m "your_message"

This code will make a “cheap copy” of your current repository and put it in a folder called tag_name in your repository. However, this will only make a copy of the project version you currently have checked out. In order to check out a version that is not the most recent, you will have to pass the -r option to the svn update command.

svn update -r revision_number

Now you know how to check out a specific version of your project, and tag it. To work with this tagged version, you will need to check it out from the repository using this code:

svn co repository_url/tag_name

Now you have easy access to your tagged version. After checking it out, you can use it for whatever purpose it was created for.

Step 5: branches

Branches, which were explained in step 4, are actually treated exactly like tags by subversion. The only difference is that a branch will be updated and a tag never changes. To turn a tag into a branch, simply check it out

svn co repository_url/tag_name

and make your necessary revisions. When you check your revisions in, subversion will know that it is updating just the tagged version (that has now become a branch) you have checked out.

Step 6: resolving conflicts

Subversion is incredibly useful because of how easily it allows many different people to work on the same project. However, this can sometimes lead to conflicts between different versions of the same file. Subversion will check for conflicts whenever you run an

svn update

and it will let you know of any conflicts it finds by putting a ‘C’ next to the file it is trying to update. When subversion finds a conflict, it will create these three files:

filename.mine
filename.rOLDREV
filename.rNEWREV

OLDREV and NEWREV will be revision numbers

In addition to creating these files, it will create a file that has the conflicting versions merged together. This file has conflict markers in it that will show which version of the file the specific code is coming from. There is no standard procedure for solving the conflict; you will have to look at the conflicts and merge the code in a way that will do what the previous change was intended to do, as well as making the changes you wanted to make.

After you have resolved the conflict in a way that fits your goals, you should run

svn resolved file_path

in order to get rid of the temporary .mine, .rOLDREV, and .rNEWREV files and allow you to check in the file that used to have a conflict in it to the repository.

Helpful Subversion Commands

svn update

This will update your project to the most recently committed version. You can update your project to a specific revision with this code:

svn update -r revision_number

replacing revision_number with the number of the revision you want to update to. Use the log command to find the revision number of the revision in question.

svn commit

This will check in your version of the project to the subversion repository. You must leave a log message for each commit, and the easiest way to do this is

svn commit -m 'this is my message for the log'

It will then let you know what revision you just committed.

svn status

This will show you the status of your working version of the project’s files and directories. Some basic information it will tell you about each file or folder is given by a single letter next to the file name. ‘A’ for added to subversion, ‘D’ for deleted, ‘M’ for modified, ‘?’ for not in subversion, etc.

svn log

This will print a list of the revisions for your project, as well as showing you the logged message for each revision and who committed that revision.

svn copy

The only use for the copy command you are likely to come across is when making new tags or branches. Review Part 2, Steps 4 and 5. If you still need help, check out Version Control with Subversion.

svn revert file_path

When you need to revert a specific file to the version of that file in the repository, but you don’t want to get rid of all of your local changes, use the revert command. This will get rid of most local changes made to the file, as long as you give the correct path to that file.

svn help

The help command can be used whenever you need to figure out how to properly use a command, and to learn what options you can pass that command. Use it as it is printed above for a list of different options to pass the help command, or simply use

svn help command_name

to learn more about command_name.

other subversion resources / citations

How to Use Subversion with a Rails Project
Subversion Official Site
Version Control with Subversion
Subversion on Wikipedia