======================================
Subversion for Personal Use Mini-HOWTO
======================================

by David Baird

Why should an individual person use Subversion for their own personal
work?

    Subversion is very easy to use, for individual use.  It is easy to
    setup as many personal repositories as you want and it is easy to
    access the repositories.  The Subversion commands are similar to
    cvs commands and to shell commands.  For instance, to make a new
    directory under version control, you would type "svn mkdir bla".

Why should I use the FSFS backend, especially for personal use?

    Read-only access to the repository is permitted.  This might be
    useful if you use WebSVN which runs in mod_php, and thus as the
    apache user and not yourself... and you most surely do not want to
    give apache write access to your files.

    The BDB backend requires read-write access to the repository no
    matter what... I think =)

    NFS friendliness: FSFS is much more NFS friendly than BDB.

    Multi-access methods: many different clients/servers can
    simultaneously access an FSFS repository.  This can cause annoying
    "wedging" (deadlocking) in BDB that has to be repaired with the
    svnadmin command.

What about running Subversion through Apache?

    ...for personal use?  Do not do this until you a fairly experienced
    with Subversion.  There are lots of permission, access control, and
    authentication pains to deal with when using HTTP for Subversion.
    This will make you hurt a lot, unless you are already familiar with
    the many constraints you are about to play with.  For personal use,
    I recommend using a file:// url that points to a repository in your
    personal home directory.

    ...for use by many people?  I highly recommend Apache, but that is
    not the topic of this mini-HOWTO.

How the heck do I get started using Subversion for personal use?

    I setup my project directories like this:

    ~/project/20031224.fx2_usb/
    ~/project/20040802.sequencer/
    ~/project/20041025.gantt/
    etc..

    Let's examine ~/project/20031224.fx2_usb.  I have:

    ~/project/20031224.fx2_usb/svn/
    ~/project/20031224.fx2_usb/wc/
    ~/project/20031224.fx2_usb/wc/fx2_usb/
    ~/project/20031224.fx2_usb/wc/fx2_usb/trunk/

    The `svn` directory contains the Subversion repository for this
    project.  The `wc` directory is the "working copy" of the repository.
    You get a working copy by checking it out from the repository.
    The repository is generally organized like this:

        projectname/trunk/
        projectname/tags/
        projectname/branches/

    In this case, the project name is `fx2_usb` and I do not yet have
    directories for tags or branches.  It may seem redundant to use a
    projectname in the repository's directory structure, but just do it
    anyways: you'll appreciate it later.

    So, here's what we do to get this project rolling, from scratch.

    # - - -   Prepare directories   - - -
    mkdir -p ~/project/20031224.fx2_usb
    cd ~/project/20031224.fx2_usb
    mkdir -p {svn,wc,import}
    mkdir -p import/fx2_usb/{trunk,branches,tags}

    To summarize, your directory structure should now look like this
    (if you run the `find` command):

        projectname/
        projectname/wc
        projectname/svn
        projectname/import
        projectname/import/projectname
        projectname/import/projectname/tags
        projectname/import/projectname/trunk
        projectname/import/projectname/branches

    # - - -   Create the repository, and perform initial import   - - -
    svnadmin create --fs-type fsfs svn/
    svn import import/fx2_usb file://localhost/home/dbaird/project/20031224.fx2_usb/svn/fx2_usb
    <don't forget to type fx2_usb for both the source and destination!!!>
    # - - -   Check out a working copy   - - -
    cd wc
    svn co file://localhost/home/dbaird/project/20031224.fx2_usb/svn/ .
    svn info # check to see if you correctly did a checkout
    # - - -   Remove the initial import, (if checkout succeeded)   - - -
    cd ..
    rm -Rf import

How do I access my personal repositories across a network?

    This is easy unless you want to start sharing with other people
    (see next question).  Use an ssh+svn:// url like so:

        svn co svn+ssh://hostname/home/username/bla/repository

How to share repositories with other people?

    I highly recommend Apache, but that is not the topic of this
    mini-HOWTO because Apache more-or-less requires administrator access
    to a computer.

    Well... if we forget about the Apache option, and I won't even
    bother going into the /etc/group option (since only sysadmins have
    access to this and also since it isn't a very good option anyways),
    then you do this:

        1. Setup user authentication information
        2. Start an svnserver process
        3. Connect with an svn:// url

    File: /path-to-repo/conf/svnserve.conf

        [general]
        password-db = passwd

    File: /path-to-repo/conf/passwd

        [users]
        dbaird = moo

    Now start svnserve,

        svnserve -d --listen-port 6789 -r /path-to-repo

    If you want to require people to ssh in to the box (or ssh port
    forward to the box, which is what I do), then add the option
    `--listen-host localhost` to only accept connections to localhost
    (ie. prohibit access via public IP address).

    Now you can checkout from the svnserver:

        svn co svn://hostname:6789/ .

Want more information?

    Read the excellent Subversion book.  Just search google for
    "Subversion" and "book".

    Type `svn help`.

    This mini-HOWTO tells you a lot of what I wish someone told me when
    I first started Subversion.