Subversion is a version control system, it allows multiple people to work on the same resources simultaneously and seamlessly merges their edits wherever possible. When changes conflict it provides tools for resolving the conflict.
This page contains tips for day to day use of subversion. If you are brand new to subversion you may want to read SubversionLayout first. That page describes how best to lay out a subversion repository for your project.
Key Commands (and a common workflow)
This section will describe the most commonly used commands and, in doing so, will describe a typically patch generation or commit process.
The scenario we are considering here is that you have checked out a subversion repository and have added a feature locally. You now want to generate a patch for the project (or if you have commit rights commit the changes directly). We recommend the use of the command line to do this as it is very easy to make a mistake using GUI editors. Using a rigorous process from the command line will, once you are used to it, be quicker and will result in fewer errors.
The first thing you need to do is make sure there are no changes in the code base you do not intend to include in your contribution.
svn status (or svn st) is used to check the status of the current checkout. It will tell you useful info such as what files have been changed and which are new (i.e. not yet committed to the repository).
Output from this command looks something like:
$ svn st ? derby.log ? hs_err_pid684.log A src/test/java/uk/ac/osswatch/simal/wicket/panel/TestPersonListPanel.java ? src/main/java/uk/ac/osswatch/simal/wicket/doap/PersonFilterInputModel.java ? src/main/java/uk/ac/osswatch/simal/wicket/doap/ResourceFilterInputModel.java M src/main/java/uk/ac/osswatch/simal/wicket/doap/ProjectFilterInputModel.java M src/main/java/uk/ac/osswatch/simal/wicket/panel/PersonListPanel.html M src/main/java/uk/ac/osswatch/simal/wicket/panel/PersonListPanel.java M src/main/java/uk/ac/osswatch/simal/wicket/data/SortableFoafResourceDataProvider.java M src/main/java/uk/ac/osswatch/simal/wicket/data/SortablePersonDataProvider.java
Here we see there a number of files locally that are not known on the server (indicated with a ?, a number of files that have been modified (M) locally, and a single file that has been created locally and added to the local filesystem that is already scheduled for addition to the repository.
The first thing to do when making your contribution is to check that all the necessary files are added to the repository and that no extra files are going to sneak in. A quick way of checking just the files that may need to be added is with the command:
svn st | grep ^?
This command runs the above status command but only outputs lines that start with a '?'. The result of the above command when the status of the filesystem is as described previously is:
$ svn st | grep ^? ? derby.log ? hs_err_pid684.log ? src/main/java/uk/ac/osswatch/simal/wicket/doap/PersonFilterInputModel.java ? src/main/java/uk/ac/osswatch/simal/wicket/doap/ResourceFilterInputModel.java
This is much easier to read and we can see at a glance that there are two extra files we do not want to commit (the log files) and two that we do (the java files).
This step is only required if you have commit access to the repository. If you need to make a patch to submit to the project you can skip this section.
We need to add all the files we wish to include. We can either delete the files we don't want to include or we can selectively add the ones we do want to include. In this case we'll delete the down extra files.
Now we need to add the files we do want. Since we have checked there are no unwanted files in the local tree we can simply do:
svn add src/main/java/uk/ac/osswatch/simal/wicket/doap/*
Now we do a sanity check to ensure we are not going to commit any files or changes we don't intend to:
Which gives us:
$ svn st A src/test/java/uk/ac/osswatch/simal/wicket/panel/TestPersonListPanel.java M src/main/java/uk/ac/osswatch/simal/wicket/doap/ProjectFilterInputModel.java A src/main/java/uk/ac/osswatch/simal/wicket/doap/PersonFilterInputModel.java A src/main/java/uk/ac/osswatch/simal/wicket/doap/ResourceFilterInputModel.java M src/main/java/uk/ac/osswatch/simal/wicket/panel/PersonListPanel.html M src/main/java/uk/ac/osswatch/simal/wicket/panel/PersonListPanel.java M src/main/java/uk/ac/osswatch/simal/wicket/data/SortableFoafResourceDataProvider.java M src/main/java/uk/ac/osswatch/simal/wicket/data/SortablePersonDataProvider.java
Note that if you skipped the previous section you will have some files marked '?' instead of 'A', this is OK, you'll deal with those in the next section.
All is well.
Make the patch/commit
If you have commit access you can now commit the changes using svn commit (or svn ci):
svn commit . -m "Added the ability to filter the person list using a regular expression on the name"
If you need to make a patch then it is a little more difficult (pay off for being able to skip the svn add section above). First you create the patch for the files you have modified:
svn diff > filterPeopleByName.diff
You then need to bundle this with the files you need to add, remember you can use svn st to check which they are. This whole bundle should then be submitted to the project issue tracker.
Simple How Tos
It is outside the scope of this page to provide a full list of commands and their use. Instead you should see the Subversion Book, which is available free online.
The remainder of this page contains notes about how to do things quickly and easily using SVN command line tools.
Merging a branch with trunk
Once you have completed work in a branch and you want to merge with trunk follow these steps (assuming your current working copy is the branch):
Find the revision in which you created the branch:
svn log -v --stop-on-copy
This will output the log until it hits a copy commit. Check the log message to ensure it was the copy that created the branch and note the revision number.
Switch to trunk with:
svn switch https://svn.foo.org/trunk/bar
Now check the changes look right with:
svn diff -r revision:HEAD https://svn.foo.org/branches/bar-foo
where "revision" is the revision number obtained earlier.
Once you are satisfied the changes are what you want actually merge them into trunk with:
svn merge -r revision:HEAD https://svn.foo.org/branches/bar-foo
Changing a Log Message
Log messages are very important as they form the past history of work on your project. If you need to edit a log entry for a past commit you can do so using the command below. However, you should think carefully before doing this, do not remove any information relating to IPR within the commit and do not change the meaning of the commit message. You should only use this command to correct mistakes or clarify a commit message.
svn propedit svn:log --revprop -r547661 --editor-cmd vi https://svn.foo.org/bar/trunk
The -r547661 should be the revision number that you want to edit the log message for.
The editor you identified in the --editor-cmd switch will open up and allow you to edit the current log message. Save this and exit the editor.
You should then see something like:
Set new value for property 'svn:log' on revision 547661
Reverting to a previous change
Suppose you want revert changes in foo/bar.xml from HEAD to revision 17847, just do this:
svn merge -r HEAD:17847 foo/bar.xml foo/bar/xml