# HG changeset patch
# User Karl Goetz <karl@kgoetz.id.au>
# Date 1498679573 -7200
# Node ID c5512c9d2118f92fce5c69cf749c7b7291f9e07c
# Parent  d29266efe5a5958b02301ad40181296f399448f6
docs/vcs_support: add information on importing repositories

This change directly relates to issue #254.

Some rework of the original patch done by Thomas De Schampheleire:
- generalize to cover both Mercurial and Git
- simplify instructions for importing via filesystem: don't impose a certain
  flow as it depends on different factors: are the repos already present on
  the machine, are they organized in a flat hierarchy or already in a more
  complex one, ...
- invalidating cache while rescanning should not be needed when adding new
  repositories

diff -r d29266efe5a5 -r c5512c9d2118 docs/usage/vcs_support.rst
--- a/docs/usage/vcs_support.rst	Wed Jun 28 22:09:16 2017 +0200
+++ b/docs/usage/vcs_support.rst	Wed Jun 28 21:52:53 2017 +0200
@@ -81,6 +81,69 @@
 Next we can edit the subrepository data, and push back to Kallithea. This will
 update both repositories.
 
+.. _importing:
+
+
+Importing existing repositories
+-------------------------------
+
+There are two main methods to import repositories in Kallithea: via the web
+interface or via the filesystem. If you have a large number of repositories to
+import, importing them via the filesystem is more convenient.
+
+Importing via web interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For a small number of repositories, it may be easier to create the target
+repositories through the Kallithea web interface, via *Admin > Repositories* or
+via the *Add Repository* button on the entry page of the web interface.
+
+Repositories can be nested in repository groups by first creating the group (via
+*Admin > Repository Groups* or via the *Add Repository Group* button on the
+entry page of the web interface) and then selecting the appropriate group when
+adding the repository.
+
+After creation of the (empty) repository, push the existing commits to the
+*Clone URL* displayed on the repository summary page. For Git repositories,
+first add the *Clone URL* as remote, then push the commits to that remote.  The
+specific commands to execute are shown under the *Existing repository?* section
+of the new repository's summary page.
+
+A benefit of this method particular for Git repositories, is that the
+Kallithea-specific Git hooks are installed automatically.  For Mercurial, no
+hooks are required anyway.
+
+Importing via the filesystem
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The alternative method of importing repositories consists of creating the
+repositories in the desired hierarchy on the filesystem and letting Kallithea
+scan that location.
+
+All repositories are stored in a central location on the filesystem. This
+location is specified during installation (via ``setup-db``) and can be reviewed
+at *Admin > Settings > VCS > Location of repositories*. Repository groups
+(defined in *Admin > Repository Groups*) are represented by a directory in that
+repository location. Repositories of the repository group are nested under that
+directory.
+
+To import a set of repositories and organize them in a certain repository group
+structure, first place clones in the desired hierarchy at the configured
+repository location.
+These clones should be created without working directory. For Mercurial, this is
+done with ``hg clone -U``, for Git with ``git clone --bare``.
+
+When the repositories are added correctly on the filesystem:
+
+* go to *Admin > Settings > Remap and Rescan* in the Kallithea web interface
+* select the *Install Git hooks* checkbox when importing Git repositories
+* click *Rescan Repositories*
+This step will scan the filesystem and create the appropriate repository groups
+and repositories in Kallithea.
+
+*Note*: Once repository groups have been created this way, manage their access
+permissions through the Kallithea web interface.
+
 
 .. _waitress: http://pypi.python.org/pypi/waitress
 .. _gunicorn: http://pypi.python.org/pypi/gunicorn