Subversion
.. in eight easy commands
(and two slightly more complicated - but optional - ones)
CSIRO.
Why Use Version Control?
project> ls sol*
solver1.f90 solver­from_bob.f90
solver.bug.f90 solver­openmp.f90
solver.f90 solver­vector.f90
solver_fastest.f90
• Which one is which again?
CSIRO.
Why Use Version Control?
solver.f90
tags/release_1.0_April_2011
Initial import
r1
Created branch for OpenMP version
Found and fixed bug
r2
r3
r4
Merged in changes from Bob
r5
Merged working openmp
branch back to trunk
r6
r6
r7
trunk
CSIRO.
branches/openmp
Added OpenMP directives
Fixed error in OpenMP,
works now
Merged in updates
from trunk
tags/release_2.0_May_2011
Why Use Version Control?
• Easily and consistently manage code modifications
• Even when multiple people are working on it
• Even when there are multiple versions being
developed
• Jump back to last known-to-be-working version
• By revision number
• By Date
• By Tag
• Without losing changes made since then
• Easily compare and merge versions
• Protects against accidental deletion or overwriting
CSIRO.
The IM&T Subversion service
CSIRO.
The IM&T Subversion service
CSIRO.
The Subversion model
• The “true” copy is in the repository
• Do all work in a local copy (offline)
• Check-in changes regularly
• With a message to say what you did
and why
Repository
n
ck
Che
e
out
at
Upd
ki
c
e
Ch
My copy
Your copy
CSIRO.
• Update to pick up changes from
others
• Or because you broke your local copy
Repository is like a filesystem
• Access it using:
• https://svnserv.csiro.au/svn/myProject
If local
• file:///path/to/repository • svn+ssh://host/path/to/repos If remote
• Note three '/' in file:/// (file:// + /path/to/repository)
• Some commands:
• svn ls
• svn mkdir
svn cp
svn rm
svn add
> svn ls svn+ssh://cherax/cs/datastore/u/csssg/lea097/repos
AAQFS/
Documents/
MOM4/
> svn ls
svn+ssh://cherax/cs/datastore/u/csssg/lea097/repos/Documents
APA_july2009.doc
Migration_Status.xls
Notes_Aspendale_Visit_2july2009.doc
CSIRO.
Working within Subversion
Create a
repository
“check out”
a copy
svn co $REPO/trunk
Put files into
your working
copy
Initial source
code
CSIRO.
svnadmin create /path/to/repos
OR fill in IM&T request form
Repository
“commit”
changes
svn ci -m “my message”
Working copy
Work in your
working copy
cp $code/*.f90 .
svn add *.f90
Working within Subversion with a collaborator
Collaborator's
working copy
“update” working
copy to get changes
from collaborator
Collaborator
commits
changes
“commit”
changes
Repository
svn update
Working copy
CSIRO.
svn ci -m “my message”
What have I changed?
• svn st
• svn status
• Show changes in my local copy
• svn st ­q
• Do it quietly (don't show all these *.o files in my local directory which are not
in the repository)
• svn st ­u
• Check for changes my collaborators have made too
• svn diff
• Detail of changes in my local copy. Can also compare with a specific revision,
or a specific date:
• svn diff ­r151
• svn diff ­r{2011­05­10}
• svn diff –diff­cmd kdiff3
CSIRO.
Get changes from collaborators
• Scenario: you try to check-in your changes, and the
check in fails with a message:
• svn: File 'my_modified_file' is out of date
• This means: your collaborator has checked-in a
modification to this file since you last looked
• You should call him/her and discuss what changes you are making!
• Really:
• You should call him/her and discuss what changes you are
making!
• To add your collaborators changes to your copy:
• svn update
• svn up
CSIRO.
Get changes from collaborators (2)
• If the changes do not overlap, subversion will merge
them and show the message 'G':
• G all_netcdf.F90
• Updated to revision 13.
• If the changes do overlap, subversion will ask you to
edit the file or postpone action
• This only affects your working copy
• Before you check the merged version in, make sure your
changes are compatible with those from your collaborator!
• Merge changes with a GUI tool:
• svn update –diff3­cmd kdiff3
• (merges into your working directory – can then use svn ci to
commit the merged version)
CSIRO.
Working with branches (Advanced topic)
solver.f90
svn cp $repo/trunk $repo/branches/openmp
r1
svn co $repo/branches/openmp
r2
svn co $repo/trunk
r3
svn ci -m “added openmp stuff”
r5
r4
svn merge $repo/trunk
r6
svn merge $repo/branches/openmp
svn ci -m “added updates from trunk”
svn ci -m “merged openmp branch”
r7
CSIRO.
trunk
branches/openmp
ACCESS Users: Subversion, fcm and Trac
• fcm: a wrapper around svn
• Any “svn ...” command can be replaced by “fcm ..”
and it will do exactly the same thing (fcm just
passes the arguments on to svn)
• Trac can be used to browse and access a Subversion
repository
• No special setup in Subversion
• System/Trac administrator simply adds an entry into
trac.ini with the repository location
• Can be added later
CSIRO.
Subversion in eight easy commands:
• svnadmin create /path/to/repos
• Or request a repository from IM&T
• svn mkdir file:///path/to/repos/NewProject
• svn co file:///path/to/repos/NewProject
• svn add $MY_FILES • svn ci ­m “I did … because …”
• What have I changed?
• svn st
• svn st ­q
• What have my collaborators changed?
• svn st ­u
• svn up
• It worked last week – why doesn't it work now?
• svn diff ­r '{2011­05­01}'
CSIRO.
Links
• For TortoiseSVN (Windows)
• http://tortoisesvn.tigris.org/
• For the SVN Book:
• http://svnbook.red-bean.com
• For a handy quick-reference card
• http://www.digilife.be/quickreferences/QRC/Subversion
%20Quick%20Reference%20Card.pdf
• ASC Help: Email
• hpchelp@csiro.au
CSIRO.
Subversion
.. in eight easy commands
(and two slightly more complicated - but optional - ones)
CSIRO.
Why Use Version Control?
project> ls sol*
solver1.f90 solver­from_bob.f90
solver.bug.f90 solver­openmp.f90
solver.f90 solver­vector.f90
solver_fastest.f90
• Which one is which again?
CSIRO.
Without version control, your working directories look like this!
If you have code .. or in fact any type of document .. which has or will have more than
one version, for any reason, then revision control is vital
If there are more than one of you working on the code
To document what you did and why
To be able to jump back to a working version if everything breaks
To have a backup of everything you do
Why Use Version Control?
solver.f90
tags/release_1.0_April_2011
Initial import
r1
Created branch for OpenMP version
Found and fixed bug
r2
r3
r4
Merged in changes from Bob
r5
Merged working openmp
branch back to trunk
r6
r6
Added OpenMP directives
Fixed error in OpenMP,
works now
Merged in updates
from trunk
tags/release_2.0_May_2011
r7
trunk
CSIRO.
branches/openmp
With version control, the relationships between different versions are documented, and
only the version you are currently interested in is presented to you
Easier to keep track of where you were up to!
All versions are retained in repository
Only the currently relevant version is visible in your working directory
But other versions can easily be checked out, or compared against this
version and each other
All changes have a log message where you can explain what you changed and why
Typing “svn log” show log message relevant to your current directory
Development of a feature can continue on a separate branch without disrupting the main
development (the trunk)
Changes on one branch can be easily merged into another once you are happy with
them
Release/important versions and self-consistent versions can be tagged and easily
accessed via the tag
Why Use Version Control?
• Easily and consistently manage code modifications
• Even when multiple people are working on it
• Even when there are multiple versions being
developed
• Jump back to last known-to-be-working version
• By revision number
• By Date
• By Tag
• Without losing changes made since then
• Easily compare and merge versions
• Protects against accidental deletion or overwriting
CSIRO.
Moreover: if you are using the CSIRO/IM&T Subversion service, your source code is:
Backed up
Accessible to your collaborators
Not reliant on you being present
The IM&T Subversion service
CSIRO.
Follow these links from the intranet
Form takes a few minutes to fill out. IM&T responds pretty quickly with an email with a
link to your new repository
Good practice is to have a separate repository for separate projects
(sub-projects can share a repository)
Eg:
the serial and parallel versions of the same code should share a repository
The model and preprocessing codes probably share a repository
Two different models probably want two different repositories – even if the output of one
is used by the other
The IM&T Subversion service
CSIRO.
Repository Name: choose something short, you'll type it a lot!
Repository owner: yourself or the primary investigator
Admins: have access to the “svnadmin” commands for repository maintenance. Rarely
used, and a fairly advanced topic. Make the P.I and/or the most computer-savvy
researcher the admin, and then ignore the fact (until or unless you need an admin
someday)
Repository access:
Read/write: people who will actually develop code (and check versions in)
Read only: people who will use the code but not make changes to it
You can add more users later
Anonymous access: probably “no”. The sort of thing that the people who need it know
about it, and nobody else cares about it
Partners External to CSIRO?
Size: for source code, probably <100MB
Duration: probably indefinite
The Subversion model
• The “true” copy is in the repository
• Do all work in a local copy (offline)
• Check-in changes regularly
• With a message to say what you did
and why
Repository
n
ck
Che
• Update to pick up changes from
others
• Or because you broke your local copy
out
ate
Upd
i
ck
e
Ch
My copy
Your copy
CSIRO.
The true version is secure
If all else fails, you can delete your local copy and check it out again
You don't need to be online to work on your local copy – just to commit changes and
fetch updates
Repository is like a filesystem
• Access it using:
• https://svnserv.csiro.au/svn/myProject
If local
• file:///path/to/repository • svn+ssh://host/path/to/repos If remote
• Note three '/' in file:/// (file:// + /path/to/repository)
• Some commands:
• svn ls
• svn mkdir
svn cp
svn rm
svn add
> svn ls svn+ssh://cherax/cs/datastore/u/csssg/lea097/repos
AAQFS/
Documents/
MOM4/
> svn ls
svn+ssh://cherax/cs/datastore/u/csssg/lea097/repos/Documents
APA_july2009.doc
Migration_Status.xls
Notes_Aspendale_Visit_2july2009.doc
CSIRO.
Working within Subversion
Create a
repository
“check out”
a copy
svn co $REPO/trunk
Put files into
your working
copy
Initial source
code
svnadmin create /path/to/repos
OR fill in IM&T request form
Repository
“commit”
changes
svn ci -m “my message”
Working copy
Work in your
working copy
cp $code/*.f90 .
svn add *.f90
CSIRO.
1. Create or repository (very easy)
Or better, request one via IM&T
If creating your own, put it on a backed-up filesystem that is intended for
small files such as source code (eg $HOME .. but $HOME on
cherax is $DATASTORE, not the ideal place as it's really for
large data files)
If creating you own, and it is to share with collaborators, just set the unix
permissions appropriately on the repository:
chmod -R g+rw /path/to/repos
2. check out a copy to create a working directory
3. Put files into the working directory. Use svn add, svn mkdir and so on. Commit them
with svn ci.
Once your source code is in the repository, you can delete the “Initial
source code” and just work in your working copy
Note: your working directory is not automatically mirrorred in the repository:
I
f you create or delete files you must use “svn add” and “svn rm” to include
them
4. Work in the working copy!
5. Every now and then, commit your changes.
You can commit even if the changes don't work yet – just write a
meaningful log message so you can track where you got up to later (and
check out a “last working version” if you need to)
Or make a branch for your unfinished modifications, and keep the trunk for
working versions
It doesn't hurt to tag working versions either!
Working within Subversion with a collaborator
Collaborator's
working copy
“update” working
copy to get changes
from collaborator
Collaborator
commits
changes
“commit”
changes
Repository
svn ci -m “my message”
svn update
Working copy
CSIRO.
Exactly the same, but your collaborator also has a working copy
(maybe each of you can have a branch so you can check in unfinished
versions without interfering with each other)
To make a branch: svn cp $repos/trunk $repos/branch/steves_branch
(more on this soon)
Every now and then, update your working copy with changes from your collaborator
Every now and then, check in your changes (or merge them into the trunk)
Update your working copy first, in case you and your collaborator have
made conflicting changes
What have I changed?
• svn st
• svn status
• Show changes in my local copy
• svn st ­q
• Do it quietly (don't show all these *.o files in my local directory which are not
in the repository)
• svn st ­u
• Check for changes my collaborators have made too
• svn diff
• Detail of changes in my local copy. Can also compare with a specific revision,
or a specific date:
• svn diff ­r151
• svn diff ­r{2011­05­10}
• svn diff –diff­cmd kdiff3
CSIRO.
Get changes from collaborators
• Scenario: you try to check-in your changes, and the
check in fails with a message:
• svn: File 'my_modified_file' is out of date
• This means: your collaborator has checked-in a
modification to this file since you last looked
• You should call him/her and discuss what changes you are making!
• Really:
• You should call him/her and discuss what changes you are
making!
• To add your collaborators changes to your copy:
• svn update
• svn up
CSIRO.
Get changes from collaborators (2)
• If the changes do not overlap, subversion will merge
them and show the message 'G':
• G all_netcdf.F90
• Updated to revision 13.
• If the changes do overlap, subversion will ask you to
edit the file or postpone action
• This only affects your working copy
• Before you check the merged version in, make sure your
changes are compatible with those from your collaborator!
• Merge changes with a GUI tool:
• svn update –diff3­cmd kdiff3
• (merges into your working directory – can then use svn ci to
commit the merged version)
CSIRO.
If you select postpone, you will get 4 version of the file in your working directory:
Filename.f90: this will have conflict markers around the conflicted areas:
<<<<< .mine
(stuff in my version)
======
(stuff in the latest repository version)
>>>> .r21
Filename.f90.mine: your version
Filename.f90.r1: the version you checked out before you modified it
Filename.f90.r2: the latest version from the repository
When you are satisfied that Filename.f90 is what you want to commit to the repository,
use “svn resolve” to resoved the conflict (see “svn help resolve” or the red-bean book for
information about using this)
Working with branches (Advanced topic)
solver.f90
svn cp $repo/trunk $repo/branches/openmp
r1
svn co $repo/branches/openmp
r2
svn co $repo/trunk
r3
svn ci -m “added openmp stuff”
r5
r4
svn merge $repo/trunk
r6
svn merge $repo/branches/openmp
svn ci -m “added updates from trunk”
svn ci -m “merged openmp branch”
r7
CSIRO.
trunk
branches/openmp
This is somewhat advanced use, and you may prefer to simply do all your work on the
trunk
..or, ask your local svn guru to create you a branch, do all your work there,
and ask the guru to merge your changes back to the trunk for you!
Why do it at all?
Good for developing different features simultaneously
First create a branch by copying the entire trunk as a new subdirectory under branches/
svn cp -m “making my branch” $repo/trunk $repo/branches/my_branch
Now check out that branch to get your new working directory
(you can also use svn switch or svn update for this, but a fresh checkout is
simplest)
Work on your branch
Before merging it back to the trunk, pull any changes from the trunk into your branch
And once you are happy with it, check it in
Now checkout a copy of the trunk … and merge your branch into that
It should happen smoothly, because you already merged this version of the
trunk into your brnach
Commit the trunk with your branch merged into it
ACCESS Users: Subversion, fcm and Trac
• fcm: a wrapper around svn
• Any “svn ...” command can be replaced by “fcm ..”
and it will do exactly the same thing (fcm just
passes the arguments on to svn)
• Trac can be used to browse and access a Subversion
repository
• No special setup in Subversion
• System/Trac administrator simply adds an entry into
trac.ini with the repository location
• Can be added later
CSIRO.
Most importantly: you don't need to worry about it
Any subversion command is also an fcm command
Trac can be used to browse a Subversion repository – Subversion doesn't need to know
about Trac
Subversion in eight easy commands:
• svnadmin create /path/to/repos
• Or request a repository from IM&T
• svn mkdir file:///path/to/repos/NewProject
• svn co file:///path/to/repos/NewProject
• svn add $MY_FILES • svn ci ­m “I did … because …”
• What have I changed?
• svn st
• svn st ­q
• What have my collaborators changed?
• svn st ­u
• svn up
• It worked last week – why doesn't it work now?
• svn diff ­r '{2011­05­01}'
CSIRO.
And two slightly harder ones:
svn branch
svn merge
Links
• For TortoiseSVN (Windows)
• http://tortoisesvn.tigris.org/
• For the SVN Book:
• http://svnbook.red-bean.com
• For a handy quick-reference card
• http://www.digilife.be/quickreferences/QRC/Subversion
%20Quick%20Reference%20Card.pdf
• ASC Help: Email
• hpchelp@csiro.au
CSIRO.