Using Subversion

  • Subversion is a version control system that allows users to keep track of changes made over time to any type of electronic data
  • See Subversion Collaboration WorkShop for details on the benefits of using Subversion for collaboration
  • For Subversion beginners see page A Crash Course in Subversion
  • For users familiar with CVS read below.

Checking Out a Repository

  • The general command to check out a subversion repository is
       # svn co <repository Uri> <local path>
    
  • To check out project repository foo do
       # cd ~/projects
       # svn co svn+ssh://biostat.mc.vanderbilt.edu/usr/local/subversion/foo/trunk foo
    
  • You can check out subdirectories instead of entire projects:
       # svn co svn+ssh://biostat.mc.vanderbilt.edu/usr/local/sportsmed/emoon/trunk/analysis/activity Activity
       # (be in parent to Activity on local machine before running this) 
    
  • The command to check out a package from the Vanderbilt Biostatistics repository is
       # svn co http://biostat.mc.vanderbilt.edu/svn/R/<repository name>/trunk/<path to file> <local path>
    

  • Department members can use their VUNETIDs and passwords to check out shared subprojects on the biosproj repository
    • example: kdesvn ... Subversion ... General ... Checkout a repository ... URL: https://data.vanderbilt.edu/biosproj/CI2 ; ... Select target directory: ~/doc/teaching
      • This will create the CI2 directory under ~/doc/teaching

  • If you do svn co ... and get a question about a certificate, answer p to allow it permanently; this will allow kdesvn to work with that repository
  • To create a new project under biosproj:
    • If you want it under your local directory biosproj, kdesvn can do this simply by doing File ... Open... and adding a new subdirectory
    • If you want to create a new project at a random location in your local tree, do the following:
        kdesvn ... Subversion ... General ... Checkout a repository
        https://data.vanderbilt.edu/biosproj
        Target directory: /tmp
        Creates /tmp/biosproj
        cd /tmp/biosproj
        mkdir foo
        Click on foo in kdesvn window
        Right click ... Add selected files/dir
        Right click ... commit
        cd basedir
        mkdir foo
        mv /tmp/biosproj/foo/.svn .
        Move all files to start project into directory foo
        Reopen foo in kdesvn
        Highlight each file and hit insert to add to repos
        Highlight all files and right click ... Commit
        Go to subfolders and repeat
  • If you want browsers to be able to automatically recognize a file type (here html) for example from http://biostat.mc.vanderbilt.edu/svn/bib/trunk/printbib.html, issue a command such as the following, then commit: svn propset svn:mime-type text/html foo.html
  • NEW This should be changed to use http://citeulike.org
  • If you are using multiple machines, use rsync to synchronize ~/.subversion across the machines

GUI Subversion client

Useful Subversion commands

  • svn help displays help on all sub-commands of the subversion program.
  • svn status displays the current status of all files within the repository directory specified.
  • svn info <file> displays information about the file, like last revision in which the file was modified, date of modification, etc.
  • svn mv <src file> <dest file> Moves a file from one location in the repository to another location while maintaining revision history and not having to manually add and remove the file.
  • svn revert <file> returns the file to it original pre-modification state.
  • svn blame <file> displays the file with users displayed next to the lines that they modified.
If you remove files under Subversion control without letting Subversion do it, do the following:
  • cd myfolder
  • svn commit # only if you have changes to save
  • svn update
  • svn revert -R .
Then your working copy should be 100% in sync with the server, and you can safely go about svn delete 'ing any files you don't want. And be sure to commit if you delete. If you really mess up a folder (say by deleting .svn folders), do something along the following:
  • Move folder to folder.bak and then do an svn update in the directory above folder (you should already be there if you did the move). Reconcile what you need to between folder.bak and folder, and then remove folder.bak.

Subversion for CVS users

Revision Numbers Are Different Now

In CVS, revision numbers are per-file. This is because CVS stores its data in RCS files; each file has a corresponding RCS file in the repository, and the repository is roughly laid out according to the structure of your project tree.

In Subversion, the repository looks like a single file system. Each commit results in an entirely new file system tree; in essence, the repository is an array of trees. Each of these trees is labeled with a single revision number. When someone talks about “revision 54”, they're talking about a particular tree (and indirectly, the way the file system looked after the 54th commit).

