Subversion for Users

title: Subversion for Users
author: Bernard Szlachta (NobleProg Ltd), Lukasz Sokolowski

Subversion for Users

Subversion for Users Training Materials

Copyright Notice

This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise.

Agenda ⌘

Revision Control Idea and Problems
Architecture of Subversion
The working cycle
Team Work I
Locking
Tagging
Branching
Merging
Team Work II
Properties
Do’s and don’t’s
Subversion Configuration

Actors ⌘

Problems ⌘

Problems, file sharing ⌘

Where the duck is my file?
Who the frog overridden my files?
I haven’t created a backup
It is faster to write it again than restore it from backup!
What has changed during last day?
Can we check whether the problem is in the code or in the database?

Subversion ⌘

The act or an instance of subverting.
The condition of being subverted.
Obsolete A cause of overthrow or ruin.

From www.thefreedictionary.com

Subvert ⌘

To destroy completely; ruin: "schemes to subvert the liberties of a great community" Alexander Hamilton.
To undermine the character, morals, or allegiance of; corrupt.
To overthrow completely: "Economic assistance ... must subvert the existing ... feudal or tribal order" Henry A. Kissinger. See Synonyms at overthrow.

From www.thefreedictionary.com

Revision Control ⌘

Revision control (AKA version control (system) (VCS), source control or (source) code management (SCM)) is the management of multiple revisions of the same unit of information. It is most commonly used in engineering and software development to manage ongoing development of digital documents like application source code, art resources such as blueprints or electronic models, and other projects that may be worked on by a team of people.

From www.wikipedia.org

Revision Control Systems ⌘

Software	Maintainer	Development status	Concurrency model	License	Platforms supported
CVS	The CVS Team	maintained but new features not added	Merge	GPL	Unix-like, Windows, Mac OS X
Subversion (SVN)	CollabNet, Inc.	actively developed	Merge or lock	Apache/BSD style	Unix-like, Windows, Mac OS X
Team Foundation Server	Microsoft	actively developed	Lock or merge	Proprietary	Server: Windows Server 2003; Clients: Windows and Web included
Telelogic Synergy	Telelogic (IBM)	actively supported	Merge or Lock	Proprietary	Linux, Windows, Unix-like
Visual SourceSafe	Microsoft	serious bug fixes only	Lock or merge	Proprietary	Windows
Git	The Git Team	actively developed	Merge or Rebase	GPL	Linux, Windows, Unix-like

The history of Subversion ⌘

RCS
CVS
Subversion
June 2000 - Coding begins.
August 2001 - Subversion becomes self-hosting.
2002 – 1^st release
2004 – Feb. Release 1.0.0
2006 – Sept. Release 1.4.0
2009 – August Release 1.6.4
2011 - Release 1.7
2014 - August Release 1.8.10
2016 - it's still ugly, but best for centralized systems (-:

Estimated amount of Subversion developers: 1.4 million

Subversion Users and Sizes ⌘

803 577 Revisions

Testimonial: Stuart Robertson of Absolute Systems, Inc (5 May 2004) In the last 4 months we have migrated all of our internal product source repositories from XXX to SVN […] Our largest SVN repository is now 3.7GB and currently has 68806 revisions. We are running SVN 1.0.1 + Apache 2.0.48 on Linux. ... SVN is a superb piece of work, and it is a *huge* step forward from XXX. To put things in perspective... previously we had 26 XXX databases for one product

More testimonials on: https://svn.apache.org/repos/asf/subversion/branches/1.2.x/www/testimonials.html

Subversion Concepts ⌘

Most current CVS features.
Directories, renames, and file meta-data are versioned.
Commits are truly atomic.
Apache network server option, with WebDAV/DeltaV protocol.
Standalone server option.
Branching and tagging are cheap (constant time) operations
Natively client/server, layered library design
Costs are proportional to change size, not data size
Choice of database or plain-file repository implementations
Versioning of symbolic links
Efficient handling of binary files
Parseable output
Localized messages

Subversion Architecture ⌘

Access URLs ⌘

file://

Direct repository access to local or network drive.)

http://

Access via WebDAV protocol to Subversion-aware Apache server.)

https://

Same as http://, but with SSL encryption.

svn://

Unauthenticated TCP/IP access via custom protocol to an svnserve server.

svn+ssh://

Authenticated, encrytped TCP/IP access via custom protocol to an svnserve server.

Access URLs ⌘

file://hostname/path/to/repos
- On local machines the hostname part must be absent or localhost.
This results in a path like this one:
- file:///path/to/repos
On Windows you have to specify the drive where to find the repository:
- file:///X:/path/to/repos

