Why Subversion?
Subversion will really help you develop software. Think of it as a giant undo history for your code:
* If you make a mistake, you can roll back to a previous, working, version.
* If you want to try out developing a new feature, you can branch the code, develop the feature, and then decide you don't like that feature anymore, and easily subtract it from your codebase.
* It allows you to easily work with other developers, or teams of developers, on the same project.
* You can easily 'mark' (or tag) versions of your software for release, so you have a complete history of your project's releases, and you can easily pull up the code sent out for every version.
In this tutorial I will teach you the basics of subversion, with examples using the command line client 'svn'. The principles are the same across the more graphical clients, and you should be able to pick up the general workflow and use it for all clients.
Repository Structure
Subversion repositories can be of any structure, but I'd recommend you split them into the following three directories:
/trunk
/branches
/tags
Ignore the other two directories at the moment, and concentrate on the /trunk. The trunk is where you check in code.
Checking Out a Repository
'Checking Out' a repository is somewhat similar to checking out a book at a library in a bad neighbourhood. You tell the repository what book you want, and it will issue you a copy to go ahead and read, scribble on, make notes in the covers, and generally mess around with. This is called your 'working copy' of the repository's code.
svn checkout http://mysvnserver/svn/example-project/trunk /home/david/example-project
'svn checkout' - the command
'http://mysvnserver/svn/example-project' - the URL of the repository
'/trunk' - the trunk folder in the repository
'/home/david/example-project' - the destination (what folder do we want to check it out to on your computer's hard drive)
(Note that I am using a Linux directory structure here, so equally a destination could be C:\Users\David\example-project if I was using Windows)
Editing My Code
Once I have checked out my code, I can go ahead and make the changes to my code with an IDE such as Eclipse, or an editor like VIM. As long as you edit and save back the files in your working copy, you can use any method of editing you like.
Committing Changes
Once I've finished making all the changes I need, I can update the repository with my edited code. The way I do this is by 'committing' my changes. The commit command is recursive, which means it will descend into all directories under the directory I am currently in, and commit any changes it finds.
cd /home/david/example-project svn commit -m"<commit message>"
This will commit all changes I have made to the my example-project, recursively committing any changes to files below the directory /home/david/example-project. It will save these changes with the commit message <commit message>. You will usually want to provide a more informative commit message, giving information on what files have changed, and why. This will allow other developers to understand why and what you've changed.
Updating your working copy
svn update
This command will update the files in your current directory and below, with any changes that have been made to the repository by other developers. It is a good idea to run this regularly, to keep your working copy in sync with the repository and other developers working copies. This will download a fresh copy of the current state of the repository, overwriting any changes that you have made in your working copy. Therefore be careful with this, you can easily lose all your changes that you were preparing.
Conflicts
Sometimes there will be conflicts between the changes you are making and other developers changes. This is usually because someone else has committed a change between the time that you last ran 'svn update' and 'svn commit'. Therefore it is a good idea to run svn update often, before you start making any changes to your working copy.
If you do get a conflict, svn will tell you when you try and commit your changes with 'svn commit'. It will attempt to automatically resolve any conflicts by merging the two changes together. If it succeeds doing this, then you don't need to step in yourself. If it can't automatically merge the two changes, it will abort the commit, telling you you will have to resolve the merge yourself. It will mark up the files that are in conflict, with the lines that need merging. You will then have to go in and merge the changes by hand, usually with an editor.
The way I usually resolve merge conflicts, is to copy the files I have changed to a temporary directory away from your working copy, run 'svn update --force' on my working copy to bring my working copy in sync with the remote repository, which will download all the changes that have been committed by other developers. Then I edit the changes I have made in the temporary directory so that they include the changes made by the other developers, then I copy the changed files back to my new working copy, and commit them with 'svn commit'. Be sure to mention in your log message how exactly you resolved the conflict.
Exporting
When you check out a working copy using 'svn checkout', it will create hidden directories such as .SVN, in all of the directories of your project. These contain metadata associated with subversion, so it can keep track of the changes you've made to your files. Sometimes you don't want that metadata, you just want a clean copy of all your code. This is when you use 'svn export'. It is the same as 'svn checkout' except that it will not create the metadata:
svn export http://mysvnserver/svn/example-project/trunk /home/david/example-project-exported
Because svn export doesn't create metadata, it also means that you can't commit, update or run any svn commands on your exported copy. So it is not a working copy. It is useful when you want to release your software to the end user.
Tagging
Sometimes you will want to tag the current state of the repository, so that you can take a snapshot of it that will stay around permanently. This is especially useful for releasing a certain version of all your files, for example when you are sending your customer a new version of your software.
The way to do this is to use 'svn copy' to copy all files in the /trunk directory, to the /tags/<YOUR TAG NAME> folder under your repository root:
svn copy http://mysvnserver/svn/myproject/trunk/ http://mysvnserver/svn/myproject/tags/<YOUR TAG NAME>
After this, you can always export the tag snapshot with the following command:
svn export http://mysvnserver/svn/myproject/tags/<YOUR TAG NAME> /home/david/example-project-exported-<TAG NAME>
You can also check out the tag and make changes to it if you really want to, but I recommend you don't, as it defeats the purpose of the tag.
Identifying previous revisions
You can have a look at the history of a particular file or directory by using the 'svn log' command.
svn log /home/david/example-project
This will output a large list of all the changes that have been committed to the repository for your project, along with the all important revision number, which looks like 'r5833'.
'Undo' a file back to a certain revision
So you realise you've made a mistake, maybe last commit, maybe hundreds of commits ago, and you want to rollback to a previous version of a file. That is simple with svn. Run the 'svn log' command on that file to find the revision number of the change you want to rollback to. Then run:
svn update -r <revision number> <file>
for example:
svn update -r5833 readme.txt
Once you have rolled back to a previous version of the file, you can commit your rollback by using the usual:
svn commit -m"I rolled back readme.txt to revision 5833"
Then your rolled back file will be part of the current version again.
Conclusion
I hope you have gained some insight into subversion by reading this tutorial. You may want to use a graphical subversion client or one that is integrated into your IDE for ease of development, but you will find that they are all based on the original command line 'svn' client explained here.
This post has been edited by wordswords: 16 October 2012 - 10:10 AM
MultiQuote
| 