[skip-ci]

tbranyen · John Haley · commit fee78185e197 · 2015-03-11T11:49:59.000-07:00
diff --git a/guides/README.md b/guides/README.md
@@ -1,4 +1,9 @@
-# Guides
+---
+layout: default
+menu_item: guides
+title: Guides
+description: Learning NodeGit
+---
 
 ## [Install](install/)
 ## [Cloning](cloning/)
diff --git a/guides/cloning/README.md b/guides/cloning/README.md
@@ -1,5 +1,11 @@
-Cloning
-=======
+---
+layout: default
+menu_item: guides
+return_to:
+  "All Guides": ../
+title: Cloning Guides
+description: How to clone repositories
+---
 
 ### [HTTP/HTTPS clone](http/)
 
diff --git a/guides/cloning/gh-two-factor/README.md b/guides/cloning/gh-two-factor/README.md
@@ -0,0 +1,126 @@
+Cloning
+=======
+
+**In order to run examples, you will need to [Install NodeGit](../../install)
+first.**
+
+[Return to cloning examples](../)
+
+HTTP/HTTPS clone
+----------------
+
+This guide explains how to clone a repository, and in the case of failure,
+attempt to open the existing path.
+
+[View example source](index.js)
+
+### Requiring NodeGit
+
+In the guides directory, we like to keep our NodeGit relative to the project
+root.
+
+``` javascript
+var Git = require('../../../');
+```
+
+However, in your project you will most likely be using the following command:
+
+``` javascript
+var Git = require('nodegit');
+```
+
+### Clone URL
+
+The first argument to the `clone` method is a URL.
+
+In this example we're going to clone one of our test repositories from GitHub.
+You could easily substitute this with any valid http or https Git repository
+URL.
+
+``` javascript
+var cloneURL = 'https://github.com/nodegit/test';
+```
+
+### Clone path
+
+The second argument to the `clone` method is a path.
+
+Ideally your application will clone a repository into the same folder path
+regardless of how or where you execute it from.  Paths are relative to the
+current working directory in NodeGit, so you will need to normalize it first.
+
+This is very simple in Node:
+
+``` javascript
+var localPath = require('path').join(__dirname, 'tmp');
+```
+
+Now this `tmp` directory will be created along side your script, no matter how
+or where you execute it from.
+
+### Clone options
+
+The third argument to the `clone` method is an optional simple object.
+
+``` javascript
+var cloneOptions = {};
+```
+
+#### GitHub certificate issue in OS X
+
+Unfortunately in OS X there is a problem where libgit2 is unable to look up
+GitHub certificates correctly.  In order to bypass this problem, we're going
+to bypass the certificate check.
+
+*Note: this is not a problem with Windows or Linux*
+
+``` javascript
+cloneOptions.remoteCallbacks = {
+  certificateCheck: function() { return 1; }
+};
+```
+
+### Invoking the clone method
+
+The way NodeGit is structured is that all [libgit2](http://libgit2.org) C
+methods are dynamically generated into C++.  Since we're taking a
+class-oriented approach, we make a top level class named `Clone`.  This class
+has a static method `clone` that we can use to bring down a repository.
+
+While it may look a bit verbose, it is symptomatic of a rigid convention.
+
+``` javascript
+var cloneRepository = Git.Clone.clone(cloneURL, localPath, cloneOptions);
+```
+
+Notice how we store the return value from `Clone.clone`.  This is a [Promise]()
+to represent the asynchronous operation.  It offers finer control flow by
+allowing us to capture errors and fallback if there is a clone failure.
+
+### Handling clone failure
+
+A naive way to handle a clone failure is to try opening the same path.  Clones
+will most commonly fail when the directory already exists.  We can define
+a function to attempt opening in this case.
+
+``` javascript
+var errorAndAttemptOpen = function() {
+  return Git.Repository.open(local);
+};
+```
+
+This will be called as part of the Promise resolution in the final step.
+
+### The Promise chain
+
+Lastly in our clone operation, we'll assemble a Promise chain to handle errors
+and work with the `Git.Repository` instance result.
+
+``` javascript
+cloneRepository.catch(errorAndAttemptOpen)
+  .then(function(repository) {
+    // Access any repository methods here.
+    console.log('Is the repository bare? %s', Boolean(repository.isBare()));
+  });
+```
+
diff --git a/guides/cloning/gh-two-factor/index.js b/guides/cloning/gh-two-factor/index.js
@@ -0,0 +1,48 @@
+// Require in NodeGit, since we want to use the local copy, we're using a
+// relative path.  In your project, you will use:
+//
+// var NodeGit = require('nodegit');
+var Git = require('../../../');
+
+// To clone with two factor auth enabled, you have to use a GitHub OAuth token
+// over HTTPS.
+var GITHUB_TOKEN = '<GH_TOKEN>';
+
+// Using the `clone` method from the `Git.Clone` module, bring down the NodeGit
+// test repository from GitHub.
+var cloneURL = 'https://github.com/nodegit/private';
+
+// Ensure that the `tmp` directory is local to this file and not the CWD.
+var localPath = require('path').join(__dirname, 'tmp');
+
+// Simple object to store clone options.
+var cloneOptions = {};
+
+// This is a required callback for OS X machines.  There is a known issue
+// with libgit2 being able to verify certificates from GitHub.
+cloneOptions.remoteCallbacks = {
+  certificateCheck: function() { return 1; },
+  credentials: function() {
+    return Git.Cred.userpassPlaintextNew(GITHUB_TOKEN, 'x-oauth-basic');
+  }
+};
+
+// Invoke the clone operation and store the returned Promise.
+var cloneRepository = Git.Clone.clone(cloneURL, localPath, cloneOptions);
+
+// If the repository already exists, the clone above will fail.  You can simply
+// open the repository in this case to continue execution.
+var errorAndAttemptOpen = function() {
+  return Git.Repository.open(localPath);
+};
+
+// Once the repository has been cloned or opened, you can work with a returned
+// `Git.Repository` instance.
+cloneRepository.catch(errorAndAttemptOpen)
+  .then(function(repository) {
+    // Access any repository methods here.
+    console.log('Is the repository bare? %s', Boolean(repository.isBare()));
+  })
+  .catch(function(ex) {
+    console.log(ex, ex.stack);
+  });
diff --git a/guides/cloning/http/README.md b/guides/cloning/http/README.md
@@ -1,5 +1,12 @@
-Cloning
-=======
+---
+layout: default
+menu_item: guides
+return_to:
+  "Clone": ../
+  "All Guides": ../../
+title: HTTP Clone Guide
+description: How to clone with HTTP
+---
 
 **In order to run examples, you will need to [Install NodeGit](../../install)
 first.**
diff --git a/guides/cloning/http/index.js b/guides/cloning/http/index.js
@@ -21,12 +21,12 @@ cloneOptions.remoteCallbacks = {
 };
 
 // Invoke the clone operation and store the returned Promise.
-var cloneRepo = Git.Clone.clone(cloneURL, localPath, cloneOptions);
+var cloneRepository = Git.Clone.clone(cloneURL, localPath, cloneOptions);
 
 // If the repository already exists, the clone above will fail.  You can simply
 // open the repository in this case to continue execution.
 var errorAndAttemptOpen = function() {
-  return Git.Repository.open(local);
+  return Git.Repository.open(localPath);
 };
 
 // Once the repository has been cloned or opened, you can work with a returned
diff --git a/guides/cloning/ssh-with-agent/README.md b/guides/cloning/ssh-with-agent/README.md
diff --git a/guides/install/README.md b/guides/install/README.md
@@ -1,3 +1,12 @@
+---
+layout: default
+menu_item: guides
+return_to:
+  "All Guides": /guides/
+title: Install Guide
+description: How to install NodeGit
+---
+
 Install
 =======
 
