More consistent guides

27407bec2dfda197010127fc442f2e295c3d1ae3
commit 27407bec2dfda197010127fc442f2e295c3d1ae3
diff --git a/guides/README.md b/guides/README.md
@@ -26,7 +26,7 @@ description: Learning NodeGit
 
 > How to clone repositories
 
-- [HTTP/HTTPS clone](cloning/http/)
+- [HTTP/HTTPS](cloning/http/)
 - [SSH w/ Agent](cloning/ssh-with-agent/)
 - [GitHub Two Factor Auth](cloning/gh-two-factor/)
 

diff --git a/guides/cloning/README.md b/guides/cloning/README.md
@@ -1,13 +1,11 @@
 ---
 layout: full
 menu_item: guides
-return_to:
-  "All Guides": ../
 title: Cloning Guides
 description: How to clone repositories
 ---
 
-### [HTTP/HTTPS clone](http/)
+### [HTTP/HTTPS](http/)
 
   > Emulates `git clone https://github.com/nodegit/test`
 

diff --git a/guides/cloning/gh-two-factor/README.md b/guides/cloning/gh-two-factor/README.md
@@ -1,7 +1,7 @@
 ---
 layout: full
 menu_item: guides
-title: HTTP Clone Guide
+title: GitHub Two Factor Auth Guide
 description: How to clone with GitHub Two Factor Authorization
 ---
 
@@ -10,8 +10,8 @@ first.**
 
 [Return to cloning guides](../)
 
-HTTP/HTTPS clone
-----------------
+GitHub Two Factor Auth
+----------------------
 
 This guide explains how to clone a repository, and in the case of failure,
 attempt to open the existing path.
@@ -33,16 +33,35 @@ However, in your project you will most likely be using the following command:
 var Git = require("nodegit");
 ```
 
+### GitHub Personal OAuth Token
+
+Before you can clone a repository, you'll need a GitHub OAuth application
+token.  You can find more information on generating one here:
+
+[Creating an access token for command-line use](
+https://help.github.com/articles/creating-an-access-token-for-command-line-use/
+)
+
+Once you have this token you'll assign it to a variable in your project, for
+this example, we'll call it `GITHUB_TOKEN`.
+
+``` javascript
+var GITHUB_TOKEN = "<GH_TOKEN>";
+```
+
+Keep this variable a secret.  If you accidentally commit this key to a public
+GitHub repository they will immediately revoke it.
+
 ### 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.
+In this example we're going to clone one of our private 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";
+var cloneURL = "https://github.com/nodegit/private";
 ```
 
 ### Clone path
@@ -84,22 +103,38 @@ cloneOptions.remoteCallbacks = {
 };
 ```
 
-### Invoking the clone method
+#### GitHub credentials for Two Factor Auth
 
-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.
+In order to authorize the clone operation, we'll need to respond to a low-level
+callback that expects credentials to be passed.
+
+This function will be attached below, the above `certificateCheck` and will
+respond back with the OAuth token.
+
+The `remoteCallbacks` object now looks like this:
+
+``` javascript
+cloneOptions.remoteCallbacks = {
+  certificateCheck: function() { return 1; },
+  credentials: function() {
+    return Git.Cred.userpassPlaintextNew(GITHUB_TOKEN, "x-oauth-basic");
+  }
+};
+```
+
+### Invoking the clone method
 
-While it may look a bit verbose, it is symptomatic of a rigid convention.
+You can easily invoke our top-level Clone as a function passing along the three
+aforementioned arguments.
 
 ``` javascript
 var cloneRepository = Git.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.
+Notice how we store the return value from `Git.Clone`.  This is a
+[Promise](https://www.promisejs.org/) 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
 

diff --git a/guides/cloning/http/README.md b/guides/cloning/http/README.md
@@ -1,17 +1,17 @@
 ---
 layout: full
 menu_item: guides
-title: HTTP Clone Guide
-description: How to clone with HTTP
+title: HTTP/HTTPS Guide
+description: How to clone with HTTP/HTTPS
 ---
 
 **In order to run examples, you will need to [Install NodeGit](../../install)
 first.**
 
 [Return to cloning guides](../)
 
-HTTP/HTTPS clone
-----------------
+HTTP/HTTPS
+----------
 
 This guide explains how to clone a repository, and in the case of failure,
 attempt to open the existing path.
@@ -86,20 +86,17 @@ cloneOptions.remoteCallbacks = {
 
 ### 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.
+You can easily invoke our top-level Clone as a function passing along the three
+aforementioned arguments.
 
 ``` javascript
 var cloneRepository = Git.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.
+Notice how we store the return value from `Git.Clone`.  This is a
+[Promise](https://www.promisejs.org/) 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
 

diff --git a/guides/cloning/ssh-with-agent/README.md b/guides/cloning/ssh-with-agent/README.md
@@ -0,0 +1,127 @@
+---
+layout: full
+menu_item: guides
+title: SSH w/ Agent Guide
+description: How to clone SSH with an agent
+---
+
+**In order to run examples, you will need to [Install NodeGit](../../install)
+first.**
+
+[Return to cloning guides](../)
+
+SSH 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 passthrough the certificate check.
+
+*Note: this is not a problem with Windows or Linux*
+
+``` javascript
+cloneOptions.remoteCallbacks = {
+  certificateCheck: function() { return 1; }
+};
+```
+
+### Invoking the clone method
+
+You can easily invoke our top-level Clone as a function passing along the three
+aforementioned arguments.
+
+``` javascript
+var cloneRepository = Git.Clone(cloneURL, localPath, cloneOptions);
+```
+
+Notice how we store the return value from `Git.Clone`.  This is a
+[Promise](https://www.promisejs.org/) 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()));
+  });
+```
+