Page 1 of 1

Commandline Subversion Tutorial

#1 wordswords  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 76
  • View blog
  • Posts: 272
  • Joined: 17-December 11

Posted 15 October 2012 - 12:47 PM

Commandline Subversion Tutorial

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


Is This A Good Question/Topic? 4
  • +

Replies To: Commandline Subversion Tutorial

#2 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7648
  • View blog
  • Posts: 12,902
  • Joined: 19-March 11

Posted 16 October 2012 - 07:52 AM

This is a good overview. Nothing to add - if you're interested in playing with svn, this will get you started.

Once you get started, you might want more information - the O'Reilly on subversion is free on line. O'Reilly Keep that bookmarked. It's a little out of date, but only in the more advanced topics - the svn API for python is now pysvn, and it's a lot nicer than the simple wrapper described in the book. For all standard operations, this book is still correct.

Subversion gets little love these days, but it's a very effective and a very simple tool for version control, and once you've got the basics, there's a lot of fun stuff you can do with it. It can be integrated with build scripts (ie, if you use ant to manage your build/deploy process, svn plays nicely) and you can write "hooks" to do stuff like send notifications on commit, update auto-generated documentation, and so forth.

Just yesterday, as it happens, I wrote a pretty complete automated deploy process using the pysvn API, managing a dev and QA environment, as well as a weird "Pre-QA" environment as a compromise between continuous integration and the week-long QA cycle. It was surprisingly easy - subversion is a nice tool!
Was This Post Helpful? 1
  • +
  • -

#3 Shane Hudson  Icon User is offline

  • D.I.C Technophile
  • member icon

Reputation: 343
  • View blog
  • Posts: 1,286
  • Joined: 06-December 09

Posted 18 October 2012 - 12:36 AM

This is a very well written tutorial, fantastic guide to beginners which I am sure I will be recommending to SVN beginners. There are a few sections that could be useful as extras to this, such as comparisons of when to use SVN over the (arguably better) alternatives such as Git and Mercurial, another section could be how to set up the repository online.
Was This Post Helpful? 1
  • +
  • -

#4 wordswords  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 76
  • View blog
  • Posts: 272
  • Joined: 17-December 11

Posted 18 October 2012 - 02:57 AM

View PostShane Hudson, on 18 October 2012 - 07:36 AM, said:

This is a very well written tutorial, fantastic guide to beginners which I am sure I will be recommending to SVN beginners. There are a few sections that could be useful as extras to this, such as comparisons of when to use SVN over the (arguably better) alternatives such as Git and Mercurial, another section could be how to set up the repository online.


Thanks for your feedback. I was thinking I might create a separate tutorial in the future for setting up a repository. I could create a tutorial on 'choosing a SCM' for comparisons of source control systems also.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1