Subversion Simple Guide

<<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-