3. What’s Subversion?
• Apache Subversion is a software versioning and a revision control system founded
and sponsored in 2000 by CollabNet Inc
• Replaces CVS and improves on its faults
• Developers use Subversion to maintain current and historical versions of files such as
source code, web pages, and documentation
• It is often abbreviated SVN, after the command name svn
3
5. Subversion Concepts – the repository
• Subversion is a centralized system for sharing information
• At its core is a repository, which is a central store of data
• The repository stores information in the form of a file system tree
• a typical hierarchy of files and directories
• Any number of clients connect to the repository, and then read or write to these files
• Sounds like a file server, what’s the difference?
• It remembers every change ever written to it —
every change to every file, and even changes to
the directory tree itself, such as the addition,
deletion, and rearrangement of files and
directories.
5
7. Subversion Concepts –
versioning models continued
• The Lock-Modify-Unlock Solution:
• This solution is used by many
version control systems
• The problem with it is:
• Locking may cause administrative
problems
• Locking may cause unnecessary
serialization
• Locking may create a false sense
of security
7
8. Subversion Concepts –
versioning models continued
This solution is used by Subversion
• The Copy-Modify-Merge Solution:
But what if changes overlap? 8
9. Subversion Concepts – Repository URLs
• Subversion uses URLs to identify versioned files and directories in Subversion
repositories:
• $ svn checkout http://svn.example.com:9834/repos
• The schema part of the URL has the following meaning:
9
11. Subversion Concepts – Working Copies
• A Subversion working copy is an ordinary directory tree on your local system,
containing a collection of files
• Your working copy is your own private work area
• Each directory in your working copy contains a subdirectory named .svn
• The following • To get a working copy of one of the example
example shows projects you must checkout as follows:
a repository
$ svn checkout http://svn.example.com/repos/calc
with two
projects:
11
12. Subversion Concepts – Revisions
• An svn commit operation publishes changes to any number of files and
directories as a single atomic transaction
• In your working copy, you can change files' contents; create, delete, rename, and
copy files and directories; and then commit a complete set of changes as an atomic
transaction
• Each time the repository accepts a commit, this creates a new state of the file
system tree, called a revision:
12
13. Subversion Concepts – trunk, branch, tag
• When laying out the repository for a project there are a couple of concepts that we will
come in contact with: trunk, branches, and tags – so what do they mean?
• trunk - main development area
• This is where your next major release of the code lives
• Generally has all the newest features
• branch – a copy of code derived from a certain point in trunk
• when a new version is released from trunk it is often custom to create a branch for
maintenance purposes
• This allows you to do bug fixes and make a new release without having to release the
newest - possibly unfinished or untested - features
• If the bug fixes work according to plan, they are usually merged back into the trunk
• tag - a point in time on the trunk or a branch that you wish to preserve
• Such as a major release of the software, whether alpha, beta, RC or GA
13
14. Subversion Usage – Initial Checkout
• Most of the time, you will start using a Subversion repository by doing a checkout of
your project
• Checking out a repository creates a working copy of it on your local machine
• This copy contains the HEAD (latest revision) of the Subversion repository that you
specify on the command line:
• $ svn checkout http://svn.example.com/repos/calc
While your working copy is “just like any other collection of files and
directories on your system,” you can edit files at will, but you must
tell Subversion about everything else that you do. For example, if
you want to copy or move an item in a working copy, you should use
svn copy or svn move instead of the copy and move
commands provided by your operating system
14
15. Subversion Usage – Initial Checkout
• For example if the main project is called alfresco you can check it out with the following
command:
• $ svn checkout https://yourproject.svn.cvsdude.com/alfresco/_training
• From TortoiseSVN you would do it like this:
Right-click in the folder
Then select Then enter URL
where you want to
SVN Checkout... here
check-out source code
15
16. Subversion Usage – Day-to-Day
• At the start of the day you would typically update your working copy:
• $ svn update
• Then you would go ahead and make changes, updating files, adding files:
• $ svn add foo.txt
• Deleting files:
• $ svn delete bar.txt
• Making new directories:
• $ svn mkdir test
• And finally you would commit your changes:
• $ svn commit -m "JIRA-101 - Corrected number of cheese
slices."
16
17. Subversion Usage – Day-to-Day – Update
• At the start of the day you would typically update your working copy
• Right click on the top directory (i.e. ‘alfresco’ in this case)
• Then Select SVN Update
17
18. Subversion Usage – Day-to-Day – Add
• Right click on the file you want to add
• Then Select TortoiseSVN
• And then select Add...
• The file will now be displayed as follows:
18
19. Subversion Usage – Day-to-Day – Delete
• Right click on the file you want to delete
• Then Select TortoiseSVN
• And then select Delete
19
20. Subversion Usage – Day-to-Day – Making a new
directory
• Same as adding
• Just create the directory and then follow same procedure as for adding file
20
21. Subversion Usage – Day-to-Day – Committing
changes
• When you are done with adding files and directories, updating files, and deleting
files and directories, then you need to commit to persist these updates in the
repository
• Right click on the top folder under which all changes have been done
• Then Select SVN Commit..., in the next dialog specify log message, commit by
pressing OK button
21
22. Best Practices (1) –
Use a sane repository layout
• There are many ways to lay out your repository
• The Subversion project officially recommends the idea of a "project root", which
represents an anchoring point for a project
• A "project root" contains exactly three subdirectories:
• /branches
• /tags
• /trunk
• A repository may contain only one project root, or it may contain a number of them
• Example:
• /alfresco
• /share-customizations-phase1
• /branches
• /tags
• /trunk
22
23. Best Practices (2) –
Commit logical change sets
• When you commit a change to the repository, make sure your change reflects a
single purpose:
• the fixing of a specific bug,
• the addition of a new feature,
• or some particular task
• Your commit will create a new revision number which can forever be used as a
"name" for the change.
• You can mention this revision number in bug databases, or use it as an argument
to svn merge should you want to undo the change or port it to another branch
23
24. Best Practices (3) –
Use the issue-tracker wisely
• Try to create as many two-way links between Subversion change sets and your
issue-tracking database as possible:
• If possible, refer to a specific issue ID in every commit log message
• When appending information to an issue (to describe progress, or to close the issue)
name the revision number(s) responsible for the change
24
25. Best Practices (4) – Track merges manually
• When committing the result of a merge, be sure to write a descriptive log message
that explains what was merged, something like:
• Merged revisions 3490:4120 of /branches/1.1-maintenance to /trunk.
• The above example log message tells us that all changes in revision 3490 to
revision 4120 in the 1.1-maintenance branch were merged over to trunk
25
26. Best Practices (5) –
Understand mixed-revision working copies
• Your working copy's directories and files can be at different "working" revisions
• This is a deliberate feature which allows you to mix and match older versions of
things with newer ones. But there are few facts you must be aware of:
1. After every svn commit, your working copy has mixed revisions
• The things you just committed are now at the HEAD revision, and everything else is at an
older revision.
2. Certain commits are disallowed:
• You cannot commit the deletion of a file or directory which doesn't have a working revision
of HEAD.
• You cannot commit a property change to a directory which doesn't have a working revision
of HEAD.
3. svn update will bring your entire working copy to one working revision, and is the
typical solution to the problems mentioned in point #2.
26
27. Best Practices (6a) –
Know when to create branches
• The Never-Branch system (policy 1)
• (Often used by nascent projects that don't yet have runnable code.)
• Users commit their day-to-day work on /trunk
• Occasionally /trunk "breaks" (doesn't compile, or fails functional tests) when a user
begins to commit a series of complicated changes
• Pros: Very easy policy to follow. New developers have low barrier to entry. Nobody
needs to learn how to branch or merge.
• Cons: Chaotic development, code could be unstable at any time
27
28. Best Practices (6b) –
Know when to create branches
• The Always-Branch system (policy 2)
• (Often used by projects that favour heavy management and supervision.)
• Each user creates/works on a private branch for every coding task
• When coding is complete, someone (original coder, peer, or manager) reviews all
private branch changes and merges them to /trunk
• Pros: /trunk is guaranteed to be extremely stable at all times
• Cons: Coders are artificially isolated from each other, possibly creating more merge
conflicts than necessary. Requires users to do lots of extra merging
28
29. Best Practices (6c) –
Know when to create branches
• The Branch-When-Needed system (policy 3)
• (This is the system used by the Subversion project)
• Users commit their day-to-day work on /trunk
• Rule #1: /trunk must compile and pass regression tests at all times. Committers who violate
this rule are publically humiliated
• Rule #2: a single commit (change set) must not be so large so as to discourage peer-review
• Rule #3: if rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small
commits without disrupting the trunk), then the user should create a branch and commit a
series of smaller change sets there. This allows peer-review without disrupting the stability of
/trunk.
• Pros: /trunk is guaranteed to be stable at all times. The hassle of branching/merging is
somewhat rare.
• Cons: Adds a bit of burden to users' daily work: they must compile and test before
every commit.
29
