Introduction to subversion


0.  The motivation of version control

Version control systems (such as subversion) are designed to help
you log and control the series of modifications that are applied
to a project during its lifetime.  Rather than spawning multiple
copies of your work you can maintain one working copy and let
subversion keep track of all previous versions in a subversion
repository.  If you ever need to inspect an older version of
a file, subversion can get it for you.  If a new bug appears
you can ask subversion to show you the difference between the
old (working) project and the current broken one.

You can use subversion to synchronize files on multiple machines
and to collaborate with other developers.  When you check
a modification into the subversion repository it becomes available
to everyone with access to the repository, no need to exchange or
transfer files manually.


1.  Working with an existing project

In order to work with a project under version control you must
check out a copy from the repository.  The syntax is usually
something like this:

svn co svn://<server><path to repository><project name> <destination>

For example, if the project TheProject was handled by a subversion
repository on TheServer and the repository was located at /var/svn
on TheServer then you could use

svn co svn://TheServer/var/svn/TheProject TheProject

to check out a copy of TheProject in the directory TheProject inside
your current working directory.

You can now make any changes you like in your local copy of TheProject.
If you want to see what you've changed you can call

svn stat

which will print a list of modified and new files in your local copy.
For example, if you modified a file named "foo" and created a new
file named "bar", then svn stat might print:

? bar
M foo

If you want to check your changes to foo into the repository you should
call:

svn commit foo

A text editor will appear where you can (and should) write a summary of
the changes you made.  If you save the file then after you exit from
the editor subversion will check your modifications into the repository.
(If you don't save the modification summary subversion will give you some
options, among them the option of aborting the check in).

Subversion might complain that your files are out of date when you try
to check in your changes.  If this happens then you should call

svn update

to update your files.  This command will print a list of the files
being updated, which will look something like this:

U foo
U bar
C baz
U buz

This indicates that foo, bar, and buz were updated, and that there
was a "conflict" in the file named "baz".  Conflicts happen when
you and another developer both make modifications to a file and
subversion can't determine the correct way to merge your changes.
If subversion reports a conflict open the offending file and search
for a long string of '>' or '<' characters, which will accompany
the text causing the conflict.  Your modifications and the
modifications which were already in the repository will be shown.
Edit the offending file to resolve the conflict and try updating
again.

You should usually call svn update before you start working every
day.  This way your local copy of the project will never be very
far out of date.


Some notes on svn update and svn commit:
1.  You can list any set of files (space delimited) after
    either "update" or "commit".  Subversion will apply the command
    only to the files you list unless your list is empty,
    in which case subversion will apply the command to
    every item in your current directory.  (If you do this,
    update will ignore up to date files, and commit
    will ignore files which have not been modified).

2.  svn update will restore files which are present in the
    repository but not in your local copy.

3.  svn update will *not* automatically add files to the repository.

If you need to add files or directories to the repository use

svn add

followed by a space delimited list of files to add.  If you then
call "svn stat" you will see these files listed with the state
"A" like so:

$ svn add foo bar baz
$ svn stat
A foo
A bar
A baz
$

A subsequent call of svn commit will add the new files to the
repository.

You can also remove files from the repository by calling

svn remove

followed by a space delimited list of files to remove.  Again,
no changes are actually applied to the repository until you
call svn commit.

You can inspect the difference between your local copy of a file
and the most recent version in the repository by calling

svn diff

followed by the name of the file to inspect.  svn diff prints
a comparison in the same format as diff.  (See the man pages
for diff for more information).  If you want to let another
developer try out a set of changes before you commit them to
the repository (code reviews are typically a good idea) you can
use the following trick.

svn diff > myRevisions.patch

If you want myRevision.patch to be more human readable use the
U option to provide some context:

svn diff -U 30 > myRevisions.patch

You can send the patch file to your colleague who can then use the
command

patch < myRevisions.patch

to apply your changes.  This is especially nice when you've
modified multiple files because all the modifications can be
recorded with a single call of svn diff and then applied
with a single call to patch.


2.  Creating and maintaining new projects with subversion
IOU