Repository Layout ⌘

Revisions ⌘

Every commit produces a new unique revision number.
The revision numbers are unique per repository.
A commit in Subversion is atomic just like a database transaction (technically there is no difference).

Working Cycle ⌘

Importing New Project ⌘

Importing Project ⌘

Linux

svn import /sample_path file:///repopath/projectname/trunk   -m “Initial Import”

Micro$oft Window$

svn import c:\sample_project file:///c:/repo/sample_project -m "Initial import"

Checking Out ⌘

A check out will transfer the project’s content from the repository server to the client machine.

Checking Out ⌘

svn checkout file:///repopath/projectname/trunk dirname

The “dirname” is a local directory. The name of the directory where the checked out project tree will be stored. This is called the “working copy” (WC).

Chick Out ⌘

WorkingCopies (WC) ⌘

Checking WC Status ⌘

svn status

Status Meanings ⌘

A: (Added)scheduled for addition into the repository.
C: conflict. That is, changes received from the server during an update overlap with local changes that you have in your working copy. You must resolve this conflict before committing your changes to the repository.
D: Scheduled for deletion from the repository.
M: The content of the file item has been modified.
R: Scheduled to replace an item in the repository. This means that the object is first deleted, then another object of the same name is added, all within a single revision.
X: The directory item is unversioned, but is related to a Subversion externals definition.
?: The file, directory, or symbolic link item is not under version control.
!: The file, directory, or symbolic link item is under version control but is missing or somehow incomplete. The item can be missing if it's removed using a non-Subversion command.
- => svn update will refetch the file or directory from the repository, or
- => svn revert file will restore a missing file.
~: The file, directory, or symbolic link item exists in the repository as one kind of object, but what's actually in your working copy is of some other kind.
I: The item is not under version control, and Subversion is configured to ignore it.

Status Meaning in SVN ⌘

Committing Changes ⌘

svn commit –m “Log messages”

Item History ⌘

svn log file(s)

Adding file to repo ⌘

Add merely means to schedule it for the next commit.

svn add file(s)

The Subversion “add”-command
One or more files separated by spaces which are scheduled for addition. If you use a directory all files in the directory are added recursively. You can use the command option --non-recursive (-N) to change this behaviour.

Creating New Directories ⌘

mkdir direcotry svn add directory	svn mkdir directory

Removing Items ⌘

svn delete file(s)

If you like to schedule a directory for deletion it is usually recursively marked for deletion.

If you have changed the file and you would like to delete it you’ll have to use the --force option.

Removing Items Caveat ⌘

Make sure that all the files are closed

Moving Files ⌘

svn move source destination

Copying Files ⌘

svn copy source destination

Copying Files via CLI ⌘

Copying with Tortoise ⌘

Copying with TortoiseSVN ⌘

Move/Copy files/directories via TortoiseSVN:

If you use the right mouse button you will see the context menu for moving and copying files.

Check What Was Changed ⌘

Examine local changes:

svn diff

The Subversion “diff”-command.
If you provide no options at all you will see the differences between your working copy and the cached “pristine” copy in the .svn area

Status vs Diff ⌘

C:\wc>svn status
M      new_file_name.txt
M      afile.txt
A  +   copyofafile.txt

Status vs Diff ⌘

C:\wc>svn diff
Index: new_file_name.txt
===================================================================
--- new_file_name.txt   (revision 6)
+++ new_file_name.txt   (working copy)
@@ -1,3 +1,3 @@
 Old Line
-New Line
-Modified Line
\ No newline at end of file
+Modified Line New bits
+New Line
\ No newline at end of file
Index: afile.txt
===================================================================
--- afile.txt   (revision 4)
+++ afile.txt   (working copy)
@@ -0,0 +1 @@
+New Line
\ No newline at end of file

Property changes on: copyofafile.txt
___________________________________________________________________
Added: svn:mergeinfo

Tortoise Diff ⌘

Caveats ⌘

Never move, delete, copy files or create directories without the Subversion commands:
- svn move
- svn delete
- svn copy
- svn mkdir
If using TortoiseSVN it is integrated directly in Windows Explorer

Undo Operation (revert) ⌘

svn revert destination

The Subversion “revert”-command.
The destination of the operation file/directory. You have to provide a destination. If you don’t the help output is shown.

If you want to revert a whole directory of files, use the „--recursive“ flag.

Pristine Copy Revert ⌘

How does the revert operation work?

Subversion holds a complete “pristine” copy of the checked out working copy in its “.svn” directory structure.
Every operation can be rolled back:
- add
- remove
- copy
- delete
- mkdir
- …
But only as long as it is uncommitted.

