<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Initial Checkout</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.tour.html" title="Chapter 2. Basic Usage" /><link rel="prev" href="svn.tour.importing.html" title="Getting Data into your Repository" /><link rel="next" href="svn.tour.cycle.html" title="Basic Work Cycle" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Initial Checkout</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.tour.importing.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Basic Usage</th><td width="20%" align="right"> <a accesskey="n" href="svn.tour.cycle.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.tour.initial"></a>Initial Checkout</h2></div></div></div><p>Most of the time, you will start using a Subversion
repository by doing a <em class="firstterm">checkout</em> of your
project. Checking out a repository creates a “<span class="quote">working
copy</span>” of it on your local machine. This copy contains
the <code class="literal">HEAD</code> (latest revision) of the Subversion
repository that you specify on the command line:</p><pre class="screen">
$ 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.
</pre><div class="sidebar"><p class="title"><b>What's in a Name?</b></p><p>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
<a class="xref" href="svn.advanced.props.file-portability.html#svn.advanced.props.special.mime-type" title="File Content Type">the section called “File Content Type”</a>
tells you how to give Subversion a hint that
“<span class="quote">textual</span>” operations don't make sense for a
particular file. There are a few places, however, where
Subversion places restrictions on information it
stores.</p><p>Subversion internally handles certain bits of
data—for example, property names, path names, 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).</p><p>In addition, path names are used as XML attribute values
in WebDAV exchanges, as well in as some of Subversion's
housekeeping files. This means that path names can only
contain legal XML (1.0) 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 like
<a class="xref" href="svn.ref.svn.c.log.html" title="svn log">svn log</a> or <a class="xref" href="svn.ref.svn.c.status.html" title="svn status">svn status</a>.</p><p>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—it will automatically escape illegal
path characters as needed in URLs you type to create
“<span class="quote">legally correct</span>” versions for internal
use.</p></div><p>Although the above 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:</p><pre class="screen">
$ 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.
</pre><p>Since Subversion uses a “<span class="quote">copy-modify-merge</span>”
model instead of “<span class="quote">lock-modify-unlock</span>” (see <a class="xref" href="svn.basic.vsn-models.html" title="Versioning Models">the section called “Versioning Models”</a>), you can start right in
making 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
them, move them around, you can even delete the entire working
copy and forget about it.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>While your working copy is “<span class="quote">just like any other
collection of files and directories on your system</span>”,
you can edit files at will, but you must tell Subversion
about <span class="emphasis"><em>everything else</em></span> that you do. For
example, if you want to copy or move an item in a working
copy, you should use <span class="command"><strong>svn copy</strong></span> or
<span class="command"><strong>svn move</strong></span> instead of the copy and move
commands provided by your operating system. We'll talk more
about them later in this chapter.</p></div><p>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.</p><div class="sidebar"><p class="title"><b>What's with the <code class="filename">.svn</code> directory?</b></p><p>Every directory in a working copy contains an
administrative area, a subdirectory named
<code class="filename">.svn</code>. 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.</p><p>If you accidentally remove the <code class="filename">.svn</code>
subdirectory, the easiest way to fix the problem is to remove
the entire containing directory (a normal system deletion,
not <span class="command"><strong>svn delete</strong></span>), then run <span class="command"><strong>svn
update</strong></span> from a parent directory. The Subversion
client will re-download the directory you've deleted, with a
new <code class="filename">.svn</code> area as well.</p></div><p>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:</p><pre class="screen">
$ 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.
</pre><p>That will place your working copy in a directory named
<code class="literal">subv</code> instead of a directory named
<code class="literal">trunk</code> as we did previously. The directory
<code class="literal">subv</code> will be created if it doesn't already
exist.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.initial.disabling-password-caching"></a>Disabling Password Caching</h3></div></div></div><p>When you perform a Subversion operation that requires you
to authenticate, by default Subversion caches your
authentication credentials on disk. This is done for
convenience, so that you don't have to continually re-enter
your password for future operations. If you're concerned
about caching your Subversion passwords,<sup>[<a id="id349720" href="#ftn.id349720" class="footnote">4</a>]</sup>
you can disable caching either permanently or on a
case-by-case basis.</p><p>To disable password caching for a particular one-time
command, pass the <code class="option">--no-auth-cache</code> option on
the commandline. To permanently disable caching, you can add
the line <code class="literal">store-passwords = no</code> to your local
machine's Subversion configuration file. See <a class="xref" href="svn.serverconfig.netmodel.html#svn.serverconfig.netmodel.credcache" title="Client Credentials Caching">the section called “Client Credentials Caching”</a> for
details.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="svn.tour.initial.different-user"></a>Authenticating as a Different User</h3></div></div></div><p>Since Subversion caches auth credentials by default (both
username and password), it conveniently remembers who you were
acting as the last time you modified you working copy. But
sometimes that's not helpful—particularly if you're
working in a shared working copy, like a system configuration
directory or a webserver document root. In this case, just
pass the <code class="option">--username</code> option on the
commandline and Subversion will attempt to authenticate as
that user, prompting you for a password if necessary.</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id349720" href="#id349720" class="para">4</a>] </sup>Of
course, you're not terribly worried—first because you
know that you can't <span class="emphasis"><em>really</em></span> delete
anything from Subversion and, secondly, because your
Subversion password isn't the same as any of the other three
million passwords you have, right? Right?</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="svn.tour.importing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="svn.tour.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="svn.tour.cycle.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Getting Data into your Repository </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Basic Work Cycle</td></tr></table></div></body></html>
