Subversion User tutorial

What do you need?

  • a subversion client (in this example TortoiseSVN, but the principle stays the same)
  • your user account (first.lastname)
  • your SVN password (can be different from this site's password)
  • the subversion repository URL

Repository URL

The repository URL is the path of the svn repository on the subversion server.

For example, the IVAC2 FIRDEF repository URL can be:

Depending on your team, you have read or read/write access to specific parts of the repository tree.

Checking out a working copy

This is the very first thing you need to do if you want to checkout a fresh copy of the repository

  • Select a directory in windows explorer where you want to place your working copy
  • Right click to open the directory context menu

  • select the command SVN Checkout…
  • the checkout dialog will appear:

  • URL of repository: fill in the URL of the repository you want to checkout
  • Checkout directory: your local directory where you want to put the files
  • Checkout Depth: Fully recursive (default)
  • Revision: HEAD
  • press the OK button to proceed
  • ( you will get a popup window asking to approve a certificate (https) - approve the certificate )
  • you should see now that files are downloaded into the working copy directory

Update your working copy with changes from others

Periodically, you should ensure that changes done by others get incorporated in your local working copy. The process of getting changes from the server to your local copy is known as updating. Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update:

  • select the root folder of your working copy (or .. select the files and/or directories you want to update)
  • Right click to open the file context menu

  • select the command SVN Update…

When the update is complete, the progress dialog shows a summary of the number of items updated, added, removed, conflicted, etc. below the file list. This summary information can be copied to the clipboard using Ctrl+C.

If you get any conflicts during an update (this can happen if others changed the same lines in the same file as you did and those changes don't match) then the dialog shows those conflicts in red. You can double click on these lines to start the external merge tool to resolve the conflicts.

The standard Update command has no options and just updates your working copy to the HEAD revision of the repository, which is the most common use case. If you want more control over the update process, you should use TortoiseSVN → Update to Revision… instead. This allows you to update your working copy to a specific revision, not only to the most recent one.

Multiple files/folders

If you select multiple files and folders in the explorer and then select Update, all of those files/folders are updated one by one. TortoiseSVN makes sure that all files/folders which are from the same repository are updated to the exact same revision! Even if between those updates another commit occurred.

Local file already exists

Sometimes when you try to update, the update fails with a message to say that there is already a local file of the same name. This typically happens when Subversion tries to checkout a newly versioned file, and finds that an unversioned file of the same name already exists in your working folder. Subversion will never overwrite an unversioned file - it might contain something you are working on, which coincidentally has the same filename as another developer has used for his newly committed file.

If you get this error message, the solution is simply to rename the local unversioned file. After completing the update, you can check whether the renamed file is still needed.

If you keep getting error messages, use TortoiseSVN → Check for Modifications instead to list all the problem files. That way you can deal with them all at once.

Committing your changes to the repository

Sending the changes you made to your working copy is known as committing the changes. But before you commit you have to make sure that your working copy is up to date. If not, there is a risk that you will get a conflict with committed files by team members.

To update your working copy to the latest version:

  • Right click to open the file context menu

  • select the command SVN Update…

To see which files have changed locally or on the server:

  • Right click to pop up the context menu and select the command TortoiseSVN

  • select the command Check for Modifications…

If your working copy is up to date and there are no conflicts, you are ready to commit your changes:

  • Select the root folder of the local working copy ( or .. any file and/or folders you want to commit)
  • Right click to pop up the file context menu

  • select the command SVN Commit…

The commit dialog will show you every changed file, including added, deleted and unversioned files. If you don't want a changed file to be committed, just uncheck that file. If you want to include an unversioned file, just check that file to add it to the commit.

Be sure to enter a log message which describes the changes you are committing. This will help you and other team members to see what happened and when, as you browse through the project log messages at a later date. The message can be as long or as brief as you like;

note: we strongly recommend that you use English - please remember that not only you but also we - Terminal2 Solutions - must be able to understand the work you have done.

commit files or directories?

When you commit files, the commit dialog shows only the files you have selected. When you commit a directory the commit dialog will select the changed files automatically. If you forget about a new file you created, committing the directory will find it anyway. Committing a directory does not mean that every file gets marked as changed; It just makes your life easier by doing more work for you.

unversioned files

Unversioned files are files which have not been added to the repository.

If you want to add new files to the _repository_ do the following:

  • Select any file and/or folders you want to add to the repository
  • Right click to pop up the file context menu and select the command TortoiseSVN

  • select the command Add…

repairing external renames

Sometimes files get renamed outside of Subversion, and they show up in the file list as a missing file and an unversioned file. To avoid losing the history you need to notify Subversion about the connection:

  • select both the old name (missing) and the new name (unversioned)
  • Right click to pop up the context menu and select the command TortoiseSVN
  • select Context Menu…
  • select the command Repair Move…

Adding (new) files to the repository

If you want to add new files to the _repository_ do the following:

  • Select any file and/or folders you want to add to the repository
  • Right click to pop up the context menu and select the command TortoiseSVN
  • select the command Add…

note

  • Do not use spaces or special characters in filenames! Special characters such as spaces are not supported on other platforms than Windows.
  • renaming files in subversion is not easy - think twice before adding a new file.

Checking out an older version

If ever you need to return to an older version, you can checkout a separate copy of your FIR definition

  • Select a directory in windows explorer where you want to place your working copy
  • Right click to pop up the file context menu

  • select the command SVN Checkout…
  • the checkout dialog will appear:

  • URL of repository: fill in the URL of the SVN repository
  • Checkout directory: your local directory where you want to put the files
  • Checkout Depth: Fully recursive (default)
  • Revision: revision number to checkout
  • press the OK button to proceed

caution

If you update a file or folder to a specific revision, you should not make changes to those files. You will get “out of date” error messages when you try to commit them! If you want to undo changes to a file and start afresh from an earlier revision, you can rollback to a previous revision from the revision log dialog.

Resolving conflicts

A file conflict occurs when two or more developers have changed the same few lines of a file. As Subversion knows nothing of your project, it leaves resolving the conflicts to the developers. Whenever a conflict is reported, you should open the file in question, and search for lines starting with the string < < < < < < <.

The conflicting area is marked like this:

<<<<<<< filename
  your changes
=======
  code merged from repository
>>>>>>> revision

Also, for every conflicted file Subversion places three additional files in your directory:

filename.ext.mine

This is your file as it existed in your working copy before you updated your working copy - that is, without conflict markers. This file has your latest changes in it and nothing else.

filename.ext.rOLDREV

This is the file that was the BASE revision before you updated your working copy. That is, it the file that you checked out before you made your latest edits.

filename.ext.rNEWREV

This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD revision of the repository.

You can either launch an external merge tool / conflict editor with TortoiseSVN → Edit Conflicts or you can use any other editor to manually resolve the conflict. You should decide what the code should look like, do the necessary changes and save the file.

Afterwards execute the command TortoiseSVN → Resolved and commit your modifications to the repository. Please note that the Resolve command does not really resolve the conflict. It just removes the filename.ext.mine and filename.ext.r* files, to allow you to commit your changes.

If you have conflicts with binary files, Subversion does not attempt to merge the files itself. The local file remains unchanged (exactly as you last changed it) and you have filename.ext.r* files. If you want to discard your changes and keep the repository version, just use the Revert command. If you want to keep your version and overwrite the repository version, use the Resolved command, then commit your version.


Back to Subversion / Back to Index