SVN tutorial for EPFL

=== Introduction ===

 
1. What is SVN?
 
SVN is a source control system: a system that can be used to manage a directory tree storing source code, documentation or other files (this is called a repository), offering the following main features:
 
* Changes (commits) can be made from multiple computers, and are shared easily (no need to send files by e-mail etc.);
* Changes are tracked automatically for all the files, and all the previous versions of all the files are saved in the repository history (no need to make manual backups; easy to revert or compare to an earlier version of a file when a change breaks something);
* Each change is given a revision number, and saved in the history with a timestamp and the user who made the change;
* In addition to being stored on each developer's computer, the repository is also stored remotely in a central location (for EPFL, the svn.epfl.ch server).
 

2. The basic workflow

 
In most cases, you only need to perform the following operations:
 
* Creating a repository (done only once);
* Downloading the repository to your computer, called checking out a local copy (done only once);
* Working in the repository, by editing, creating or deleting files;
* Updating your local copy by downloading changes that may have been made by the other developers in the meantime; in case other people modified the same files you did, this is called a conflict and you will have to solve it by editing the file until it is correct;
* Uploading your changes, called committing.
 

=== Basic operations (Linux) ===

Creating a new repository

 
* Open https://svn.epfl.ch
* From the right menu, go to "New repository". 
* When asked about git, choose "I still want to create an SVN repository".
* Choose a name (no spaces or special characters), for example: smalltest
* Enter a description.
* You should see a message that the repository has been created successfully. You should also see the repository URL, for example https://svn.epfl.ch/svn/smalltest, and a command you can use to download it (starts with svn co).
 
Commands
 
# Downloading a local copy of a repository to your computer
# Run the command as indicated by https://svn.epfl.ch, for example:
svn co --username=mygaspar https://svn.epfl.ch/svn/smalltest
cd smalltest/trunk
 
# Display the current state of your local copy
svn status
 
# Add a new file to the repository
# Note: save all your files in smalltest/trunk
svn add path/to/file
 
# Example:
svn add main.cpp
 
# Display changes prepared to be committed
svn diff
 
# Update your repository before commit (download changes made by other people)
svn update
 
# Commit (upload your changes)
svn commit -m 'The commit message'
svn update
 
# Use informative messages, for example:
svn commit -m 'Created main file'
svn update
 
# Display the log
svn log
 
# Display the changes from a specific revision number
svn diff -c3
 

=== Solving conflicts ===

 
# When two people change the same line in the same file, svn update will show a message like this:
Conflict discovered in 'main.cpp'.
Select: (p) postpone, (df) diff-full, (e) edit, (r) resolved,
        (mc) mine-conflict, (tc) theirs-conflict,
        (s) show all options:
 
# Press p and 'Enter' (ignore the other options, they cause more problems than they solve). Now the file main.cpp will contain something like this:
<<<<<<< .mine
My changes.
=======
The other developer's changes.
>>>>>>> .r5
 
# You need to edit the file so that in the end it is clean, without any markers (<<<<, ====, >>>>).
# It might be useful to inspect the recent commit history for the file. To do this, run (replace 5 and 4 with the version numbers you need):
svn diff -c5 main.cpp
svn diff -c4 main.cpp
 
# Alternatively, you can inspect the files svn has created for you, named main.cpp.r4, main.cpp.r5, main.cpp.mine.
 
# Once you have resolved the conflicts in a file, run:
svn resolve --accept=working main.cpp
 
# Finally, you can commit
svn commit -m 'Changed blah blah blah, resolved conflicts'
 
# Tip: make your life easy and update often, so that you avoid having conflicts. Also, inform in advance the other person about what you want to change, so that you do not both work on the same thing at the same time.
 

=== Solving some common problems ===

# Svn shows the message:
"Password for '(null)' GNOME keyring"
 
# then it shows the error:
svn: OPTIONS of 'https://svn.epfl.ch/svn/smalltest': authorization failed: Could not authenticate to server: rejected Basic challenge (https://svn.epfl.ch)
 
# A simple workaround is to run:
rm ~/.gnome2/keyrings/login.keyring
 

=== SVN vs. Git ===

 
# If you are familiar with git, you can use it instead of SVN, or you can also use it as an SVN client. See https://wiki.epfl.ch/git