“Please make sure your seat backs are in their full, upgright position, and that your tray tables are stored. Flight attendants, prepare for take-off….”
The following is a very high-level tutorial which will walk you through some basic Subversion configuration and operation. By the time you complete the tutorial, you should have a basic understanding of Subversion's typical usage.
The examples used in this appendix assume that you have svn, the Subversion command-line client, and svnadmin, the administrative tool, ready to go. It also assumes you are using Subversion 1.2 or later (run svn --version to check.)
Subversion stores all versioned data in a central repository. To begin, create a new repository:
$ svnadmin create /path/to/repos $ ls /path/to/repos conf/ dav/ db/ format hooks/ locks/ README.txt
This command creates a new directory
/path/to/repos which contains a Subversion
repository. This new directory contains (among other things) a
collection of database files. You won't see your versioned
files if you peek inside. For more information about repository
creation and maintenance, see
Chapter 5, Repository Administration.
Subversion has no concept of a “project”. The repository is just a virtual versioned filesystem, a large tree that can hold anything you wish. Some administrators prefer to store only one project in a repository, and others prefer to store multiple projects in a repository by placing them into separate directories. The merits of each approach are discussed in the section called “Planning Your Repository Organization”. Either way, the repository only manages files and directories, so it's up to humans to interpret particular directories as “projects”. So while you might see references to projects throughout this book, keep in mind that we're only ever talking about some directory (or collection of directories) in the repository.
In this example, we assume that you already have some sort
of project (a collection of files and directories) that you wish
to import into your newly created Subversion repository. Begin
by organizing them into a single directory
myproject (or whatever you wish).
For reasons that will be clear later (see
Chapter 4, Branching and Merging), your project's tree
structure should contain three top-level directories
directory should contain all of your data,
tags directories are empty:
/tmp/myproject/branches/ /tmp/myproject/tags/ /tmp/myproject/trunk/ foo.c bar.c Makefile …
trunk subdirectories aren't actually
required by Subversion. They're merely a popular convention
that you'll most likely want to use later on.
Once you have your tree of data ready to go, import it into the repository with the svn import command (see the section called “Getting Data into your Repository”):
$ svn import /tmp/myproject file:///path/to/repos/myproject -m "initial import" Adding /tmp/myproject/branches Adding /tmp/myproject/tags Adding /tmp/myproject/trunk Adding /tmp/myproject/trunk/foo.c Adding /tmp/myproject/trunk/bar.c Adding /tmp/myproject/trunk/Makefile … Committed revision 1. $
Now the repository contains this tree of data. As mentioned
earlier, you won't see your files by directly peeking into the
repository; they're all stored within a database. But the
repository's imaginary filesystem now contains a top-level
myproject, which in turn
contains your data.
Note that the original
directory is unchanged; Subversion is unaware of it. (In fact,
you can even delete that directory if you wish.) In order to
start manipulating repository data, you need to create a new
“working copy” of the data, a sort of private
workspace. Ask Subversion to “check out” a working
copy of the
myproject/trunk directory in
$ svn checkout file:///path/to/repos/myproject/trunk myproject A myproject/foo.c A myproject/bar.c A myproject/Makefile … Checked out revision 1.
Now you have a personal copy of part of the repository in a
new directory named
myproject. You can edit
the files in your working copy and then commit those changes
back into the repository.
Enter your working copy and edit a file's contents.
Run svn diff to see unified diff output of your changes.
Run svn commit to commit the new version of your file to the repository.
Run svn update to bring your working copy “up-to-date” with the repository.
For a full tour of all the things you can do with your working copy, read Chapter 2, Basic Usage.
At this point, you have the option of making your repository available to others over a network. See Chapter 6, Server Configuration to learn about the different sorts of server processes available and how to configure them.
### TODO: Let's make this into a full tutorial, rather than simply referring off to other sections. ###