Subversion

Subversion is a revision control system maintained by the Apache Foundation. Its primary interface is a command line application: svn. Any files can be locally or remotely stored with a revision history. The most common uses for subversion are code repositories and document management.

Usage

svn <subcommand> [options] [args]

Subcommands:

 add
 blame (praise, annotate, ann)
 cat
 checkout (co)
 cleanup
 commit (ci)
 copy (cp)
 delete (del, remove, rm)
 diff (di)
 export
 help (?, h)
 import
 info
 list (ls)
 lock
 log
 merge
 mkdir
 move (mv, rename, ren)
 propdel (pdel, pd)
 propedit (pedit, pe)
 propget (pget, pg)
 proplist (plist, pl)
 propset (pset, ps)
 resolved
 revert
 status (stat, st)
 switch (sw)
 unlock
 update (up)

Most commands operate recursively on the current directory if no parameters are given.

Revert

To revert a file using SVN is to replace it with the last version stored in the code repository. If there are local edits, and the file is reverted, it will be put back to the last checked in version. For safety this function does not automatically operate recursively. Use revert with care as local edits can be lost permanently since they are not under version control.

Use Cases

Help for a subcommand:

svn help <subcommand>

Most often, at least for software developers, svn is used in the following way.

Perform an initial checkout of project code. This gets the latest version and puts it into a local working directory. To check out from a local (on the same computer) repository stored at /svn:

svn co file:///svn/project

To check out from a remote repository over SSH:

svn co svn+ssh://svn/project

Often path-based trunks and branches are used. By default svn uses the last part of the path to determine the name of the local directory to create. Pass a third parameter to override the default name of this working directory. To check out the trunk version of a project you might use:

svn co svn+ssh://svn/project/trunk project

If you add files in your local working directory you'll need to tell svn to add them to the repository so they get uploaded:

svn add filename

After you've made changes to files or added new files in your working directory you'll want to send them back into the repository:

svn ci -m "Added xyz feature"

Over time the files in the repository may be updated by other users. To update your local working copy go into the directory and use:

svn update

To see changes between your working copy and the latest version in the repository:

svn diff filename

To see the status of your local working directory (e.g. new and changed files):

svn status

Branching and Merging

There are multiple ways branching and merging of code can be handled with subversion. It's typically best to pick one common set of rules for all developers on a team at the very beginning of any project. Below are some examples of common use cases. Any can be augmented or combined.

Feature Branches

In this use case the trunk of the project code is always the latest ready for release, i.e. it's considered stable. This is most useful in projects with no specific version releases, such as web sites.

In this example, assume trunk is at

svn+ssh://example.com/svn/trunk

Branches start at

svn+ssh://example.com/svn/branches

To create a new branch perform a server-side copy of the trunk. This is an inexpensive copy as svn only tracks the copy, no files are technically copied on disk.

svn cp -m "Branch for feature X" svn+ssh://example.com/svn/trunk svn+ssh://example.com/svn/branches/feature_x

Then go into your working directory (your local copy of the project):

cd ~/projects/example.com

Let's say you're currently working in the trunk, but would like to switch to the new branch. This way you're editing the branch locally. The "svn info" command tells you what path you're currently at. To switch to the branch:

svn switch svn+ssh://example.com/svn/branches/feature_x

Now code edits are made locally. Commits will apply to only the feature branch. At any time switch back and forth between the trunk and branches. Just watch that changed files are being committed to the right place. It's helpful to run "svn info" and "svn status" at any time to see which path of code is being worked on locally and if any files should be committed before switching.

Once all edits are committed you have a branch with changes you'd like to see applied to the trunk. So the next step is to merge all of the changes from the time of the copy until now into the trunk. First we need to see the applicable revision numbers:

svn log --stop-on-copy svn+ssh://example.com/svn/branches/feature_x

Or, if my current local working copy is the branch,

svn log --stop-on-copy

Let's say the branch was made at revision 100 and changes were finished at 150. First switch to the trunk locally:

svn switch svn+ssh://example.com/svn/trunk

And then merge the changes into your local copy:

svn merge -r 100:150 svn+ssh://example.com/svn/branches/feature_x

Now your local copy of the trunk has the branch changes. Fix any conflicts and test the merge locally. It may also be helpful to have others test this copy of the code to make sure nothing that changed in the trunk while also working on the branch has broken something. Once satisfied, check in the changes and trunk is now updated with the branch feature change.

See Also

• Subversion Home Page
• TortoiseSVN - a windows shell extension