Technically, it's not valid to talk about “revision 5 of foo.c”. Instead, one would say “foo.c as it appears in revision 5”. Also, be careful when making assumptions about the evolution of a file. In CVS, revisions 5 and 6 of foo.c are always different. In Subversion, it's most likely that foo.c did not change between revisions 5 and 6.

For more details on this topic, see the section called “Revisions”.

Directory Versions

Subversion tracks tree structures, not just file contents. It's one of the biggest reasons Subversion was written to replace CVS.

Here's what this means to you, as a former CVS user:

  • The svn add and svn delete commands work on directories now, just as they work on files. So do svn copy and svn move. However, these commands do not cause any kind of immediate change in the repository. Instead, the working items are simply “scheduled” for addition or deletion. No repository changes happen until you run svn commit.
  • Directories aren't dumb containers anymore; they have revision numbers like files. (Or more properly, it's correct to talk about “directory foo/ in revision 5”.)

Let's talk more about that last point. Directory versioning is a hard problem; because we want to allow mixed-revision working copies, there are some limitations on how far we can abuse this model.

From a theoretical point of view, we define “revision 5 of directory foo” to mean a specific collection of directory-entries and properties. Now suppose we start adding and removing files from foo, and then commit. It would be a lie to say that we still have revision 5 of foo. However, if we bumped foo's revision number after the commit, that would be a lie too; there may be other changes to foo we haven't yet received, because we haven't updated yet.

Subversion deals with this problem by quietly tracking committed adds and deletes in the .svn area. When you eventually run svn update, all accounts are settled with the repository, and the directory's new revision number is set correctly. Therefore, only after an update is it truly safe to say that you have a “perfect” revision of a directory. Most of the time, your working copy will contain “imperfect” directory revisions.

Similarly, a problem arises if you attempt to commit property changes on a directory. Normally, the commit would bump the working directory's local revision number. But again, that would be a lie, because there may be adds or deletes that the directory doesn't yet have, because no update has happened. Therefore, you are not allowed to commit property-changes on a directory unless the directory is up-to-date.

For more discussion about the limitations of directory versioning, see the section called “Mixed Revision Working Copies”.

More Disconnected Operations

In recent years, disk space has become outrageously cheap and abundant, but network bandwidth has not. Therefore, the Subversion working copy has been optimized around the scarcer resource.

The .svn administrative directory serves the same purpose as the CVS directory, except that it also stores read-only, “pristine” copies of your files. This allows you to do many things off-line:

svn status: Shows you any local changes you've made (see the section called “svn status”) svn diff: Shows you the details of your changes (see the section called “svn diff”) svn revert: Removes your local changes (see the section called “svn revert”)

Also, the cached pristine files allow the Subversion client to send differences when committing, which CVS cannot do.

The last sub command in the list is new; it will not only remove local changes, but it will unschedule operations such as adds and deletes. It's the preferred way to revert a file; running rm file; svn update will still work, but it blurs the purpose of updating. And, while we're on this subject…

Distinction Between Status and Update

In Subversion, we've tried to erase a lot of the confusion between the cvs status and cvs update commands.

The cvs status command has two purposes: first, to show the user any local modifications in the working copy, and second, to show the user which files are out-of-date. Unfortunately, because of CVS's hard-to-read status output, many CVS users don't take advantage of this command at all. Instead, they've developed a habit of running cvs update or cvs -n update to quickly see their changes. If users forget to use the -n option, this has the side effect of merging repository changes they may not be ready to deal with.

With Subversion, we've tried to remove this muddle by making the output of svn status easy to read for both humans and parsers. Also, svn update only prints information about files that are updated, not local modifications. Status

svn status prints all files that have local modifications. By default, the repository is not contacted. While this sub command accepts a fair number of options, the following are the most commonly used ones:

-u
Contact the repository to determine, and then display, out-of-dateness information.
-v
Show all entries under version control.
-N
Run non-recursively (do not descend into sub directories).

The status command has two output formats. In the default “short” format, local modifications look like this:

$ svn status
M      foo.c
M      bar/baz.c
If you specify the --show-updates (-u) switch, a longer output format is used:

$ svn status -u
M            1047   foo.c
       *     1045   faces.html
       *            bloo.png
