ECE297
Communication and Design
Winter 2017
ECE297 Quick Start Guide
SVN
“We all have our time machines. Some take us back, they’re called memories.
Some take us forward, they’re called dreams.”
–Jeremy Irons
1
What is “Revision Control”?
Revision control (or version control, or source control) describes a software tool that manages the
source code of a project being developed by one or more programmers. To make our lives easier, a
revision control tool (like SVN) does the following:
• Creates a back-up of files that belong to a certain project.
• Maintains a history of changes (versions) made to any file and allows you to view/fetch any
revision.
• Allows multiple programmers to make changes to source files without getting in each other’s
way.
1.1
Why use Revision Control?
Real-world software projects have a lifetime of years or decades, and usually dozens of programmers
work on the same project which may grow to include millions of lines of code and thousands of
files. It becomes impossible to make changes to such large projects without revision control.
Even for your project in ECE297, you will soon find that using revision control allows you to
efficiently work on the same source code as a group and effortlessly keep track of the changes you
make to your source code.
1.2
Why SVN?
There are many revision control tools out there like Git, Perforce and CVS. We are using SVN (full
name: “Apache Subversion”) because it is widely used, easy to understand, powerful and free!
2
How does SVN work?
SVN keeps all your files in a central repository. You can interact with the repository to grab a
version of the files and create a working copy; svn checkout is the command to grab a local copy.
Page 1 of 1
Checkout of a repository happens only once at the very beginning of working on
a project. Afterwards, use update to get latest changes from a repository.
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
7/8/2014
A working copy is a local version of the files in the repository. To make changes to your projects
you can modify/add/delete files in your working copy. After that you can run the svn commit
command to create a revision in the repository.
Page 1 of 22
ECE297
Communication and Design
Page 1 of 1
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
Winter 2017
Every time you commit your modified files to a repository you create a version
of the project (revision). You can go back to this revision anytime using the
update command or compare revisions using diff.
7/8/2014
Repository
svnadmin ...
Commands to create and
manage the repository
r1
svn checkout
First time download
of repository files
r2
r3
r4 (HEAD)
svn import
First time upload of
project into repository
svn commit
svn update
Create a new revision in
repository with changes in
working copy
Update working
copy to a revision
You
Working copy
svn add/delete
Mark a local file to be added/
removed to the repository on
the next commit
svn log
View commit log
User 1
User 2
Working copy
Working copy
Figure 1: SVN overview.
Figure 1 shows an overview of how SVN works and some of the most common commands. To
create/manage a repository there are special administrative commands – you will only be using
svnadmin create throughout this course. Note that repositories can either be created on a server
or on your local computer.
Page 1 of 1
svnadmin commands are used to manage the repository; for example svnadmin
create sets up and creates the repository.
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
7/8/2014
Once a repository is created, the next thing to do is to svn checkout the repository. This
fetches a copy of the files in the repository and puts them in a local directory. It also adds setting
files to the directory so that SVN commands can be executed on your working copy in that directory.
Every user that will be working on the same project should checkout a working copy of the
repository. Your working copy is the version of the project on which you will be working. Changes
you make to your working copy are not automatically visible to other developers on the project;
for others to see your changes you must send updates back to the repository. When you are happy
with some changes you have made to your working copy, you use a svn commit to upload files to
the repository - a commit creates a new revision r1, r2, r3, etc. To see changes other developers
have made to the repository, you use svn update to download changed files from the repository
Page 2 of 22
ECE297
Communication and Design
Winter 2017
and place them in your working copy. When you create a new file in your working directory it
is not automatically placed under revision control, nor does it become part of your working copy
until you invoke svn add. Note that SVN also supports the command svn import that works in
the same way as svn add but is used initially to svn add the entire project to revision control
and svn commit all the changes as well. Additionally, if you delete a file it is not removed from
revision control unless you use svn delete.
Page 1 of 1
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
When adding or removing files in your working copy use SVN commands svn
add and svn delete to add/remove files from revision control. Changes are only
uploaded to the repository after running svn commit.
7/8/2014
With every svn commit, you write a commit message that is meant to concisely describe the
changes you made with this commit. The command svn log prints out a summary of these commit
messages; this includes the user who did the commit, the revision number, and the message supplied
with the commit.
3
SVN with Netbeans Command Reference
Since we will be using Netbeans IDE, it is easiest and most efficient to use the Netbeans SVN
plugin to manage your project files.
!
If you are not working on a lab computer, go to netbeans.org to install and
configure Netbeans with both the C/C++ and SVN plugins.
For the rest of this document we will go over the main SVN commands and how they can be
invoked through the Netbeans SVN plugin.
The book “Version Control with SVN” is a great reference for everything to do
with SVN, you can access it online at: svnbook.red-bean.com.
We will go through adding a “Hello World” C++ application to revision control with SVN. We
will start by looking at how to create a repository. Remember that the repository is where all your
files and their revisions live; it’s the central database that will have everything. First, we’ll create
a repository using svnadmin create.
Page 3 of 22
ECE297
Communication and Design
Winter 2017
svnadmin create repository name
1. Open a command terminal.
2. Create the directory in which you want to keep your repository – I called this “repos”.
3. Run the command svnadmin create repository name – I called my repository “svn tutorial”.
We now have an empty repository in the path “/nfs/ug/homes-0/m/mohamed/repos/svn tutorial”.
Note that you should always use the full path of the repository with SVN commands and never a
relative path. Also note that you can create the repository on a remote computer/server and access
it through network protocols like HTTP or SSH; however, in this case we are just creating it on
our local machine. Now let’s create a project in Netbeans and put it under revision control.
You should already have completed the Getting Started with NetBeans tutorial; if not go read
that document now. We want to add the source and Project code for the “hello” application we
created in Netbeans to the SVN repository that we just created. The very first time we add files
to a repository we use the svn import command. This command points to the project directory
we want to add and the repository path or url.
Page 4 of 22
ECE297
Communication and Design
Winter 2017
svn import [project path] repository path or url
1. Start NetBeans by typing netbeans & at a terminal prompt. Either open the ‘’hello” project you
created during the Getting Started with NetBeans tutorial, or use “File ⇒New Project ⇒C/C++
Application” to create a new project and write a small Hello World program in its main.cpp file.
Note that this project should not be in the “repos” directory you created above; the Project
Location (working directory) can be anywhere else in your filesystem.
2. Right click on the project and go to ⇒Versioning ⇒Import into Subversion Repository.
Page 5 of 22
ECE297
Communication and Design
Winter 2017
2. Enter the repository path in the dialog box prefixed with “file://”, then click next.
3. Specify the project directory you want to import and you must write a commit message. You
must always provide a message with any files you add/change in the repository – the first one
usually accompanies an import and later it comes with the commit command.
4. SVN will then figure out which files it needs to add to revision control – only source files or
configuration files such as Makefiles should be included. Compiled applications or output “.o” files
should never be added to a repository as they can always be regenerated. In our case, Netbeans
has already selected the relevant files so we can just click finish. We have now successfully added
the project to revision control with SVN.
Page 6 of 22
ECE297
Communication and Design
Winter 2017
Page 7 of 22
ECE297
Communication and Design
Winter 2017
The repository now has a copy of your files, and at this specific moment, they are identical to
the ones you are working on – your working copy. The next thing that you’ll probably be doing is
start working on your project. Our simple application isn’t much right now, it just prints “Hello
World!”. We’ll add another line to it so that it prints a second line saying “Hello SVN!” and make
a few other minor changes. Because we have modified our files, our working copy project is now
not the same as the project in the repository; it has this one extra line. If we have a large number
of files with many edits, it is useful to see which files are changed, added or deleted compared to
the repository – we can do that through the svn status command.
svn status
1. Right click on the project. You will find that the “Versioning” menu has now been replaced
with the “Subversion” menu. Clicking on it opens the available SVN commands. Click on “Show
Changes”.
2. A “Subversion” tab will show up listing which files were added, removed or modified. In the
following figure it only says that “main.cpp” was modified locally because that’s the only file we
touched.
Page 8 of 22
ECE297
Communication and Design
Winter 2017
Another useful command is svn diff. This command goes line-by-line and shows you which
lines in your source code have been changed/added/deleted.
svn diff
1. Go to the “Subversion” menu again by right clicking on the project and click “diff” this time.
You can compare your file to the HEAD revision or the BASE revision. The HEAD revision is the
latest revision in the repository while BASE is your working copy before you made any changes to
it. HEAD will be different to BASE if another user commits to the repository while you’re editing
your files.
2. The following tab opens up and shows a diff output for our local file compared to the HEAD
revision. The added line is highlighted in green, the modified line is shown in light blue, and any
deleted text is shown in red.
Page 9 of 22
ECE297
Communication and Design
Winter 2017
We now might want to add a new file. We’ll add a header file that defines the text we’re
printing.
svn add filename
1. To add a new file just do so normally in Netbeans. Right click on “Header Files” ⇒New ⇒C++
Header File. Netbeans also automatically invokes the svn add command to mark the new file for
addition on the next svn commit.
Page 10 of 22
ECE297
Communication and Design
Winter 2017
2. When we invoke the svn status command after adding the file (by right clicking on the project
and selecting “Subversion ⇒Show Changes”), it shows the new file “parameters.h” as locally new.
Additionally if we invoke the svn diff command it will list all the new and changed files as well.
Page 11 of 22
ECE297
Communication and Design
Winter 2017
Sometimes you will create new files in your project that you don’t want to put under revision
control. This applies for files that are generated from your program: for example if your program
prints data to a file. There is no value to putting such a file under revision control as it can be
regenerated using your application. Netbeans will want to include all new files in your commits by
default, so you have to explicitly svn ignore this file. You can always “unignore” a file later if you
choose that you need to have it backed up and shared. Note that you can only svn ignore new
files that are not yet added to your repository. To exclude a file that has already been committed
to your repository, use svn delete. Note that ignoring files from the command line is done using
svn propset (see the red book for more info).
svn ignore filename
1. Right click on the file you want to exclude from your repository and click “ignore”. This will
remove this file from all of your following commits.
Page 12 of 22
ECE297
Communication and Design
Winter 2017
At this point if we are happy with the changes we made we can now svn commit those changes
to the repository. This is how we communicate with the repository. The svn commit command
creates a new revision in the repository and uploads the new files and changes.
svn commit
1. Right click on the project then go to the “Subversion” menu and click on “commit”. The
following dialog box opens up and asks for a “commit message”. These messages are important
and you will lose style marks if you do not write meaningful commit messages. They are saved
with each revision and should concisely describe what changes you made in that revision.
Page 13 of 22
ECE297
Communication and Design
Winter 2017
Now the latest revision (HEAD revision) in the repository which we have just created matches
the working copy. If we invoke svn status or svn diff , it will report that there are no changes.
The “commit messages” we provided when we performed the initial svn import and with the
svn commit we just completed form a log that we can view at any time.
svn log
1. Right click on the project then go to the “Subversion” menu and click on “Search History”.
Then click “Search” in the window that opens up to view all log entries along with their revision
number. You can optionally filter the results.
Page 14 of 22
ECE297
Communication and Design
Winter 2017
Now that you have created your repository and started working on it, it is time to expand your
team! Assume that your friend Kevin wants to take a working copy of the repository so that he
can also work on the files. The first thing Kevin will do is svn checkout. By default, the svn
checkout command fetches the latest (or HEAD) revision from the repository, but you can also
manually specify which revision you want to get.
svn checkout repository path or url
1. After opening Netbeans, go to the menu and click Team ⇒Subversion ⇒Checkout.
2. Enter the repository path or url and click next.
Page 15 of 22
ECE297
Communication and Design
Winter 2017
3. The next dialog box asks if you want to only import certain folders of the repository and whether
you want a specific revision. If you leave the defaults, all the files in the HEAD revision will be
downloaded. You can also specify the local directory in which you want to save your working copy.
When you click “Finish”, Netbeans will automatically look for the project and ask you if you want
to open it.
Page 16 of 22
ECE297
Communication and Design
Winter 2017
Kevin will then start working on the project – he modified “main.cpp” to print one more line
and then he wants to run svn commit. Because Kevin is careful, he ran svn update first to make
sure that he is modifying the latest revision with his commit.
svn update [revision number]
1. After opening Netbeans, right click on the project and click Subversion ⇒Update ⇒Update
to HEAD. This updates your working copy to the latest revision in the repository. You can also
manually specify the revision number to which you want to update if you want to return to an
older version of the code.
Page 1 of 1
Before running commit you must run svn update to make sure that your working
version is up-to-date, and you aren’t modifying old files.
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
7/8/2014
After running svn update, there are 2 scenarios depending on what other users have been doing
with the code base.
1. If other users were not modifying the same lines of the code as Kevin, then this update is
“conflict-free”. That means that the changes that other people added to the repository will
be integrated automatically into your code. However, that does not mean that your code
will work! Other users might have deleted a variable assuming that Kevin will not need it,
or changed the interface of a function that Kevin’s new code uses. With every update, you
must understand what your team members changed in the code and whether it will affect
your code’s functionality or not. SVN is not a magic tool, it simply does what you tell it to
do and it can not guarantee code correctness – you must do that yourself.
2. There was a conflict. That only happens if both Kevin and another user were modifying the
exact same lines of code in the same source file.
Page 17 of 22
ECE297
Communication and Design
Page 1 of 1
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
Winter 2017
After every svn update, you must make sure that your code still compiles. Other
users may have made changes that are not compatible with the code that you
are writing and it is your job to compile (and ideally test) your code after each
svn update.
7/8/2014
Now let’s assume that another user (Mohamed) modified some of the same lines of code that
Kevin was modifying. That means there is a conflict! When Kevin runs update a dialog box shows
up saying that “Subversion has created local conflicts”. This means that there are two versions
of the file, the first one I modified, and the other one Kevin modified, and SVN doesn’t know
which one we actually want. We can svn resolve these conflicts using a merge tool. Luckily, the
Netbeans SVN plugin comes with a nice merge tool.
Page 18 of 22
ECE297
Communication and Design
Winter 2017
svn resolve filename
1. If svn update tells you that there are conflicts, the conflicted files will be highlighted in red and
the menu “Resolve Conflicts” will be clickable. Click on it.
2. The merge tool will open up. This goes through each and every conflict (set of lines in the file
that two people changed) and asks you which version you would like to keep. In the screenshot
below the window states that there is one conflict and it is still unresolved. The highlighted text is
the one in conflicted state. On the left, Kevin sees his local file, and on the right, he sees the latest
repository file that Mohamed committed. At the bottom, the resulting file is shown after merging.
Page 19 of 22
ECE297
Communication and Design
Winter 2017
3. Kevin wasn’t sure which piece of code he should choose, so he checked with Mohamed and they
agreed that Kevin’s changes are more useful. So he goes back to the merge tool and clicks “Accept”
on his changes. It is reflected in the “Result after merge” window as shown in the screenshot. Note
that they could’ve also accepted both changes by clicking “Accept Both”. You can also edit the
code in the “Result after merge” window after you’ve accepted a change in case you still need to
tweak it to make it fully correct. After making sure that all conflicts have been resolved, click
“OK”. Netbeans will ask you whether you want to save the file, click “Yes”. Kevin can now svn
commit his changes to the repository.
Page 20 of 22
ECE297
Communication and Design
Page 1 of 1
file:///C:/Users/Mohamed/Desktop/light-bulb-7.svg
Winter 2017
It is good practice to avoid editing the same file at the same time as much as
possible, but it will often happen when you work on the same project. Try to
split your application into multiple classes and discuss which team member is
doing what, and at what time to avoid unnecessary merges.
7/8/2014
Now let’s assume that Mohamed started enthusiastically editing the code, but he realized –
two hours later – that all the code he wrote is incorrect. Thankfully, he didn’t commit any of the
incorrect code he just wrote, but how does he go back to the last commit (which was working fine)?
SVN has a convenient command called svn revert that does exactly that.
svn revert [filename]
1. To svn revert a file, right click on it and go to “Revert Modifications”. You can also revert a
whole directory or the entire project.
Page 21 of 22
ECE297
Communication and Design
Winter 2017
2. The following menu opens up. To undo local changes, click on “Revert Local Changes”. This
returns your file(s) to your BASE revision (that is, before you did any local edits). Note that there
are two other options, these are explained in the following bullet point.
3. Option 1 corresponds to svn revert on the command line. However Netbeans has two other
revert options1 that are convenient in rolling back changes. Option 2 (as marked on the screenshot
above) removes all the changes from a specific commit only. Option 3 removes all changes from
revision “Starting Revision” to revision “Ending Revision”.
1
Under the hood Netbeans calls a combination of update and merge commands to achieve this functionality.
Page 22 of 22