<<Subversion Simple Guide>>
DOCUMENT HISTORY
----------------------------------------------------------
DATE VERSION COMMENTS WRITER
----------------------------------------------------------
2007-4-6 0.9 DRAFT ZhaoXiaoguang
----------------------------------------------------------
----------------------------------------------------------
----------------------------------------------------------
Table of Contents
=======================================
1.Preface
2.Introduce
3.Glossary
4.Install
4.1 Basic Requirement
4.2 Download
4.3 Install Subversion
5.Configuration
5.1 Create repository
5.2 Configure SVN
5.3 Import your project
5.4 Start SVN service
6.Configure SVN with Apache
7.SVN client
8.Issues
9.Reference
=======================================
1.Preface
The main aim of this document is to give you an elementary instruction about Subversion.
The following content are based on WinXP only,not for Linux.
After reading it, I wish you could know how to install Subvision and how to build your own
repository, and also know how to use SVN clinet(I suggest to use SmartSVN) to manage your project.
2.Introduce
Subversion is a version control system that is a compelling replacement for CVS in the open source
community. The software is released under an Apache/BSD-style open source license.
Subversion's Features:
* Most current CVS features.
Subversion is meant to be a better CVS, so it has most of CVS's features. Generally, Subversion's
interface to a particular feature is similar to CVS's, except where there's a compelling reason to
do otherwise.
* Directories, renames, and file meta-data are versioned.
Lack of these features is one of the most common complaints against CVS. Subversion versions not only
file contents and file existence, but also directories, copies, and renames. It also allows arbitrary
metadata ("properties") to be versioned along with any file or directory, and provides a mechanism
for versioning the `execute' permission flag on files.
* Commits are truly atomic.
No part of a commit takes effect until the entire commit has succeeded. Revision numbers are per-commit,
not per-file; log messages are attached to the revision, not stored redundantly as in CVS.
* Apache network server option, with WebDAV/DeltaV protocol.
Subversion can use the HTTP-based WebDAV/DeltaV protocol for network communications, and the Apache
web server to provide repository-side network service. This gives Subversion an advantage over
CVS in interoperability, and provides various key features for free: authentication,
wire compression, and basic repository browsing.
* Standalone server option.
Subversion also offers a standalone server option using a custom protocol (not everyone wants to run
Apache 2.x). The standalone server can run as an inetd service, or in daemon mode, and offers basic
authentication and authorization. It can also be tunnelled over ssh.
* Branching and tagging are cheap (constant time) operations
There is no reason for these operations to be expensive, so they aren't.
Branches and tags are both implemented in terms of an underlying "copy" operation. A copy takes up
a small, constant amount of space. Any copy is a tag; and if you start committing on a copy, then
it's a branch as well. (This does away with CVS's "branch-point tagging", by removing the
distinction that made branch-point tags necessary in the first place.)
* Natively client/server, layered library design
Subversion is designed to be client/server from the beginning; thus avoiding some of the maintenance
problems which have plagued CVS. The code is structured as a set of modules with well-defined
interfaces, designed to be called by other applications.
* Client/server protocol sends diffs in both directions
The network protocol uses bandwidth efficiently by transmitting diffs in both directions whenever
possible (CVS sends diffs from server to client, but not client to server).
* Costs are proportional to change size, not data size
In general, the time required for a Subversion operation is proportional to the size of the
changes resulting from that operation, not to the absolute size of the project in which the
changes are taking place. This is a property of the Subversion repository model.
* Choice of database or plain-file repository implementations
Repositories can be created with either an embedded database back-end (BerkeleyDB) or with
normal flat-file back-end, which uses a custom format.
* Versioning of symbolic links
Unix users can place symbolic links under version control. The links are recreated in Unix
working copies, but not in win32 working copies.
* Efficient handling of binary files
Subversion is equally efficient on binary as on text files, because it uses a binary diffing
algorithm to transmit and store successive revisions.
* Parseable output
All output of the Subversion command-line client is carefully designed to be both human readable
and automatically parseable; scriptability is a high priority.
* Localized messages
Subversion uses gettext() to display translated error, informational, and help messages, based
on current locale settings.
* Repository mirroring
Subversion supplies a utility, svnsync for synchronizing (via either push or pull) a read-only
slave repository with a master repository.
3.Glossary
SVN : Subversion;
SVN_HOME : The directory which Subversion programs lies in
REPOS_HOME : The directory of your repository
APACHE_HOME : The directory which Apache programs lies in
4.Install
4.1 Basic Requirement
N/A
4.2 Download
Currently, the latest version is 1.4.3, you can download it from http://subversion.tigris.org/.
URL links:
http://subversion.tigris.org/downloads/svn-win32-1.4.3.zip
If you want to configure SVN with Apache, then please download Apache also.
URL links:
http://apache.miroir-francais.fr/httpd/binaries/win32/apache_2.0.59-win32-x86-no_ssl.msi
[NOTICE]: Currently ,the latest Apache version is 2.2.4, but for SVN,the available Apache version
is 2.0.x, but unavailable for Apache 2.2.x;
#The reason is "mod_dav_svn.so" of SVN isn't compatible with Apache2.2.x for Win,
But for their Linux version, they work pretty well.
If you want to make you SNV to an (WinXP)System Service, you also need an service wrapper who
named "svnservice".I strongly suggest you to download it.
URL links:
http://www.stanford.edu/~bsuter/subversion-setup-guide/SVNService.zip
[NOTICE]:To use SVNservice, it needs the support of MicroSoft dotnet frameworks, if you haven't
installed it on your PC, you can download it from :
http://download.microsoft.com/download/5/6/7/567758a3-759e-473e-bf8f-52154438565a/dotnetfx.exe
#This this the latest version: dotnetfx2.0;
4.3 Install Subversion
Install Subversioin:
Quite easy just extract "svn-win32-1.4.3.zip" to your directory.
Install Apache:
Quite easy too.
[NOTICE]: If on your PC, it already start some services, e.g. IIS, Oracle Http Server... these applications
will occupy "80" port, so please make sure stop them(release 80 port) before installing Apache Server.
Install SVNservice (Service Wrapper):
Extract "SVNservice.exe" from SVNService.zip, and then copy it into %SVN_HOME%/bin directory.
[NOTICE]: If you haven't installed MicroSoft dotnet frameworks on your PC, it's better to install it now.
5.Configuration
I strongly suggest you to add "SVN_HOME" to your System Environment Variables, and add %SVN_HOME%/bin to the
System "PATH" variable.
5.1 Create repository
EXAMPLE-1 : create an repository named "project1" on "d:/myrepos";
>svnadmin create d:/myrepos/project1
>dir d:/myrepos/project1
d:/myrepos/project1
├─conf
├─dav
├─db
│ ├─revprops
│ ├─revs
│ └─transactions
├─hooks
└─locks
[NOTICE]: in /conf, there're 3 important files:
1)svnserve.conf
#the central mechanism for controlling authentication and authorization policies
e.g.
[general]
#Spicific a file that contains a list of usernames and passwords
password-db = passwd
# Specific access rules for specific locations
authz-db = authz
realm = example realm
# anonymous users can only read the repository
anon-access = read
# authenticated users can both read and write
auth-access = write
2)passwd
#a file that contains a list of usernames and passwords
e.g.
[users]
harry = foopassword
sally = barpassword
3)authz
#a file that contains access rules for specific locations
EXAMPLE-2 : create 2 repositories named "project1" and "project2";
>svnadmin create d:/myrepos/project1
>svnadmin create d:/myrepos/project2
>dir d:/myrepos
d:/myrepos
├─project1
│ ├─conf
│ ├─dav
│ ├─db
│ │ ├─revprops
│ │ ├─revs
│ │ └─transactions
│ ├─hooks
│ └─locks
└─project2
├─conf
├─dav
├─db
│ ├─revprops
│ ├─revs
│ └─transactions
├─hooks
└─locks
sometimes in order to manage our projects more easily,we usually use the same "passwd" and "authz" for them.
We can modify the svnserve.conf of project1 and project2 like below:
e.g.
password-db = ../../passwd
authz-db = ../../authz
anon-access = none #restricts all access of any kind for Anonymous Users
5.2 Configure SVN
The main configuration files lies in "%REPOS_HOME%/conf"
#Please refer to chapter 5.1
1)Congigure "svnserve.conf"
e.g.
anon-access = read
auth-access = write
password-db = passwd
2)Congigure "passwd"
e.g.
[users]
admin = abcd#1234
user = abcd#1234
guest = abcd#1234
3)Configure "authz"
e.g.
[groups]
# harry_and_sally = harry,sally
# [/foo/bar]
# harry = rw
# * =
# [repository:/baz/fuz]
# @harry_and_sally = rw
# * = r
[/]
* = r
user = rw
guest = r
admin = rw
[project1:/trunk]
user = r
guest =
admin = rw
5.3 Import your project
I strongly suggest you to create the following 3 directories in your project,and put all your
project file in "/trunk" directory.
/branches
/tags
/trunk #put all your project files here.
[NOTICE]: This behavior is not mandatory,just a practice/habit.
Now, let's begin our import action.
e.g. c:/project1
project1/branches
project1/tags
project1/trunk
>svn import c:/project1 file:///d:/myrepos/project1 -m "initial import"
"c:/project1" : our porject directory
"file:///d:/myrepos/project1" : the target repository
There are some useful commands:
1) "svn list": to browse the repository.
>svn list file:///d:/myrepos/project1
2) "svn checkout"
>svn checkout file:///d:/myrepos/project1/trunk c:/myproject1
5.4 Start SVN service
Use "svnserve":
>svnserve -d -r d:/myrepos/project1
>svnserve -d -r d:/myrepos/project2
You can also run the following command to start all repositories in "d:/myrepos"
>svnserve -d -r d:/myrepos
After it start successfully, you could acces the repository by SVN protocal:
svn://localhost/project1
svn://localhost/project2
Use SVNservice:
#a wrapper for adding the svnserve to WinXP System Service.
Usage instructions:
SVNService -? to display this list
SVNService -install <svnserve params> to install the service
SVNService -remove to remove the service
SVNService -setup <svnserve params> to change command line parameters for svnserve
SVNService -debug to run as a console app for debugging
Example:
SVNService -install -d -r c:/repos
SVNService -setup -d -r c:/repos
IMPORTANT:
Make sure you place SVNService.exe in the same directory as svnserve.exe
For our example:
>SVNService -install -d -r d:/myrepos/project1
>SVNService -install -d -r d:/myrepos
#to access all repositories
After that, please open Control Panel -> Administrative Tools -> Services, if it's successfully
installed, you can see and start/stop the "SVNService" item, it's a better way to modify its
properties and set the Startup Type with "automatic".
6.Configure SVN with Apache
1)httpd.conf
This file lies in "%APACHE_HOME%/conf".
First, copy %SVN_HOME%/bin/mod_dav_svn.so & mod_authz_svn.so to %APACHE_HOME%/modules,then
modify %APACHE_HOME%/conf/httpd.conf as below.
#uncomment this line
LoadModule dav_module modules/mod_dav.so
#add the following modules
LoadModule dav_svn_module modules/mod_dav_svn.so
LoadModule authz_svn_module modules/mod_authz_svn.so
Second, add <Location> tag at the end of httpd.conf.
Exam-1: no authentication,your repository is “anonymously” accessible to the world
<Location /svn>
DAV svn
SVNPath d:/myrepos
#ServerName svn.example.com
</Location>
[NOTICE]:
1.Any "/svn/project1" URL will map to "d:/myrepos/project1",but "/svn" (root) doesn't allow
to access, otherwise you'll get 403 forbidden error.
2.Be sure that when you define your new Location, it doesn't overlap with other exported Locations.
For example, if your main DocumentRoot is exported to /www, do not export a Subversion repository
in <Location /www/repos>. If a request comes in for the URI /www/repos/foo.c, Apache won't know
whether to look for a file repos/foo.c in the DocumentRoot, or whether to delegate mod_dav_svn
to return foo.c from the Subversion repository
Exam-2: has authentication
step1:
To use "%APACHE_HOME%/bin/htpasswd.exe" utility for managing the list of acceptable usernames
and passwords.
e.g.
First time, need "-c" to create the auth file
>htpasswd -cm d:/myrepos/svn-auth-file admin
New password: *****
Re-type new password: *****
Adding password for user admin
Add an new user, donot need "-c" parmeter
>htpasswd -m d:/myrepos/svn-auth-file user
New password: *******
Re-type new password: *******
Adding password for user user
step2:
Write <Location> tag:
<Location /svn>
DAV svn
SVNParentPath d:/myrepos
# how to authenticate a user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile d:/myrepos/svn-auth-file
# only authenticated users may access the repository
Require valid-user
</Location>
[NOTICE]:
Require valid-user :
tells Apache that all requests require an authenticated user
Limit and LimitExcept:
The parameters present on the Limit and LimitExcept directives are HTTP request types
that are affected by that block. For example, if you wanted to disallow all access to
your repository except the currently supported read-only operations, you would use
the LimitExcept directive, passing the GET, PROPFIND, OPTIONS, and REPORT request
type parameters. Then the previously mentioned Require valid-user directive would
be placed inside the <LimitExcept> block instead of just inside the <Location> block.
e.g.
<Location /svn>
DAV svn
SVNParentPath d:/myrepos
# how to authenticate a user
AuthType Basic
AuthName "Subversion repository"
AuthUserFile d:/myrepos/svn-auth-file
# For any operations other than these, require an authenticated user.
<LimitExcept GET PROPFIND OPTIONS REPORT>
Require valid-user
</LimitExcept>
</Location>
2)Restart Apache, access your repository by the following URL:
http://localhost/svn/project1
http://localhost/svn/project2
[NOTICE]: The root URL (http://localhost/svn) doesn't allow to access, otherwise you'll get
403 forbidden error.
7.SVN client
SmartSVN:
http://www.syntevo.com/smartsvn/
TortoiseSVN
http://www.tortoisesvn.net/downloads
8.Issues
N/A
9.Reference
1)basic commands
svn The command-line client program.
svnversion A program for reporting the state (in terms of revisions of the items present) of
a working copy.
svnlook A tool for inspecting a Subversion repository.
svnadmin A tool for creating, tweaking or repairing a Subversion repository.
svndumpfilter A program for filtering Subversion repository dumpfile format streams.
mod_dav_svn A plug-in module for the Apache HTTP Server, used to make your repository available
to others over a network.
svnserve A custom standalone server program, runnable as a daemon process or invokable by SSH;
another way to make your repository available to others over a network.
2)Links
http://subversion.tigris.org/
http://svnbook.red-bean.com/
#authz
http://svnbook.red-bean.com/nightly/en/svn.serverconfig.httpd.html#svn.serverconfig.httpd.authz.perdir
http://subversion.tigris.org/svn_1.3_releasenotes.html#svnserve-authz
#organize your repository
http://svnbook.red-bean.com/nightly/en/svn.reposadmin.projects.html#svn.reposadmin.projects.chooselayout
-END-