M            1050   bar/baz.c
Status against revision:   1066

In this case, two new columns appear. The second column contains an asterisk if the file or directory is out-of-date. The third column shows the working-copy's revision number of the item. In the example above, the asterisk indicates that faces.html would be patched if we updated, and that bloo.png is a newly added file in the repository. (The absence of any revision number next to bloo.png means that it doesn't yet exist in the working copy.)

Lastly, here's a quick summary of the most common status codes that you may see:

A
Resource is scheduled for Addition
D
Resource is scheduled for Deletion
M
Resource has local Modifications
C
Resource has Conflicts (changes have not been completely merged between the repository and working copy version)
X
Resource is eXternal to this working copy (may come from another repository). See the section called “svn:externals”
?
Resource is not under version control
!
Resource is missing or incomplete (removed by another tool than Subversion)

For a more detailed discussion of svn status, see the section called “svn status”.

Update

svn update updates your working copy, and only prints information about files that it updates.

Subversion has combined the CVS P and U codes into just U. When a merge or conflict occurs, Subversion simply prints G or C, rather than a whole sentence about it.

For a more detailed discussion of svn update, see the section called “Update Your Working Copy”.

Branches and Tags

Subversion doesn't distinguish between file system space and “branch” space; branches and tags are ordinary directories within the file system. This is probably the single biggest mental hurdle a CVS user will need to climb. Read all about it in Chapter 4, Branching and Merging.

Metadata Properties

A new feature of Subversion is that you can attach arbitrary metadata (or “properties”) to files and directories. Properties are arbitrary name/value pairs associated with files and directories in your working copy.

To set or get a property name, use the svn propset and svn propget subcommands. To list all properties on an object, use svn proplist.

For more information, see the section called “Properties”.

Conflict Resolution

CVS marks conflicts with in-line “conflict markers”, and prints a C during an update. Historically, this has caused problems, because CVS isn't doing enough. Many users forget about (or don't see) the C after it whizzes by on their terminal. They often forget that the conflict-markers are even present, and then accidentally commit files containing conflict-markers.

Subversion solves this problem by making conflicts more tangible. It remembers that a file is in a state of conflict, and won't allow you to commit your changes until you run svn resolved. See the section called “Resolve Conflicts (Merging Others' Changes)” for more details.

Binary Files and Translation

In the most general sense, Subversion handles binary files more gracefully than CVS does. Because CVS uses RCS, it can only store successive full copies of a changing binary file. Subversion, however, expresses differences between files using a binary-differencing algorithm, regardless of whether they contain textual or binary data. That means that all files are stored differentially (compressed) in the repository.

CVS users have to mark binary files with -kb flags, to prevent data from being garbled (due to keyword expansion and line-ending translations). They sometimes forget to do this.

Subversion takes the more paranoid route—first, it never performs any kind of keyword or line-ending translation unless you explicitly ask it do so (see the section called "svn:keywords” and the section called “svn:eol-style” for more details). By default, Subversion treats all file data as literal byte strings, and files are always stored in the repository in an untranslated state.

Second, Subversion maintains an internal notion of whether a file is “text” or “binary” data, but this notion is only extant in the working copy. During an svn update, Subversion will perform contextual merges on locally modified text files, but will not attempt to do so for binary files.

To determine whether a contextual merge is possible, Subversion examines the svn:mime-type property. If the file has no svn:mime-type property, or has a mime-type that is textual (e.g. text/*), Subversion assumes it is text. Otherwise, Subversion assumes the file is binary. Subversion also helps users by running a binary-detection algorithm in the svn import and svn add commands. These commands will make a good guess and then (possibly) set a binary svn:mime-type property on the file being added. (If Subversion guesses wrong, the user can always remove or hand-edit the property.)

Versioned Modules

Unlike CVS, a Subversion working copy is aware that it has checked out a module. That means that if somebody changes the definition of a module (e.g. adds or removes components), then a call to svn update will update the working copy appropriately, adding and removing components.

Subversion defines modules as a list of directories within a directory property: see the section called “Externals Definitions”.

-- Copied from http://svnbook.red-bean.com/nightly/en/svn-book.html
Topic revision: r12 - 15 Jul 2014, FrankHarrell
 

This site is powered by FoswikiCopyright © 2013-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback