<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-repository-create">
	<title>Repository Creation</title>
	<indexterm>
		<primary>create repository</primary>
	</indexterm>
	<para>
		You can create a repository with the FSFS backend or with the
		older Berkeley Database (BDB) format. The FSFS format
		is generally faster and easier to administer, and it works on
		network shares and Windows 98 without problems. The BDB format
		was once considered more stable simply because it has been in use
		for longer, but since FSFS has now been in use in the field for
		several years, that argument is now rather weak.
		Read
		<ulink url="http://svnbook.red-bean.com/en/1.5/svn.reposadmin.planning.html#svn.reposadmin.basics.backends">
			<citetitle>Choosing a Data Store</citetitle>
		</ulink>
		in the Git book for more information.
	</para>
	<sect2 id="tsvn-repository-create-commandline">
		<title>Creating a Repository with the Command Line Client</title>
		<indexterm>
			<primary>Create</primary>
			<secondary>Command Line Client</secondary>
		</indexterm>
		<orderedlist>
			<listitem>
				<para>
					Create an empty folder with the name SVN
					(e.g. <filename>D:\SVN\</filename>),
					which is used as root for all your repositories.
				</para>
			</listitem>
			<listitem>
				<para>
					Create another folder
					<filename>MyNewRepository</filename> inside
					<filename>D:\SVN\</filename>.
				</para>
			</listitem>
			<listitem>
				<para>
					Open the command prompt (or DOS-Box), change into 
					<filename>D:\SVN\</filename> and type
<screen>
svnadmin create --fs-type bdb MyNewRepository
</screen>
or
<screen>
svnadmin create --fs-type fsfs MyNewRepository
</screen>
				</para>
			</listitem>
		</orderedlist>
		<para>
			Now you've got a new repository located at
			<filename>D:\SVN\MyNewRepository</filename>.
		</para>
	</sect2>
	<!-- ================================================================= -->
	<sect2 id="tsvn-repository-create-TortoiseGit">
		<title>Creating The Repository With TortoiseGit</title>
		<indexterm>
			<primary>Create</primary>
			<secondary>TortoiseGit</secondary>
		</indexterm>
		<?dbhh topicname="HIDD_REPOCREATE"?>
		<figure id="tsvn-serversetup-local-dia-1">
			<title>The TortoiseGit menu for unversioned folders</title>
			<graphic fileref="../images/ContextMenuDirNoControl.png"/>
		</figure>
		<orderedlist>
			<listitem>
				<para>
					Open the windows explorer
				</para>
			</listitem>
			<listitem>
				<para>
					Create a new folder and name it e.g.
					<filename>SVNRepository</filename>
				</para>
			</listitem>
			<listitem>
				<para>
					<action>Right-click</action> on the newly created folder
					and select
					<menuchoice>
						<guimenu>TortoiseGit</guimenu>
						<guimenuitem>Create Repository here...</guimenuitem>
					</menuchoice>.
				</para>
				<para>
					A repository is then created inside the new folder.
					<emphasis>Don't edit those files yourself!!!</emphasis>.
					If you get any errors make sure that the folder is empty
					and not write protected.
				</para>
			</listitem>
		</orderedlist>
		<tip>
			<para>
				TortoiseGit no longer offers the option to create BDB repositories,
				although you can still use the command line client to create them.
				FSFS repositories are generally easier for you to maintain, and also
				makes it easier for us to maintain TortoiseGit due to compatibility
				issues between the different BDB versions.
			</para>
			<para>
				Future versions of TortoiseGit will not support
				<literal>file://</literal> access to BDB repositories due to these
				compatibility issues, although it will of course always support
				this repository format when accessed via a server through the
				<literal>svn://</literal>,
				<literal>http://</literal> or
				<literal>https://</literal> protocols.
				For this reason, we strongly recommend that any new repository
				which must be accessed using <literal>file://</literal>
				protocol is created as FSFS.
			</para>
			<para>
				Of course we also recommend that you don't use <literal>file://</literal>
				access at all, apart from local testing purposes. Using a server is
				more secure and more reliable for all but single-developer use.
			</para>
		</tip>
	</sect2>
	<!-- ================================================================= -->
	<sect2 id="tsvn-repository-local-access">
		<title>Local Access to the Repository</title>
		<indexterm>
			<primary>Access</primary>
		</indexterm>
		<indexterm>
			<primary>UNC paths</primary>
		</indexterm>
		<para>
			To access your local repository you need the path to that folder.
			Just remember that Git expects all repository paths in the form
			<systemitem class="url">file:///C:/SVNRepository/</systemitem>.
			Note the use of forward slashes throughout.
		</para>
		<para>
			To access a repository located on a network share you can either
			use drive mapping, or you can use the UNC path. For UNC paths,
			the form is
			<systemitem class="url">file://ServerName/path/to/repos/</systemitem>.
			Note that there are only 2 leading slashes here.
		</para>
		<para>
			Prior to SVN 1.2, UNC paths had to be given in the more obscure form
			<systemitem class="url">file:///\ServerName/path/to/repos</systemitem>.
			This form is still supported, but not recommended.
		</para>
	</sect2>
	<warning>
		<para>
			Do not create or access a Berkeley DB repository on a network share.
			It <emphasis>cannot</emphasis> exist on a remote file system.
			Not even if you have the network drive mapped to a drive letter.
			If you attempt to use Berkeley DB on a network share,
			the results are unpredictable - you may see mysterious errors
			right away, or it may be months before you discover that your
			repository database is subtly corrupted.
		</para>
	</warning>
	<sect2 id="tsvn-repository-local-share">
		<title>Accessing a Repository on a Network Share</title>
		<indexterm>
			<primary>Network share</primary>
		</indexterm>
		<para>
			Although in theory it is possible to put a FSFS repository on a network
			share and have multiple users access it using <literal>file://</literal>
			protocol, this is most definitely <emphasis>not</emphasis>
			recommended. In fact we would <emphasis>strongly</emphasis>
			discourage it, and do not support such use.
		</para>
		<para>
			Firstly you are giving every user direct write access to the
			repository, so any user could accidentally delete the entire repository
			or make it unusable in some other way.
		</para>
		<para>
			Secondly not all network file sharing protocols support the locking
			that Git requires, so you may find your repository gets corrupted.
			It may not happen straight away, but one day two users will try to access
			the repository at the same time.
		</para>
		<para>
			Thirdly the file permissions have to be set just so. You may just about
			get away with it on a native Windows share, but SAMBA is particularly
			difficult.
		</para>
		<para>
			<literal>file://</literal> access is intended for local, single-user
			access only, particularly testing and debugging. When you want to share
			the repository you <emphasis>really</emphasis> need to set up a proper server,
			and it is not nearly as difficult as you might think.
			Read <xref linkend="tsvn-serversetup"/> for guidelines on choosing and
			setting up a server.
		</para>
	</sect2>
	<sect2 id="tsvn-repository-layout">
		<title>Repository Layout</title>
		<para>
			Before you import your data into the repository you should
			first think about how you want to organize your data. If you
			use one of the recommended layouts you will later have it much
			easier.
		</para>
		<para>
			There are some standard, recommended ways to organize a
			repository. Most people create a <filename>trunk</filename>
			directory to hold the <quote>main line</quote> of development, a
			<filename>branches</filename> directory to contain branch
			copies, and a <filename>tags</filename> directory to contain
			tag copies. If a repository holds only one project, then
			often people create these top-level directories:
		</para>
