Subversion is, like CVS, a tool for managing source files. It keeps track of your work and changes in a set of files and directories. It allows developers and writers to collaborate. The common area is the repository, where all files are stored. The repository can reside on a local directory, but it is usually accessible over a network.

Working with Subversion involves the following steps:

For more information, see [svn]. Although you can work with Subversion on Windows, this guide is targeted to Linux.

For your daily work, use the svn command. It knows --help. You can even get the options for a certain Subversion command, for example svn update --help. This prints the available options for the update procedure of Subversion.

A typical work cycle looks like this (taken from the Subversion Book):

Before you start, you should know about Subversion:

There are some packages that are essential or might be useful if you work with Subversion:

The configure check needs additional packages:

Before you work with Subversion, you should check whether all relevant packages are installed. Proceed as follows:

The first step when working with Subversion is to check out your files from a repository. This step must be done only once, but it is essential.

From time to time, you should update your working directory to get changes others have made:

The next action depends on the status of the file. If you have modified a file, you probably want to check in your changes. If your file is added or removed, a commit would solve this problem. For files with a conflict, resolve the conflict before handing it to Subversion.

Before you checking in your changes, it is always a good idea to take a look at exactly what you have changed. Subversion prints the status of your working directory with svn status. The output of this commands contains six columns:

If you do not know, which changes did you make, try svn diff. You can diff your files even if you are not online—Subversion holds a copy of the last revision.

To get the differences between your current, modified file and the last revision, run:

svn diff foo

To get the difference between your working copy and the trunk revision, run:

svn diff

However, you can also diff between revisions that are already checked in. Subversion knows the following revision keywords:

Here are some examples (taken from the Subversion Book):

svn diff --revision PREV:COMMITED foo
# shows the last change committed to foo

svn log --revision HEAD
# shows log message for the latest repository commit

svn diff --revision BASE:HEAD
# shows all commit logs since you last updated

This section is probably useful to SUSE employees only. However it can be informative for other as well.

Tags are “snapshots of a project in time”. To create a tag for our books, enter:

svn copy $SVNROOT/trunk/books/en \
         $SVNROOT/tags/books/en/TAG_NAME

Replace TAG_NAME with an appropriate name.

If you need to add new files or remove old files, use the commands svn add and svn remove.

To add a new file, enter:

svn add NEW_FILE

To delete an old file, enter:

svn remove OLD_FILE

If you are finished with adding or deleting files, commit your changes:

svn commit

Unless CVS, Subversion can copy a file and retain its history. Subversion copies a file from a source to a destination. There are four possibilities where the source and destination are located:

In general, you can copy a file A to a file B with the following command:

svn copy A B

After a svn status you can see the new file B is scheduled for addition. It looks like if you have added and removed a file.

To rename or move a file from a source to a destination, use svn move or svn rename (the two commands are the same, they are just synonyms.) For example:

svn rename X Y

This renames X to Y. After a svn status you can see the renamed file is scheduled for addition.

After you copied or renamend the files, you must check in if you want to save it in the repository:

svn ci -m"Copied file" A B
svn ci -m"Renamend file" X Y

If you want to discard your local changes, you can use the svn revert command. It reverts any local changes to a file, directory or any property changes. It can revert scheduling operations like addition, renaming or deletion only. For example:

svn add foo
svn revert foo

svn rename foo bar
svn revert foo bar

svn delete foo
svn revert foo

	No targets to svn revert is a protection
The Subversion book [svn] says: “If you provide no target to svn revert, it will do nothing—to protect you from accidentally losing changes in your working copy, svn revert requires you to provide at least one target.”

Conflicts occur only when all of the following conditions are met:

If you update your working directory and Subversion detects a conflict, it changes the contents of the file and inserts “conflict marks”:

<<<<<<< .mine
  This is a nice line.
=======
  This is a short line.
>>>>>>> .r4

You have the following possibilities:

To resolve the conflict, proceed as follows:

After you have changed, added, or removed files in your local working directory, you have to commit your files back to the Subversion repository:

	Checking in is always a good Idea
Do not hesitate to check in your changes. If you have checked your changes back in our Subversion repository, you are protected from hard disk crash or other loss of data. In other words: Subversion is your backup system. Please make sure that you always check in valid XML.

If you want to see the history of your files use the svn log command. For example:

svn log xml/help.xml
------------------------------------------------------------------------
r2913 | tom | 2005-12-19 13:34:17 +0100 (Mo, 19 Dez 2005) | 1 line

docmanager: Property »doc:status« set to »proofed«
------------------------------------------------------------------------
r2912 | tom | 2005-12-19 13:33:19 +0100 (Mo, 19 Dez 2005) | 2 lines

worked on comments

------------------------------------------------------------------------
r2877 | rwalter | 2005-12-18 18:52:07 +0100 (So, 18 Dez 2005) | 1 line

docmanager: Property »doc:status« set to »comments«
------------------------------------------------------------------------
r2876 | rwalter | 2005-12-18 18:49:53 +0100 (So, 18 Dez 2005) | 3 lines

proofing and comments
...

It is more convenient to pipe it to less to browse a long history:

svn log xml/help.xml | less

Quit with q.

Sometimes you need to restore an old revision from the Subversion repository. Do the following: