Improved documentation

sphinx/git.rst

@@ -5,46 +5,57 @@ Introduction
 ------------
 
 Moa integrates with `Git <http://git-scm.com/>`_ repositories to
-easily add templates from any git repository. This currently only
-works when having the moaGit plugin enabled and with having your moa
-workflow under git version control. Upon installing a git based
-template, moa merges the template repository with the workflow's
-repository using the git subtree merge strategy. In short, the
-template repository is added as a remote to the workflow's repository
-and subsequently merged with the workflow. This strategy has a number
-of nice properties:
-
-- The template is properly integrated in the local workflow and can be
-  copied around and changed (as one normally would do within a git
+easily add templates from any git repository. This requires that you
+have the moaGit plugin enabled and that your Moa workflow is under Git
+version control. Upon installing a Git based template, moa merges the
+template repository with the workflow's repository using the `git
+subtree <https://github.com/apenwarr/git-subtree>`_. This approach has
+a a number of nice properties:
+
+- The template is integrated in the local workflow and can be copied
+  around and changed (as one normally would do within a git
   repository).
 - The template code does not change unless requested. Even when
   duplicating your repository - the template remains unchanged.
 - If required, it is possible to update to the latest version of the
   remote template repository (using a regular `moa refresh`)
+- It possible to upload the template changes upstream.
 
-As a note - the git submodule approach was another candidate for
-implenting this, but copying submodules around is much more
-cumbersome.
+Note - the git submodule approach was another candidate for implenting
+this, but submodules are difficult to be copied once they are checked
+out. Additionally, the `git subtree
+<https://github.com/apenwarr/git-subtree>`_ approach has as an
+advantage above the `git subtree merge strategy
+<https://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html>`_
+that it is easier to upload changes upstream. A downside is that an
+extra prerequisite is added.
 
 Installation
 ------------
 
-To set up moa to work with git template you meed to define a template
-provider in the configuration (for example in
-`~/.config/moa/config`). For example::
+Install `git subtree`
+=====================
+
+See: https://github.com/apenwarr/git-subtree for installation instructions
+
+Define a template provider
+==========================
+
+To set up moa to work with git template you need to define a template
+provider, for example::
 
-    template:
-      providers:
-        mfg:
-          enabled: false
-          class: gitmodule
-          base: 'https://github.com/mfiers/moa_template_'
+	moa set -s template.providers.gtp.class=gitmodule
+	moa set -s template.providers.gtp.base='https://github.com/mfiers/moa_template_'
+    moa set -s template.providers.gtp.enabled=true
 
+This defines a provider (called gtp) that pulls templates from github
+(but any other git server can be used). Note that it is probably
+advisable to set `*.enabled=true` as last - to prevent an incomplete
+import.
 
-This defines a provider (called mfg) that pulls templates from
-github. After doing this you can run::
+After doing this you can run::
 
-    moa new mfg:bowtie
+    moa new gtp:bowtie
 
 which would expect and merge a repository in the following location: