Overview

Subversion (SVN) is a version control system that is used to maintain and share the computer code (or any plain text documents, e.g. LaTex), save and retreve older versions etc.

Subversion is an open source project maintained by the Apache Foundation: Subversion Project Page.

Refer to the following free book for full authoritative documentation for Subversion:

Basic Subversion commands

Most commands can be abbreviated, e.g. checkout = co, update = up and commit = ci.

For example, to update the current working directory from the server use

svn up

On the Microsoft Windows platform, the TortoiseSVN program provides an easy to use graphical user interface. For example, the update command works like this:

img/tortoise.png

Checkout/update/commit/diff

  • Get things from the server for the first time (checkout): 

    svn --username your_username checkout https://path_to_repository

  • Gets new things and updates from the server (update): 

    svn update

  • Save things to the server (commit): 

    svn commit  optional_file_name -m "commit message, any text described what has been done"

  • Add file to subversion repository: 

    svn add file_name

    or

    svn commit file_name -m "commit message"

  • Remove file from subversion while keeping the local file: 

    svn delete --keep-local file_name

  • Checks if any updates that are not commited (status): 

    svn status

  • Checks if there is any difference between the server and my files 

    svn diff

  • See differences with colours (Note: You need to have colourdiff installed!) 

    svn diff optional_file_name --diff-cmd=colordiff

  • See difference between specific two versions of a file: 

    svn diff -r old_file_revision_number:new_file_revision_number file_name

  • See differences more visually on Linux with "Meld Diff Viewer" (Note: You need to have meld installed!). 

    meld file_name

  • See difference between specific file versions and look at this in meld 

    svn diff -r  old_file_revision_number:new_file_revision_number file_name --diff-cmd='meld'

  • Looking at the 16 last log entries: 

    svn log --limit 16

Directories/branches

  • Making a new directory (mkdir): 

    svn mkdir https://path/to_new_folder_name

  • Making a branch (or copy a single file across folders): 

    svn copy https://old_full_path  https://new_full_path -m "commit message"

  • Moving from one folder to the other (move): 

    svn mv https://old_full_path  https://new_full_path -m "commit message"

Merge across branches

  • Merge from from_this_uri to local (merge): 

    svn merge from_this_uri

Revert/cleanup

  • Revert to the last version of the file that is saved on the server, overwrite any local changes (revert): 

    svn revert file_name

  • Revert the whole current directory 

    svn revert -R .

  • If something goes wrong clean up with this command (cleanup): 

    svn cleanup

Amend commit message

  • Change (amend) the commit message for a commit that has already been sent to the server (this functionality must be supported by the Subversion server). An example below sets a new commit message for rev. 4200: 

    svn propset -r 4200 --revprop svn:log 'New commit message'

Revert to previous revision (scrap and go back)

Revert to a previous revision, e.g. r103 scrapping the whole line r104:r106. Then the next commit r107 will originate from r103:

img/svn-back.svg

  • revert to r103 and scrap all after r103 and continue 

    svn merge -r HEAD:103 .

Relocate server

  • Switch (migrate) to a differen Subversion server (relocate): 

    svn relocate --username your_user_name https://new_repository_url_address/

Tags/keywords

Subversion can place keywords into the versioned files, that is dynamic information about the file itself, such as the revision number, file name, revision date etc.

Command to add svn keywords to a file:

svn propset svn:keywords "Id Date Revision HeadURL LastChangedDate" file_name

  • Example Id: In file, add this line (it will change after commit to reflect the actual information about the file): 

    ! $Id: svnref.adoc 16698 2024-11-04 15:52:01Z sbu062 $

  • Example Revision: In Fortran file (optional), this line will keep the revision tag and could be printed to outputs to make it clear exactly what model version that generated it: 

      character(len=*), parameter :: SVN_VERSION_STRING = "$Revision: 16698 $"

Command to request default locking of a file (usually a binary file):

svn propset svn:needs-lock "true" file_name

Commands to set specific MIME type for a file:

svn propset svn:mime-type "application/vnd.oasis.opendocument.text" file_name

Any arbitrary properties can be set

svn propset copyright '(c) 2006 Red-Bean Software' code.c

also from a file

svn propset license -F /path/to/LICENSE code.c

Show properties for a file:

svn proplist FILE

Show properties for a file with their content

svn proplist --verbose FILE

Edit property value

svn propedit copyright code.c

Set properties on commit

svn commit -m "Message ..." --with-revprop "test-results=all passing"

For more details see Keyword Substitution.

Password caching on server systems

The new versions of Subversion go away from insecure password caching in plain text and should use encrypted storage with standard OS keychain (e.g. Gnome on Linux). But on many servers, keychain is not installed or available or configured. A workaround is to use GPG as secure password storage.

If you have already have GPG configures, go to Step 2.

Step 1 Configure GPG

Create a gpg key for you with this your email using this command:

This is necessary to store encrypted password for svn in the gpg keystore.

Add gpg-agent that manages password store to your .bashrc configuration file (standard shell config)

Logout from the system and login back. Now the gpg-agent is managing the passwords in an encrypted store. To check if gpg agent is configured issue this command:

The result should be something like this:

/run/user/1000/gnupg/S.gpg-agent::

If gpg-agent is not started automatically, add

to .bashrc config to start it.

Step 2 Configure Subversion to use GPG store for passwords

To enable svn to get your password from the gpg-agent, change the default configuration in .subversion as follows:

File ~/.subversion/config ::
password-stores = gpg-agent
store-passwords = yes
File ~/.subversion/servers
store-passwords = yes

From now on the Subversion client will use gpg-agent to store the password. GPG will therefore ask for svn password on the next authentication request and save it in an encrypted GPG store.

Interfacing Subversion with Git and Mercurial

The examples below assume the remote repositories are managed by GitHub and BitBucket. The commands create and maintain Git/Mercurial mirrors for the Subversion project.

Git

This functionality requires git-svn.

  1. Clone a (remote) Subversion repository to a local Git repository: 

    git svn clone --authors-file=path_to_authors.txt https://subversion_repo_path git_repo_name

  2. Set the (remote) GitHub repository path: 

    cd git_repo_name
git remote add origin git@github.com:user/github_repo.git

  3. Push the new repository git_repo_name to GitHub: 

    git push -u origin master

Mercurial

This functionality requires hgsubversion. See Interacting with Subversion for more details.

  1. Clone a (remote) Subversion repository to a local Mercurial repository: 

    hg clone --stupid --authors path_to_authors.txt svn+https://subversion_repo_path mercurial_repo_name

  2. Push the new repository mercurial_repo_name to Bitbucket: 

    cd mercurial_repo_name
hg push ssh://hg@bitbucket.org/bitbucket_repo_path

TEG: Theoretical Biology Group