<?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>Getting Data into Your Repository</title> <link rel="stylesheet" type="text/css" href="styles.css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /> <style type="text/css"> body { background-image: url('images/draft.png'); background-repeat: no-repeat; background-position: top left; /* The following properties make the watermark "fixed" on the page. */ /* I think that's just a bit too distracting for the reader... */ /* background-attachment: fixed; */ /* background-position: center center; */ }</style> <link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" /> <link rel="up" href="svn.tour.html" title="Chapter 2. Basic Usage" /> <link rel="prev" href="svn.tour.help.html" title="Help!" /> <link rel="next" href="svn.tour.initial.html" title="Creating a Working Copy" /> </head> <body> <div xmlns="" id="vcws-version-notice"> <p>This text is a work in progress—highly subject to change—and may not accurately describe any released version of the Apache™ Subversion® software. Bookmarking or otherwise referring others to this page is probably not such a smart idea. Please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a> for stable versions of this book.</p> </div> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Getting Data into Your Repository</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="svn.tour.help.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.initial.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="svn.tour.importing"></a>Getting Data into Your Repository</h2> </div> </div> </div> <p>You can get new files into your Subversion repository in two ways: <span class="command"><strong>svn import</strong></span> and <span class="command"><strong>svn add</strong></span>. We'll discuss <span class="command"><strong>svn import</strong></span> now and will discuss <span class="command"><strong>svn add</strong></span> later in this chapter when we review a typical day with Subversion.</p> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.tour.importing.import"></a>Importing Files and Directories</h3> </div> </div> </div> <a id="idm956" class="indexterm"></a> <p>The <span class="command"><strong>svn import</strong></span> command is a quick way to copy an unversioned tree of files into a repository, creating intermediate directories as necessary. <span class="command"><strong>svn import</strong></span> doesn't require a working copy, and your files are immediately committed to the repository. You typically use this when you have an existing tree of files that you want to begin tracking in your Subversion repository. For example:</p> <div class="informalexample"> <pre class="screen"> $ svn import /path/to/mytree \ http://svn.example.com/svn/repo/some/project \ -m "Initial import" Adding mytree/foo.c Adding mytree/bar.c Adding mytree/subdir Adding mytree/subdir/quux.h Committed revision 1. $ </pre> </div> <p>The previous example copied the contents of the local directory <code class="filename">mytree</code> into the directory <code class="filename">some/project</code> in the repository. Note that you didn't have to create that new directory first—<span class="command"><strong>svn import</strong></span> does that for you. Immediately after the commit, you can see your data in the repository:</p> <div class="informalexample"> <pre class="screen"> $ svn list http://svn.example.com/svn/repo/some/project bar.c foo.c subdir/ $ </pre> </div> <p>Note that after the import is finished, the original local directory is <span class="emphasis"><em>not</em></span> converted into a working copy. To begin working on that data in a versioned fashion, you still need to create a fresh working copy of that tree.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.tour.importing.layout"></a>Recommended Repository Layout</h3> </div> </div> </div> <p>Subversion provides the ultimate flexibility in terms of how you arrange your data. Because it simply versions directories and files, and because it ascribes no particular meaning to any of those objects, you may arrange the data in your repository in any way that you choose. Unfortunately, this flexibility also means that it's easy to find yourself <span class="quote">“<span class="quote">lost without a roadmap</span>”</span> as you attempt to navigate different Subversion repositories which may carry completely different and unpredictable arrangements of the data within them.</p> <p> <a id="idm978" class="indexterm"></a> <a id="idm980" class="indexterm"></a> <a id="idm982" class="indexterm"></a> <a id="idm984" class="indexterm"></a>To counteract this confusion, we recommend that you follow a repository layout convention (established long ago, in the nascency of the Subversion project itself) in which a handful of strategically named Subversion repository directories convey valuable meaning about the data they hold. Most projects have a recognizable <span class="quote">“<span class="quote">main line</span>”</span>, or <em class="firstterm">trunk</em>, of development; some <em class="firstterm">branches</em>, which are divergent copies of development lines; and some <em class="firstterm">tags</em>, which are named, stable snapshots of a particular line of development. So we first recommend that each project have a recognizable <em class="firstterm">project root</em> in the repository, a directory under which all of the versioned information for that project—and only that project—lives. Secondly, we suggest that each project root contain a <code class="filename">trunk</code> subdirectory for the main development line, a <code class="filename">branches</code> subdirectory in which specific branches (or collections of branches) will be created, and a <code class="filename">tags</code> subdirectory in which specific tags (or collections of tags) will be created. Of course, if a repository houses only a single project, the root of the repository can serve as the project root, too.</p> <p>Here are some examples:</p> <div class="informalexample"> <pre class="screen"> $ svn list file:///var/svn/single-project-repo trunk/ branches/ tags/ $ svn list file:///var/svn/multi-project-repo project-A/ project-B/ $ svn list file:///var/svn/multi-project-repo/project-A trunk/ branches/ tags/ $ </pre> </div> <p>We talk much more about tags and branches in <a class="xref" href="svn.branchmerge.html" title="Chapter 4. Branching and Merging">Chapter 4, <em>Branching and Merging</em></a>. For details and some advice on how to set up repositories when you have multiple projects, see <a class="xref" href="svn.branchmerge.maint.html#svn.branchmerge.maint.layout" title="Repository Layout">the section called “Repository Layout”</a>. Finally, we discuss project roots more in <a class="xref" href="svn.reposadmin.planning.html#svn.reposadmin.projects.chooselayout" title="Planning Your Repository Organization">the section called “Planning Your Repository Organization”</a>.</p> </div> <div class="sect2"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.tour.importing.naming"></a>What's In a Name?</h3> </div> </div> </div> <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">“<span class="quote">textual</span>”</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, 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).</p> <p>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 <code class="literal">TAB</code>, <code class="literal">CR</code>, and <code class="literal">LF</code> characters in path names to prevent paths from being broken up in diffs or in the output of commands such as <span class="command"><strong>svn log</strong></span> or <span class="command"><strong>svn status</strong></span>.</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—to create <span class="quote">“<span class="quote">legally correct</span>”</span> versions for internal use it will automatically escape illegal path characters as needed in URLs that you type.</p> <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Warning"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Warning]" src="images/warning.png" /> </td> <th align="left">Warning</th> </tr> <tr> <td align="left" valign="top"> <p>Of course, when it comes to choosing valid path names, Subversion isn't the only limiting factor. Teams using multiple operating systems need to consider the limitations placed on path names by those operating systems, too. For example, while Windows disallows the use of colon characters in file names, a user on a Linux system can very easily add such a file to version control, resulting in a dataset that can no longer be checked out on Windows. Adding multiple files to a directory whose names differ only in their letter casing will likewise cause problems for users checking out working copies onto case-insensitive filesystems. So, some broad awareness of the various limitations introduced by different operating systems and filesystems, then, is recommended.</p> </td> </tr> </table> </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.help.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.initial.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Help! </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Creating a Working Copy</td> </tr> </table> </div> <div xmlns="" id="vcws-footer"> <hr /> <img src="images/cc-by.png" style="float: right;" /> <p>You are reading <em>Version Control with Subversion</em> (for Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato.</p> <p>This work is licensed under the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p> <p>To submit comments, corrections, or other contributions to the text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p> </div> </body> </html>