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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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