<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-import">
  <title>Importing Data Into A Repository</title>
  <indexterm>
    <primary>import</primary>
  </indexterm>
  <indexterm>
    <primary>repository</primary>
  </indexterm>
  <indexterm>
    <primary>add files to repository</primary>
  </indexterm>
  <?dbhh topicname="HIDD_IMPORT"?>
  <sect2 id="tsvn-dug-import-2">
    <title>Import</title>
    <indexterm>
      <primary>temporary files</primary>
    </indexterm>
    <para>
      If you are importing into an existing repository which already
      contains some projects, then the repository structure will already
      have been decided.
      If you are importing data into a new repository, then it is worth
      taking the time to think about how it will be organised. Read
      <xref linkend="tsvn-repository-layout"/> for further advice.
    </para>
    <para>
      This section describes the Subversion import command, which was designed
      for importing a directory hierarchy into the repository in one shot.
      Although it does the job, it has several shortcomings:
      <itemizedlist>
        <listitem>
          <para>
            There is no way to select files and folders to include,
            aside from using the global ignore settings.
          </para>
        </listitem>
        <listitem>
          <para>
            The folder imported does not become a working copy. You have
            to do a checkout to copy the files back from the server.
          </para>
        </listitem>
        <listitem>
          <para>
            It is easy to import to the wrong folder level in the repository.
          </para>
        </listitem>
      </itemizedlist>
      For these reasons we recommend that you do not use the import command
      at all but rather follow the two-step method described in
      <xref linkend="tsvn-dug-import-in-place"/>, unless you are performing
      the simple step of creating an initial
      <filename>/trunk /tags /branches</filename> structure in your repository.
      Since you are here, this is how the basic import works ...
    </para>
    <para>
      Before you import your project into a repository you should:
      <orderedlist>
        <listitem>
          <para>
            Remove all files which are not needed to
            build the project (temporary files, files which are
            generated by a compiler e.g. *.obj, compiled
            binaries, ...)
          </para>
        </listitem>
        <listitem>
          <para>
            Organize the files in folders and
            sub-folders. Although it is possible to rename/move
            files later it is highly recommended to get your project's
            structure straight before importing!
          </para>
        </listitem>
      </orderedlist>
    </para>
    <para>
      Now select the top-level folder of your project
      directory structure in the windows explorer and
      <action>right click</action>
      to open the context menu. Select the command
      <menuchoice>
        <guimenu>TortoiseSVN</guimenu>
        <guimenuitem>Import...</guimenuitem>
      </menuchoice>
      which brings up a dialog box:
      <figure id="tsvn-dug-import-dia-1">
        <title>The Import dialog</title>
        <graphic fileref="../images/Import.png"/>
      </figure>
    </para>
    <para>
      In this dialog you have to enter the URL of the repository location
      where you want to import your project.
      It is very important to realise that the local folder you are
      importing does not itself appear in the repository, only its content.
      For example if you have a structure:
      <screen>
C:\Projects\Widget\source
C:\Projects\Widget\doc
C:\Projects\Widget\images
      </screen>
      and you import <filename>C:\Projects\Widget</filename> into
      <systemitem class="url">http://mydomain.com/svn/trunk</systemitem>
      then you may be surprised to find that your subdirectories go
      straight into <literal>trunk</literal> rather than being in a
      <literal>Widget</literal> subdirectory. You need to specify the
      subdirectory as part of the URL,
      <systemitem class="url">http://mydomain.com/svn/trunk/Widget-X</systemitem>.
      Note that the import command will automatically create subdirectories
      within the repository if they do not exist.
    </para>
    <para>
      The import message is used as a log message.
    </para>
    <para>
      By default, files and folders which match the global-ignore patterns
      are <emphasis>not</emphasis> imported. To override this behaviour you can
      use the <guilabel>Include ignored files</guilabel> checkbox.
      Refer to <xref linkend="tsvn-dug-settings-main"/> for more information
      on setting a global ignore pattern.
    </para>
    <para>
      As soon as you press <guibutton>OK</guibutton> TortoiseSVN imports the
      complete directory tree including all files into the repository.
      The project is now stored in the repository under version control.
      Please note that the folder you imported is <emphasis>NOT</emphasis>
      under version control! To get a version-controlled
      <firstterm>working copy</firstterm>
      you need to do a Checkout of the version you just imported.
      Or read on to find out how to import a folder in place.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-import-in-place">
    <title>Import in Place</title>
    <indexterm>
      <primary>import in place</primary>
    </indexterm>
    <para>
      Assuming you already have a repository, and you want to add a new folder
      structure to it, just follow these steps:
      <orderedlist>
        <listitem>
          <para>
            Use the repository browser to create a new
            project folder directly in the repository.
            If you are using one of the standard layouts you will probably
            want to create this as a sub-folder of trunk rather than in
            the repository root. The repository browser shows the repository
            structure just like Windows explorer, so you can see how
            things are organised.
          </para>
        </listitem>
        <listitem>
          <para>
            Checkout the new folder over the top of the folder you want to import.
            You will get a warning that the local folder is not empty. Ignore the warning.
            Now you have a versioned top level folder with unversioned content.
          </para>
        </listitem>
        <listitem>
          <para>
            Use
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Add...</guimenuitem>
            </menuchoice>
            on this versioned folder to add some or all of the content.
            You can add and remove files, set <literal>svn:ignore</literal>
            properties on folders and make any other changes you need to.
          </para>
        </listitem>
        <listitem>
          <para>
            Commit the top level folder, and you have a new versioned tree,
            and a local working copy, created from your existing folder.
          </para>
        </listitem>
      </orderedlist>
    </para>
  </sect2>
  <sect2 id="tsvn-dug-import-3">
    <title>Special Files</title>
    <indexterm>
      <primary>special files</primary>
    </indexterm>
    <para>
      Sometimes you need to have a file under version control which contains
      user specific data. That means you have a file which every developer/user
      needs to modify to suit his/her local setup. But versioning such a file
      is difficult because every user would commit his/her changes every
      time to the repository.
    </para>
    <para>
      In such cases we suggest to use <emphasis>template</emphasis> files.
      You create a file which contains all the data your developers
      will need, add that file to version control and let the developers
      check this file out. Then, each developer has to <emphasis>make a copy</emphasis>
      of that file and rename that copy. After that, modifying the copy
      is not a problem anymore.
    </para>
    <para>
      As an example, you can have a look at TortoiseSVN's build script. It
      calls a file named <filename>default.build.user</filename> which
      doesn't exist in the repository. Only the file
      <filename>default.build.user.tmpl</filename>.
      <filename>default.build.user.tmpl</filename> is the template file which
      every developer has to create a copy from and rename that file
      to <filename>default.build.user</filename>. Inside that file, we added
      comments so that the users will see which lines they have to edit
      and change according to their local setup to get it working.
    </para>
    <para>
      So as not to disturb the users, we also added the file
      <filename>default.build.user</filename> to the ignore list of its
      parent folder, i.e. we've set the Subversion property
      <literal>svn:ignore</literal> to include that filename.
      That way it won't show up as unversioned on every commit.
    </para>
  </sect2>
</sect1>