Revert and other changes ⌘

If you copied (without svn copy) directory, svn revert will not revert the change. The easiest way to make sure that your WC is really pristine is to remove the whole working copy and check it out again.

Operation on WC versus Repo ⌘

svn mkdir file:///repo/dirname

svn mkdir wcdir/dirname

Working Copies ⌘

Conflicts ⌘

Both begin to edit the same file in their copies and their changes overlap.

Conflicts ⌘

Sally commits her work

Conflicts ⌘

Harry tries to commit his work after Sally.

Conflicts ⌘

Harry has to update his local working copy to get Sally‘s changes.

Conflicts ⌘

U: File was Updated (received changes from the server).
A: File or directory was Added to your working copy.
D: File or directory was Deleted from your working copy.
R: File or directory was Replaced in your working copy; that is, file was deleted and a new item with the same name was added. While they may have the same name, the repository considers them to be distinct objects with distinct histories.
G: File received new changes from the repository, but your local copy of the file contained your modifications. Either the changes did not intersect, or the changes were exactly the same as your local modifications, so Subversion has successfully merGed the repository's changes into the file without a problem.
C: File received Conflicting changes from the server. The changes from the server directly overlap your own changes to the file. No need to panic, though. This overlap needs to be resolved by a human (you);

Conflicts ⌘

How to solve a conflict?

No tool is able to handle the conflict.
Only humans are capable of understanding and making the necessary intelligent choices.
The two members (in the example) have to discuss the conflict as well as possible solutions.

Conflicts ⌘

How does Subversion support you?

Subversion outputs a C during the update and remembers that the file is in a state of conflict.
If Subversion considers the file to be of a mergeable type, it places conflict markers „<<<<<“ or „>>>>>“ —special strings of text which delimit the “sides” of the conflict—into the file to demonstrate visibly the overlapping areas (Subversion uses the svn:mime-type property to decide if a file is capable of contextual, line-based merging).

Conflicts ⌘

How does Subversion support you?

For every conflicted file Subversion places up to three extra unversioned files in your working copy:
- filename.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. (If Subversion considers the file to be non mergeable, then the .mine file isn't created, since it would be identical to the working file.)
- filename.rOLDREV
  - This is the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
- filename.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.

Conflicts ⌘

Conflict has been solved by a human being. It is clear now which part of the code or documentation is the right one.
Before you can check in the merged file you have to tell Subversion that the conflict has been solved.

Conflicts ⌘

Tell svn which ver do you want to keep:

svn resolve --accept <base, mine-full, theirs-full, working>

Deprecated:

svn resolved destination

Conflicts ⌘

In the last step Sally has to update her local working copy.

Now both share the same state.

Reasons for Conflicts ⌘

Two members of a team work on the same files and overlapping areas.
In the end it can be reduced to one critical factor:
- User communication.
It must be clear who is working on what.
How often do conflicts arise?
- Conflicts arise due to poor human communication, no software can solve that. If people communicate, conflicts are rare.

Binary Conflicts ⌘

M:\training\svn_subversion\np_svn_for_users>svn up
Conflict discovered in 'svn_for_users.ppt'.
Select: (p) postpone, (mf) mine-full, (tf) theirs-full,
        (h) help for more options: _

Locking ⌘

Locking Models
Optimistic Locking
Pessimistic Locking

Copy-Edit-Merge Model ⌘

The default model of Subversion is the "copy-edit-merge" model.

Check out a working copy
Make any edits
merge changes from server
Commit your changes

But there are situations in which this model might cause problems.

The Two Models ⌘

You can't use the "copy-modify-merge" model with files like Word or Excel (this applies for other types too)
- because you can't merge those files
So you have to go another way. There are two possible solutions:
- The first one is to explicitly lock the file before you start to edit a file of the above type (called optimistic locking)
- The second one is to use the "pessimistic-locking" variety

Optimistic Locking ⌘

Explicit Locking strategy

Before you start working on a non-mergeable file (like Word etc.) you have to request a lock for the given file
If you get the lock you can start working on it
When you are done with your changes, you commit whereas the lock will be released at the same time
Advantages
- It’s simple
- It’s not error-prone
Disadvantages
- You miss to unlock a file e.g. before you are going on vacation etc. (You can steal locks ;-))
- Everyone has to apply this procedure as a default rule
- No lock "reminder" for the user

Optimistic Locking Con't ⌘

To unlock a file just type the svn unlock command with a particular destination
Or it will be unlocked automatically if you commit your changes back to the repository