<screen>
/trunk
/branches
/tags
</screen>
		<para>
			If a repository contains multiple projects, people often
			index their layout by branch:
		</para>
<screen>
/trunk/paint
/trunk/calc
/branches/paint
/branches/calc
/tags/paint
/tags/calc
</screen>
		<para>
			...or by project:
		</para>
<screen>
/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags
</screen>
		<para>
			Indexing by project makes sense if the projects are not closely related
			and each one is checked out individually. For related projects where
			you may want to check out all projects in one go, or where the projects
			are all tied together in a single distribution package, it is often better
			to index by branch. This way you have only one trunk to checkout, and
			the relationships between the sub-projects is more easily visible.
		</para>
		<para>
			If you adopt a top level <filename>/trunk /tags /branches</filename>
			approach, there is nothing to say that you have to copy the entire trunk
			for every branch and tag, and in some ways this structure offers the
			most flexibility.
		</para>
		<para>
			For unrelated projects you may prefer to use separate repositories.
			When you commit changes, it is the revision number of the whole
			repository which changes, not the revision number of the project.
			Having 2 unrelated projects share a repository can mean large gaps
			in the revision numbers. The Git and TortoiseGit projects
			appear at the same host address, but are completely separate
			repositories allowing independent development, and no confusion
			over build numbers.
		</para>
		<para>
			Of course, you're free to ignore these common layouts.  You
			can create any sort of variation, whatever works best for you or
			your team.  Remember that whatever you choose, it's not a
			permanent commitment.  You can reorganize your repository at any
			time.  Because branches and tags are ordinary directories,
			TortoiseGit can move or rename them however you wish. 
		</para>
		<para>
			Switching from one layout to another is just a matter of 
			issuing a series of server-side moves; If you don't like the 
			way things are organized in the repository, just juggle the 
			directories around.
		</para>
		<para>
			So if you haven't already created a basic folder structure inside
			your repository you should do that now. There are two ways to
			achieve this. If you simply want to create a
			<filename>/trunk /tags /branches</filename> structure, you can use
			the repository browser to create the three folders (in three separate
			commits). If you want to create a deeper hierarchy then it is simpler
			to create a folder structure on disk first and import it in a single
			commit, like this:
			<orderedlist>
				<listitem>
					<para>
						create a new empty folder on your hard drive
					</para>
				</listitem>
				<listitem>
					<para>
						create your desired top-level folder structure inside
						that folder - don't put any files in it yet!
					</para>
				</listitem>
				<listitem>
					<para>
						import this structure into the repository via a 
						<action>right click</action> on the folder and
						selecting
						<menuchoice>
							<guimenu>TortoiseGit</guimenu>
							<guimenuitem>Import...</guimenuitem>
						</menuchoice>
						This will import your temp
						folder into the repository root to create the basic
						repository layout.
					</para>
				</listitem>
			</orderedlist>
		</para>
		<para>
			Note that the name of the folder you are importing does not appear in
			the repository, only its contents. For example, create the following folder
			structure:
<screen>
C:\Temp\New\trunk
C:\Temp\New\branches
C:\Temp\New\tags
</screen>
			Import <filename>C:\Temp\New</filename> into the repository root,
			which will then look like this:
<screen>
/trunk
/branches
/tags
</screen>
		</para>
	</sect2>
</sect1>
