Add a recipe for git clone --mirror

It's not necessarily obvious how to perform a mirror, so add a recipe
which tells what git does as well as provide example code of how to
perform the same steps in pygit2.

docs/recipes.rst

@@ -22,5 +22,6 @@ Main porcelain commands
    git-log (Show commit logs.) <recipes/git-log>
    git-show (Show various types of objects.) <recipes/git-show>
    git-tag (Create, list, delete or verify a tag object signed with GPG.) <recipes/git-tag>
+   git clone --mirror (Clone with a mirroring configuration) <recipes/git-clone-mirror>
 
 .. _git man page: https://www.kernel.org/pub/software/scm/git/docs/git.html

docs/recipes/git-clone-mirror.rst

@@ -0,0 +1,25 @@
+**********************************************************************
+git-clone --mirror
+**********************************************************************
+
+git provides an argument to set up the repository as a mirror, which
+involves setting the refspec to one which copies all refs and a mirror
+option for push in the remote.
+
+.. code-block:: bash
+    $> git clone --mirror https://github.com/libgit2/pygit2
+
+.. code-block:: python
+
+    def init_remote(repo, name, url):
+        # Create the remote with a mirroring url
+        remote = repo.remotes.create(name, url, "+refs/*:refs/*")
+        # And set the configuration option to true for the push command
+        mirror_var = "remote.{}.mirror".format(name)
+        repo.config[mirror_var] = True
+        # Return the remote, which pygit2 will use to perform the clone
+        return remote
+    
+    print("Cloning pygit2 as mirror")
+    pygit2.clone_repository("https://github.com/libgit2/pygit2", "pygit2.git", bare=True,
+                            remote=init_remote)