Pessimistic Locking ⌘

You can put a special property to a file svn:needs-lock with any value
The result is if you check out a file with the property set, the file will be marked as read-only
Advantage
- The application you use with this type of file will give you a reminder about the read-only state
Disadvantage
- The system isn't flawless, either. It's possible that even when a file has the property, the read-only reminder won't always work. Sometimes applications misbehave and "hijack" the read-only file, silently allowing users to edit and save the file anyway. Unfortunately there's not much Subversion can do about this.

Tagging ⌘

Why do we need tags?
- Mark a release state of a product.
- Mark a snapshot of the current development.
Typical Release names:
- Release 1.0.0, Release 2.3.1, PRODUCT 1.0.0RC1 etc.
A Tag name
- must be unique to mark all components of the given product (source code and documentation)
- and is used to reproduce the state of the tag in the future.

What are Tags ⌘

If we take a look at the architecture chapter we really don‘t need a special tag. We only need to write down the revision number.
But human beings have other requirements.
They like to have self-explanatory tag names which are more handy.
But the question is:
- Where to put the tag information in the repository?

Tagging con't ⌘

You can create a tag using the following command:
- ```
svn copy source destination
```
  - The Subversion "copy"-command.
  - The source of the operation (this can be the current working copy or an explicit referenced part in the repository).
  - The destination of the operation. This means the name of the tag.

Tagging Example ⌘

Example:

svn copy http://svnserver/calc/trunk http://svnserver/calc/tags/RELEASE-1.0.0 -m "Create Release Tag for Release 1.0.0"

If the release name contains spaces you have to use quotes.

Branching ⌘

Assume the following situation:
- You have created a great product and it has been delivered to your customer.
- Before you delivered the product you have created a tag, let us name it "Release 1.0.0"
- Your current development crew is working on Release 1.1.0 with new features.
And now Murphy‘s Law caught you:
- Your customer calls you and reports that he has found a bug in your software.

Branching con't ⌘

The development has continued after the release of RELEASE 1.0.0
You want to fix the bug to satisfy your customer!
In your current development
- you have enhanced many of the product's functions
- but you don't want to deliver a product with more features
- and you haven't finished testing yet
How to solve this situation?

Branching con't ⌘

Based on the tag you've created during the delivery you can check out the exact state of the delivery.
You create a Branch to fix the bug in the software.
After you have fixed the bug you can tag the Branch and deliver another version to the customer.
Your customer is satisfied that you fixed the bug so fast.
You haven't disturbed the current development.

Branch Example ⌘

svn copy 
  http://svnserver/calc/trunk                     # You can replace this with a "." for your working copy
  http://svnserver/calc/branches/my-calc-branch   # The branch name
  -m "Create the branch"                          # Log Message

Switching WC ⌘

You can switch your current working copy to a branch with the following command

svn switch destination

– The Subversion "switch"-command
– The destination of the operation which means the name of the branch

Branching - Releases ⌘

Fix the bug through doing the necessary modifications and finally commit the changes to the branch
After having fixed the bug on the branch create a tag to mark the new release which can be delivered to the customer
Create the new Release Tag

svn copy
file:///home/kama/repos/project1/branches/BUGFIX_BRANCH
file:///home/kama/repos/project1/tags/RELEASE-1.0.1
-m”- Fixed Release 1.0.1”

Merging From a Branch ⌘

What's with the bug you've fixed on the bug-fix-branch?
What about your current development?
You have to merge the changes made in the branch back to the main line

Merging Con't ⌘

You can merge the changes from the branch into your current working copy with the following command

svn merge ^branchname

– The Subversion "merge"-command
– The branch-name you like to merge into your current working copy

Merge Info ⌘

Which changes have already been merged from trunk to branch?

$ svn mergeinfo ^/calc/trunk
r341
r390
# Which changes are still eligible to merge from trunk to branch?
$ svn mergeinfo ^/calc/trunk --show-revs eligible
r391
r392
r393
r394
r395

Merge --reintegrate ⌘

Merging branch back into the trunk

svn merge ^trunk --reintegrate

Best Practices ⌘

If you need to create a branch, you should do it from a completely committed working copy. This prevents you from becoming confused
If you merge check out a clean copy into another directory
- Otherwise you can't go back using "svn revert"
- After you've merged commit the changes and provide a log message with information on which revision/branch you have merged (merge tracking)
- You can first test the merge using the --dry-run flag of the merge command

Branches vs Tags ⌘

