Initial Checkout

Most of the time, you will start using a Subversion
repository by doing a checkout of your
project. Checking out a repository creates a “working
copy” of it on your local machine. This copy contains
the HEAD (latest revision) of the Subversion
repository that you specify on the command line:

$ svn checkout http://svn.collab.net/repos/svn/trunk
A trunk/Makefile.in
A trunk/ac-helpers
A trunk/ac-helpers/install.sh
A trunk/ac-helpers/install-sh
A trunk/build.conf
…
Checked out revision 8810.

What's in a Name?

Subversion tries hard not to limit the type of data you
can place under version control. The contents of files and
property values are stored and transmitted as binary data, and
the section called “File Content Type”
tells you how to give Subversion a hint that
“textual” operations don't make sense for a
particular file. There are a few places, however, where
Subversion places restrictions on information it
stores.

Subversion internally handles certain bits of
data—for example, property names, pathnames, and log
messages—as UTF-8-encoded Unicode. This is not to say
that all your interactions with Subversion must involve UTF-8,
though. As a general rule, Subversion clients will gracefully
and transparently handle conversions between UTF-8 and the
encoding system in use on your computer, if such a conversion
can meaningfully be done (which is the case for most common
encodings in use today).

In WebDAV exchanges and older versions of some of
Subversion's administrative files, paths are used as XML
attribute values, and property names in XML tag names. This
means that pathnames can contain only legal XML (1.0)
characters, and properties are further limited to ASCII
characters. Subversion also prohibits TAB,
CR, and LF characters in
path names to prevent paths from being broken up in diffs or
in the output of commands such as svn log
or svn status.

While it may seem like a lot to remember, in practice
these limitations are rarely a problem. As long as your
locale settings are compatible with UTF-8 and you don't use
control characters in path names, you should have no trouble
communicating with Subversion. The command-line client adds
an extra bit of help—to create
“legally correct” versions for internal
use it will automatically escape illegal
path characters as needed in URLs that you type.

Although the preceding example checks out the trunk directory,
you can just as easily check out any deep subdirectory of a
repository by specifying the subdirectory in the checkout
URL:

$ svn checkout \
http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/
A cmdline/revert_tests.py
A cmdline/diff_tests.py
A cmdline/autoprop_tests.py
A cmdline/xmltests
A cmdline/xmltests/svn-test.sh
…
Checked out revision 8810.

Since Subversion uses a copy-modify-merge
model instead of lock-modify-unlock (see
the section called “Versioning Models”), you can immediately
make changes to the files and directories in your working
copy. Your working copy is just like any other collection of
files and directories on your system. You can edit and change
it, move it around, even delete the entire working copy and
forget about it.

Warning

While your working copy is “just like any other
collection of files and directories on your system,”
you can edit files at will, but you must tell Subversion
about everything else that you do. For
example, if you want to copy or move an item in a working
copy, you should use svn copy or
svn move instead of the copy and move
commands provided by your operating system. We'll talk more
about them later in this chapter.

Unless you're ready to commit the addition of a new file or
directory or changes to existing ones, there's no need to
further notify the Subversion server that you've done
anything.

What's with the .svn Directory?

Every directory in a working copy contains an
administrative area—a subdirectory named
.svn. Usually, directory listing
commands won't show this subdirectory, but it is nevertheless
an important directory. Whatever you do, don't delete or
change anything in the administrative area! Subversion
depends on it to manage your working copy.

If you accidentally remove the .svn
subdirectory, the easiest way to fix the problem is to remove
the entire containing directory (a normal system deletion,
not svn delete), then run svn
update from a parent directory. The Subversion
client will download the directory you've deleted, with a
new .svn area as well.

While you can certainly check out a working copy with the
URL of the repository as the only argument, you can also specify
a directory after your repository URL. This places your working
copy in the new directory that you name. For example:

$ svn checkout http://svn.collab.net/repos/svn/trunk subv
A subv/Makefile.in
A subv/ac-helpers
A subv/ac-helpers/install.sh
A subv/ac-helpers/install-sh
A subv/build.conf
…
Checked out revision 8810.

That will place your working copy in a directory named
subv instead of a directory named
trunk as we did previously. The directory
subv will be created if it doesn't already
exist.

Disabling Password Caching

When you perform a Subversion operation that requires you
to authenticate, by default Subversion tries to cache your
authentication credentials on disk in encrypted form.
On some systems, Subversion may be unable to encrypt your
authentication data. You will then be asked whether you
want to cache your credentials to disk in plaintext.
You can choose to do so for convenience so that you don't have
to continually reenter your password for future operations.
If you're concerned about caching your Subversion passwords
in plaintext and do not want to be asked about it again and
again, you can disable caching of plaintext passwords either
permanently, or on a server-per-server basis.

To permanently disable caching of passwords in plaintext,
you can add the line
store-plaintext-passwords = no
to the global section in the servers
configuration file on the local machine. To disable caching
of plaintext passwords for a particular server, use the same
setting in the appropriate group section in the
servers configuration file.
See the section called “Configuration Options”
in Chapter 7, Customizing Your Subversion Experience for details.

You can also disable caching of authentication credentials
entirely, regardless of whether the credentials are stored
in encrypted form or not.

To disable password caching entirely for a particular one-time
command, pass the --no-auth-cache option on
the command line. To permanently disable caching entirely,
you can add the line store-passwords = no
to your local machine's Subversion configuration file. See the section called “Client Credentials Caching” for
details.

Authenticating As a Different User

Since Subversion caches auth credentials by default (both
username and password), it conveniently remembers who you were
acting as the last time you modified your working copy. But
sometimes that's not helpful—particularly if you're
working in a shared working copy such as a system
configuration directory or a web server document root. In this
case, just pass the --username option on the
command line, and Subversion will attempt to authenticate as
that user, prompting you for a password if necessary.

You are reading Version Control with Subversion (for Subversion 1.6), by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato.
This work is licensed under the Creative Commons Attribution License v2.0.
To submit comments, corrections, or other contributions to the text, please visit http://www.svnbook.com/.