Subversion Tutorial

Subversion

Abstract

Subversion (SVN hereafter) is a version managament system designed as a replacement for, and general improvement on, CVS. Subversion is designed to be a distributed, concurrent, expandable version control system.

To have a complete documentation on Subversion, please go and read this: http://svnbook.red-bean.com/en/1.1/index.html Those wiki pages are only a quick tutorial for our use of SVN.

And don't forget to use the 'svnadmin help' , 'svn help' commands to get information on usage and so on for a svn command.

Features

When discussing the features that Subversion brings to the version control table, it is often helpful to speak of them in terms of how they improve upon CVS's design. If you're not familiar with CVS, you may not understand all of these features. And if you're not familiar with version control at all, your eyes may glaze over unless you first read Chapter 2, Basic Concepts, in which we provide a gentle introduction to version control in general.

Subversion provides:

Svn repository

Repository Structure

Svn repository as itself on disk

In a repository you will find a few folders and files

conf
   A directory containing repository configuration files.
dav
   A directory provided to Apache and mod_dav_svn for their private housekeeping data.
db
   Where all of your versioned data resides. This directory is either a Berkeley DB environment (full of DB tables and other things), or is an FSFS environment containing revision files.
format
   A file whose contents are a single integer value that dictates the version number of the repository layout.