The intention of a tag is that it should be used as read-only area whereas a branch is used to continue development (interim code, bug-fixing, release candidate etc.)
Technically you can use a tag to continue development and check in etc. but you shouldn’t do it
So in other words the difference between a tag and a branch is just an agreement

Reverting Commited Changes ⌘

svn merge -c -303 ^/calc/trunk
svn merge -r -303:302 ^/calc/trunk

Reverting Deleted Files/Directories ⌘

svn cat ^/calc/trunk/real.c@807 > ./real.c

Cherry Picking ⌘

svn diff -c 355 ^/calc/trunk
svn diff -r 355:360 ^/calc/trunk

Properties ⌘

You can get a list of properties using the following command

svn proplist --verbose destination

svn:ignore ⌘

Tell Subversion which files and subdirectories to ignore
Equivalent to CVS’s .cvsignore file
You can define a special file/directory or patterns defining the files/directories which will be ignored
You can suppress the exclusion if you use the --no-ignore flag for the svn status command

Some Good Practices ⌘

Do not not commit just a single file if your change applies to more than one file
Commit the complete directory tree beginning at the root of your working copy
Make sure your change reflects a single purpose: fixing a specific bug, the addition of a new feature, or some specific task
- But why?

Good Practices Con't ⌘

Log messages should describe the change from a business point of view
Put in a reference to Ticket/Issue/Bug Id
Don't write log messages like:
- Removed line 4
- Inserted line 10 in file, etc
The above is the job of Subversion not yours ;-)
Often Log messages have to follow policies given by the company. Pay attention to yours

Recap

## GETTING HELP
svn help                   # For usage 
svn help <subcommand>      # For help on a specific subcommand
svn help <subcommand> -v   # For help and show global and experimental options


## MAKING REPOS
# Create catalog for all repositories
svnadmin create /home/userName/repos
# Put new project files into
svn import ... file:///home/userName/repos/slideshow -m "Initial Rev"


## WORKING COPIES (WC)
# Full copy (branches, tags, trunk)
svn checkout file:///home/userName/repos/slideshow wc1
# Your BEST FRIEND - Status
svn st -uv                 # Do it ALWAYS before any new commit
# ..and his great sis - Difference
svn diff                   # Do this ALWAYS before any new commit
svn diff -r REV1:REV2
# ..and their younger bros
svn info                   # To check where your things live
svn list                   # To see what's inside
# WC usuals
svn add                    # New files
svn mkdir                  # New folders
svn ci -m "..."            # Making revs
svn mv                     # Moving things around
svn rm                     # Deleting
svn cp                     # Cloning (-;
# Updating locals
svn up                     # Do it ALWAYS in the very root folder
svn up --force
svn up --parents
svn up -r REV1             # Time vehicle, but you can't kill the Hitler, nope.. (-:
# Boring History
svn log -vq -l 5                            # Verbose without messages limitted to 5
svn log trunk/logo.html@2                   # Changes for 'logo.html' from 'rev2'
svn log ^/slideshow/trunk@3 logo5.html      # Changes from 'rev3' for file 'logo5.html'
svn log -r BASE:HEAD trunk/logo.html        # Incoming changes from the next 'svn up'
# Blaming (-;
svn blame trunk/logo.css -v
# Cleaning
svn cleanup                                 # Recover from an interrupted operation that left the working copy locked, or remove unwanted files
svn revert                                  # Restore pristine working copy state (undo local changes)
# Locking
svn lock
svn unlock


## BRANCHES
# Create a branch or tag	                  ( svn copy URL1 URL2 )
# Switch a working copy to a branch or tag    ( svn switch URL )
# Synchronize a branch with trunk	          ( svn merge trunkURL; svn commit )
# See merge history or eligible changesets    ( svn mergeinfo SOURCE TARGET )
# Merge a branch back into trunk	          ( svn merge --reintegrate branchURL; svn commit )
# Merge one specific change	                  ( svn merge -c REV URL; svn commit )
# Merge a range of changes	                  ( svn merge -r REV1:REV2 URL; svn commit )
# Block a change from automatic merging	      ( svn merge -c REV --record-only URL; svn commit )
# Preview a merge	                          ( svn merge URL --dry-run )
# Abandon merge results	                      ( svn revert -R . )
# Resurrect something from history	          ( svn copy URL@REV localPATH )
# Undo a committed change	                  ( svn merge -c -REV URL; svn commit )
# Examine merge-sensitive history	          ( svn log -g; svn blame -g )
# Create a tag from a working copy	          ( svn copy . tagURL )
# Rearrange a branch or tag	                  ( svn move URL1 URL2 )
# Remove a branch or tag	                  ( svn delete URL )

Exercises

Svn exercises