Login | Join Now
  • Initial Checkout
    Prev Chapter 2. Basic Usage Next

    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, 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).

    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 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–it will automatically escape illegal path characters as needed in URLs you type to create “legally correct” versions for internal use.

    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:

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

    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 re-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 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,[3] you can disable caching either permanently or on a case-by-case basis.

    To disable password caching for a particular one-time command, pass the --no-auth-cache option on the commandline. To permanently disable caching, 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 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 --username option on the commandline and Subversion will attempt to authenticate as that user, prompting you for a password if necessary.


    [3] Of course, you're not terribly worried–first because you know that you can't really 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?

    Prev Up Next
    Getting Data into your Repository Home Basic Work Cycle

    The Version Control with Subversion book 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.