hooks
   A directory full of hook script templates (and hook scripts themselves, once you've installed some).
locks
   A directory for Subversion's repository locking data, used for tracking accessors to the repository.
README.txt
   A file which merely informs its readers that they are looking at a Subversion repository.

You don't need to access those files, unless you are the repository's administrator. In this case you will edit the conf/snvserve.conf. Otherwise, all the data contained in the repository (files, folders...) are not visible as it is for CVS. To administrate the repository, you will have to use the svnadmin, svnlookup and svn tools. It is possible to add hooks scripts to manage some pre or post commit, or many other hooks.

Administration

create a repository

• svnadmin create path_to_repository

for instance:
   > cd /home/svn/
   > mkdir my_repo
   > svnadmin create my_repo

It will create the repository inside 'my_repo' by creating a few folders and files. There are 2 kinds of repository for subversion, one base on berkeley database (bdb), and one base of subversion's filesystem database (fsfs). By default, 'svnadmin create' will create a 'fsfs' repository, and we will use this default for our repository. (Using Berkeley db seems to lead to database corruption in some cases).

At this stage, the new repository (just created) contains no file, and the revision is 0. More information with: svnadmin help create

Importing into a repository

• svn import [PATH] URL

svn import e:\my_src\test file:///home/svn/my_repo/test 
if PATH is ommitted, it will use the current directory  '.'

How to access a svn repository ?

The Subversion architecture can help you figuring out how things are done: Svn architecture

A SVN repository can be published by many ways:

file:/// direct repository access (on local disk) 
    : direct access is pretty useful especially when you create, import your repository

svn:// using the svn server 
    : access via custom protocol to an svnserve server (Check xinet.d on linux).

svn+ssh:// using the svn+ssh server 
    : same as svn:// but through an SSH tunnel

http:// access via WebDAV protocol 
    : the apache server has to be configured to be Subversion-aware 
    :(Pretty useful to give access to your repository to the outside world.)

https:// 
    :	same as http://, but with SSL encryption.

Thus, if all those media are provided (configuration done), you will address the repository as following:

local: 
   file:///home/svn/my_repo
   
Via the svnserve (thanks to xinet.d for linux for instance using /home/svn/ as root directory) :
   svn://login@machine/my_repo
   
Same with ssh :  
   svn+ssh://machine/my_repo
   
And using webdav (with /svn/ aliases on the root folder for subversion repository) :
   http://machine/svn/my_repo

Checkout your working copy

• svn checkout URL or svn co URL

For instance
svn co svn://username@svn_svr_address/test/
svn co http://username@svn_svr_address/svn/test/

If you want to checkout only a sub folder 'trunk/src' of your repository, you can do 
   svn co svn://username@svn_svr_address/test/trunk/src
and if you want to precise the output path
   svn co svn://username@svn_svr_address/test/trunk/src my_src

If you want to checkout a revision 123:
svn co svn://username@svn_svr_address/test/ -r123

More information with: svn help checkout

Repository and revision

Global Revision Numbers

Unlike those of many other version control systems, Subversion's revision numbers apply to entire trees, not individual files. Each revision number selects an entire tree, a particular state of the repository after some committed change. Another way to think about it is that revision N represents the state of the repository filesystem after the Nth commit. When a Subversion user talks about revision 5 of foo.c, they really mean foo.c as it appears in revision 5. Notice that in general, revisions N and M of a file do not necessarily differ!

For CVS users who are used to per-file revisions numbers, you can have a look at Appendix A, Subversion for CVS Users.

Working with your working copy

• update and commit are very similar to CVS's update and commit
• Most svn commands don't use repository URIs, acting directly on a local working copy. The most general form of an svn command is:

svn <command> [<options>] [<targets>]
where targets is the list of files or directories to operate on, 
and options is an optional list of flags, in the familiar fashion of most Unix command-line interfaces. 
For most svn commands, targets defaults to the current directory,
and the command operates recursively on each directory it processes

• you have (among others) the following options which can be useful

  -q [--quiet]             : print as little as possible
  -N [--non-recursive]     : operate on single directory only

Working copy

In your working copy, you will have many .svn folder containing among other the base version of your files. This .svn area is similar to CVS folder with CVS, except it contains a lot of information. This allows you to do the status, diff, revert command without requiring the network. You should never edit the content of this .svn area. If you want to cancel an operation (like adding, deleting, or even changing a file), you should use the svn revert command.

Basic Work Cycle

Subversion has numerous features, options, bells and whistles, but on a day-to-day basis, odds are that you will only use a few of them. In this section we'll run through the most common things that you might find yourself doing with Subversion in the course of a day's work.

The typical work cycle looks like this:

• Update your working copy : svn update
• Make changes : svn add, svn delete, svn copy, svn move
• Examine your changes : svn status, svn diff, svn revert
• Merge others' changes into your working copy : svn update, svn resolved
• Commit your changes : svn commit

svn update

• svn update or svn up

Template:Nota

svn resolved

When you have a conflict on a file:

• either you revert your local change (using svn revert).
• or you can edit the file and resolve the conflict. When it is done, you have to do svn resolved on this file, otherwise you won't be able to commit your change later.

svn commit

• svn commit or svn ci
• you can pass the message using the -m "message" arguments (or the --message "...")

 svn ci the_file_a the_file_b -m "added the_file_a and the_file_b"

svn status

• Unlike CVS, svn status is useful (do not use svn update like you were doing with cvs)

Here are some typical cases

  L    abc.c               # svn has a lock in its .svn directory for abc.c
M      bar.c               # the content in bar.c has local modifications
 M     baz.c               # baz.c has property but no content modifications
X      3rd_party           # this dir is part of an externals definition
?      foo.o               # svn doesn't manage foo.o
!      some_dir            # svn manages this, but it's either missing or incomplete
~      qux                 # versioned as file/dir/link, but type has changed
I      .screenrc           # svn doesn't manage this, and is configured to ignore it
A  +   moved_dir           # added with history of where it came from
M  +   moved_dir/README    # added with history and has local modifications
D      stuff/fish.c        # this file is scheduled for deletion
A      stuff/loot/bloo.h   # this file is scheduled for addition
C      stuff/loot/lump.c   # this file has conflicts from an update
R      xyz.c               # this file is scheduled for replacement
    S  stuff/squawk        # this file or dir has been switched to a branch

• svn status prints five columns of characters, followed by several whitespace characters, followed by a file or directory name. Columns :

1. status of a file or directory and/or its contents.
2. status of a file or directory's properties
3. show whitespace or an L which means that Subversion has locked the item in the .svn working area
4. show whitespace or a + which means that the file or directory is scheduled to be added or modified with additional attached history
5. show whitespace or an S. This signifies that the file or directory has been switched from the path of the rest of the working copy (using svn switch) to a branch

• The codes for the 1st column are listed here :

M               44        23    sally     README
                44        30    sally     INSTALL
M               44        20    harry     bar.c
                44        18    ira       stuff
                44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
                44        21    sally     stuff/things
A                0         ?     ?        stuff/things/bloo.h
                44        36    harry     stuff/things/gloo.c

M      *        44        23    sally     README
M               44        20    harry     bar.c
       *        44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
A                0         ?     ?        stuff/things/bloo.h
Status against revision:   46

Examing History

svn log

Shows you broad information: log messages attached to revisions, and which paths changed in each revision.

• Because Subversion allows you to move and copy files and directories, it is important to be able to track path changes in the filesystem, so in verbose mode, svn log will include a list of changed paths in a revision in its output:

svn diff

Shows you the specific details of how a file changed over time.

• compare your working files to the cached “pristine” copies in the .svn area

• your working copy is compared to the specified revision in the repository

• the two revisions are directly compared

• You can also compare the file directly from the repository (without having a working copy)

svn cat

This is used to retrieve any file as it existed in a particular revision number and display it on your screen.

svn list

Displays the files in a directory for any given revision.

• Using -v or --verbose, you get detailed list

Branches and Tags

As mention before, SVN differs from CVS for the revision number system. The revision number is global to the repository, each atomic commit will incremente the global revision.

Then a revision N describe the state of the full repository. The result of svn status -v will show the current revision of the files, and also the revision number of the last commit occurred on each file.

... NEED TO COMPLETE THIS PART ... A branch or a tag, is no more than a copy in the repository of a folder. So this operation is very cheap, this is just a matter of saying this tags is on revision N . ... NEED TO COMPLETE THIS PART ...

Repository layout

We saw than a branch or a tag is technically the same idea. But let's adopt the convention that

• a branch may contains commit
• a tag will not contains commit, it is just used to "tag" or to give a "name" to a revision of the repository

Then here is a recommended layout for your repository

/trunk      # for the HEAD 
/branches   # for the various branches, versions
/tags       # for the tags

Trunk will contain the current development branch (alias HEAD), then 'branches' will contain for instance Eiffel_57, Eiffel_58, but can also contain a branch for user, since this is cheap operation, let's do it (You can always delete your branch after).

Here are the steps to create this kind of layout easily:

cd /home/username/SvnDir/repo
mkdir example
svnadmin create example/
svn mkdir file:///home/username/SvnDir/repo/example/project -m "created project"
svn mkdir file:///home/username/SvnDir/repo/example/project/trunk -m "created project/trunk"
svn mkdir file:///home/username/SvnDir/repo/example/project/branches -m "created project/branches"
svn mkdir file:///home/username/SvnDir/repo/example/project/tags -m "created project/tags"

Your repository has now fpr revision:  4
(you can do the same by checkouting a working copy, then add the folders and commit .. 
 this will do the same in only one commit)

You can check your repository with 

svnlook tree example/
 /
  project/
   trunk/
   branches/
   tags/

or even
svn list file:///home/username/SvnDir/repo/example/
  project/
svn -v list file:///home/username/SvnDir/repo/example/project
     3 username               Sep 30 09:14 branches/
     4 username               Sep 30 09:14 tags/
     2 username               Sep 30 09:13 trunk/

Creating a Branch

Nb: to have write access via svn:// please edit the example/conf/svnserve.conf, and change the text to
[general]
anon-access = write

There are two different ways to make a copy. We'll demonstrate the messy way first, just to make the concept clear. To begin, check out a working copy of the project's root directory, /project:

svn checkout file:///home/username/SvnDir/repo/example my_ex
or using the svn:// access protocol:
svn checkout svn://username@svn_svr_address/example my_ex
A    my_ex/project
A    my_ex/project/trunk
A    my_ex/project/trunk/src
A    my_ex/project/trunk/src/test.e
A    my_ex/project/trunk/Readme
A    my_ex/project/branches
A    my_ex/project/tags
Checked out revision 5.

Making a copy is now simply a matter of passing two working-copy paths to the svn copy command:

cd my_ex/project
svn copy trunk branches/branch_username
svn status
A  +   branches/branch_username

In this case, the svn copy command recursively copies the trunk working directory to a new working directory, project/branches/branch_username. As you can see from the svn status command, the new directory is now scheduled for addition to the repository. But also notice the “+” sign next to the letter A. This indicates that the scheduled addition is a copy of something, not something new. When you commit your changes, Subversion will create /project/branches/branch_username in the repository by copying /project/trunk, rather than resending all of the working copy data over the network:

$ svn ci -m "Creating a private branch of /project/trunk."
Adding         project/branches/branch_username

Committed revision 6.

And now the easier method of creating a branch, which we should have told you about in the first place: svn copy is able to operate directly on two URLs.

svn copy svn://username@svn_svr_address/example/project/trunk \
          svn://username@svn_svr_address/example/project/branches/branch_username \
     -m "Creating a private branch of /project/trunk."

Committed revision 6.

There's really no difference between these two methods. Both procedures create a new directory in revision 6, and the new directory is a copy of /project/trunk.

Notice that the second method, however, performs an immediate commit. It's an easier procedure, because it doesn't require you to check out a large mirror of the repository. In fact, this technique doesn't even require you to have a working copy at all.

I would advice the second method, because if case of large folder to "branch", this will avoid copying all the files and folder in your working directory (indeed, often when you create a branch, it is for later or other).

Template:Nota

Working with Your Branch

getting the branch's version

Now that you've created a branch of the project, you can check out a new working copy to start using it:

svn checkout svn://username@svn_svr_address/example/project/branches/branch_username
A    branch_username/src
A    branch_username/src/test.e
A    branch_username/Readme
Checked out revision 6.

There's nothing special about this working copy; it simply mirrors a different directory in the repository. When you commit changes, however, other developers won't ever see them when they updates. Their working copy is of /project/trunk or others. Now you can use this working copy, as any other folder in your working copy. The global revision will incremente the same way, when you commit or other commit. If another user wants to use the branch_username , he can use the svn switch command.

for instance

cd my_ex/project/trunk
svn info
 Path: .
 URL: svn://username@svn_svr_address/example/project/trunk
 Repository UUID: e6f56783-ff01-0410-a399-a959a12a58d5
 Revision: 6
 Node Kind: directory
 Schedule: normal
 Last Changed Rev: 5
 Last Changed Date: 2005-09-30 09:20:13 -0700 (Fri, 30 Sep 2005)

svn switch svn://username@svn_svr_address/example/project/branches/branch_username
At revision 6.

svn info
 Path: .
 URL: svn://username@svn_svr_address/example/project/branches/branch_username
 Repository UUID: e6f56783-ff01-0410-a399-a959a12a58d5
 Revision: 6
 Node Kind: directory
 Schedule: normal
 Last Changed Rev: 6
 Last Changed Date: 2005-09-30 09:27:38 -0700 (Fri, 30 Sep 2005)

Nota: The Key Concepts Behind Branches

1. Unlike many other version control systems, Subversion's branches exist as normal filesystem directories in the repository, not in an extra dimension. These directories just happen to carry some extra historical information.
2. Subversion has no internal concept of a branch—only copies. When you copy a directory, the resulting directory is only a “branch” because you attach that meaning to it. You may think of the directory differently, or treat it differently, but to Subversion it's just an ordinary directory that happens to have been created by copying.}}

Merging

• Merging is more or less applying some difference to a working copy. Thus, you always merge on a working copy.

Quick examples from

• http://svnbook.red-bean.com/en/1.1/ch04.html
• http://svnbook.red-bean.com/en/1.1/ch04s03.html#svn-ch-4-sect-3.3

svn merge -r 343:344 http://svn.example.com/repos/calc/trunk my-calc-branch
U   my-calc-branch/integer.c

svn merge http://svn.example.com/repos/branch1@150 \
           http://svn.example.com/repos/branch2@212 \
           my-working-copy
           
svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy

svn merge -r 100:200 http://svn.example.com/repos/trunk

Learn with an example

Create the repository

repository: file:///home/username/SvnDir/repo/example
export MYSVN_DIR=/home/username/SvnDir
(change this value to your own path)

cd $MYSVN_DIR/repo
svnadmin create example/
export MYSVN_URL=file://$MYSVN_DIR/repo/example
(change this value to use the correct url, here we use local access using file:/// ..)

Fill the repository with test files

Create the basic structure .. trunk and branches
svn mkdir $MYSVN_URL/project -m "created project"
svn mkdir $MYSVN_URL/project/trunk -m "created project/trunk"
svn mkdir $MYSVN_URL/project/branches -m "created project/branches"

Add folders and files using a working copy
cd $HOME
mkdir test_svn
cd test_svn
svn checkout $MYSVN_URL/project/trunk proj
mkdir proj/src
cd proj/src
mkdir listing
ls > listing/ls.txt
mkdir dating
date > dating/date.txt
cd ..
svn add src
svn ci -m "adding src files"

Now we will create a branch for src

We want to create a branch
if you want to branch all the trunk
svn copy $MYSVN_URL/project/trunk $MYSVN_URL/project/branches/v1 -m "creating branch for src"

And if you want only the branch the "src" folder (and sub folders)
svn mkdir $MYSVN_URL/project/trunk/src $MYSVN_URL/project/branches/v1 -m "mkdir project/branches/v1"
svn copy $MYSVN_URL/project/trunk/src $MYSVN_URL/project/branches/v1/src -m "creating branch for src"

cd $HOME/test_svn/proj

if you look at the repository :
svnlook tree $MYSVN_DIR/repo/example --show-ids
/ <0.0.r5/601>
project/ <1.0.r5/418>
 trunk/ <2.0.r4/981>
  src/ <4.0.r4/810>
   dating/ <5.0.r4/274>
    date.txt <6.0.r4/84>
   listing/ <7.0.r4/596>
    ls.txt <8.0.r4/407>
 branches/ <3.0.r5/198>
  v1/ <2.1.r5/0>
   src/ <4.0.r4/810>
    dating/ <5.0.r4/274>
     date.txt <6.0.r4/84>
    listing/ <7.0.r4/596>
     ls.txt <8.0.r4/407>

Modify some files in your working copy

(which is for now the HEAD/trunk version)

cd $HOME/test_svn/proj/
date >> src/dating/date.txt
ls > src/listing/proj.txt

svn status
M      src/dating/date.txt
?      src/listing/proj.txt

svn diff
Index: src/dating/date.txt
===================================================================
--- src/dating/date.txt (revision 4)
+++ src/dating/date.txt (working copy)
@@ -1 +1,2 @@
 Mon Oct 17 13:54:45 CEST 2005
+Mon Oct 17 13:58:43 CEST 2005

Let's commit our nice changes

svn commit -m "added new date, and new listing"
Sending        src/dating/date.txt
Transmitting file data .
Committed revision 6.

Oups I forgot to add the new file
svn add src/listing/proj.txt
A         src/listing/proj.txt

svn commit -m "added new listing"
Adding         src/listing/proj.txt
Transmitting file data .
Committed revision 7.

Let's change the log's message of revision 6

(since I first forgot to add the new listing)

Warning: to be able to change the log of a revision, you must enable the pre-revprop-change hook on the repository.

cd $MYSVN_DIR/repo/example/hooks
cp pre-revprop-change.tmpl  pre-revprop-change
chmod a+x pre-revprop-change

now we can change logs ... (be careful, there is no revision of svn:log property changes)

echo "added new date" > /tmp/newlog_r6
svnadmin setlog $MYSVN_DIR/repo/example -r 6 /tmp/newlog_r6

or using

svn propset -r 6 --revprop svn:log  "added new date" $MYSVN_URL/project/trunk/src/dating/date.txt
property 'svn:log' set on repository revision 6

cd $HOME/test_svn/proj
svn log -r6 
------------------------------------------------------------------------
r6 | username | 2005-10-17 14:02:22 +0200 (Mon, 17 Oct 2005) | 1 line

added new date

Switch to branch working copy

Ok now, we have a branch "v1", and a main branch "trunk" with new commits If we want to work on the branch itself

You can checkout the branch and work on it:
cd $HOME/test_svn
svn checkout $MYSVN_URL/project/branches/v1 proj_v1
A    proj_v1/src
A    proj_v1/src/dating
A    proj_v1/src/dating/date.txt
A    proj_v1/src/listing
A    proj_v1/src/listing/ls.txt
Checked out revision 7.

cd proj_v1
svn info | grep URL
URL: file:///home/username/SvnDir/repo/example/project/branches/v1

svn log
------------------------------------------------------------------------
r5 | username | 2005-10-17 14:28:42 +0200 (Mon, 17 Oct 2005) | 1 line

creating branch for src
------------------------------------------------------------------------
r4 | username | 2005-10-17 14:28:32 +0200 (Mon, 17 Oct 2005) | 1 line

adding src files
------------------------------------------------------------------------
r2 | username | 2005-10-17 14:28:23 +0200 (Mon, 17 Oct 2005) | 1 line 

created project/trunk
------------------------------------------------------------------------

The other way to do, working on the same file, is just to switch your current working copy to the branch version
cd $HOME/test_svn/proj
(this directory contains, the trunk version)
svn info | grep URL
URL: file:///home/username/SvnDir/repo/example/project/trunk

svn switch $MYSVN_URL/project/branches/v1
U    src/dating/date.txt
D    src/listing/proj.txt
Updated to revision 7.

As you noticed, it will put our working copy in the "v1" branche state
svn info | grep URL
URL: file:///home/username/SvnDir/repo/example/project/branches/v1

And let's merge the changes

• Now, let's merge one change from the trunk into this branch "v1", for that, as previously precised, you need a working copy of the branch "v1" (to patch the diff into this branch)

at this point, we switched the $HOME/test_svn/proj into branch "v1", so "proj" is a working copy of "v1"
remember, we added a new date into "dating/date.txt"

svn log $MYSVN_URL/project/trunk/src/dating/date.txt
------------------------------------------------------------------------
r6 | username | 2005-10-17 14:30:20 +0200 (Mon, 17 Oct 2005) | 1 line 

added new date
------------------------------------------------------------------------
r4 | username | 2005-10-17 14:28:32 +0200 (Mon, 17 Oct 2005) | 1 line

adding src files
------------------------------------------------------------------------

svn diff -r5:6 $MYSVN_URL/project/trunk/src/dating/date.txt
Index: date.txt
===================================================================
--- date.txt    (revision 5)
+++ date.txt    (revision 6)
@@ -1 +1,2 @@
 Mon Oct 17 14:28:30 CEST 2005
+Mon Oct 17 14:29:37 CEST 2005

At this point, we could save this diff into a patch file, and patch the branch copy.
Or simply using the same usage as "svn diff" command, we can directly merge the difference

cd $HOME/test_svn/proj
svn merge -r5:7 $MYSVN_URL/project/trunk/src/dating/date.txt src/dating/date.txt
U    src/dating/date.txt

svn st
M      src/dating/date.txt

Then, we simply need to commit, or revert if you finaly don't want to merge
svn commit  src/dating/date.txt -m "merge HEAD into branch v1"
or
svn revert src/dating/date.txt

Template:Nota

if you want to merge all differences from "project/trunk/src" into "v1/src"
you can do:
cd $HOME/test_svn/proj
svn merge -r5:7 $MYSVN_URL/project/trunk/src src

Now, let's switch back to the trunk copy:
svn sw $MYSVN_URL/project/trunk
A    src/listing/proj.txt
Updated to revision 8.

Need to be documented

svn:externals properties

• for now check this http://svnbook.red-bean.com/en/1.0/ch07s03.html

client side

config file, and auto-props

• for now check this http://svnbook.red-bean.com/en/1.0/ch07.html#svn-ch-7-sect-1.3.2