nodegit · tbranyen · Mar 6, 2015 · Mar 6, 2015
diff --git a/guides/README.md b/guides/README.md
@@ -1,30 +1,34 @@
 ---
-layout: default
+layout: guides
 menu_item: guides
 title: Guides
 description: Learning NodeGit
 ---
 
-## [Install](install/)
+## Install
 
 > How to install NodeGit
 
-- [Basics](install/basics/)
+- [Basics](install/)
 - [From source](install/from-source)
 - [Atom Shell](install/atom-shell/)
 - [NW.js](install/nw.js/)
 
-## [Repository](repositories/)
+***
+
+## Repository
 
 > How to work with repositories
 
+- [Opening](repositories/)
 - [Initializing](repositories/initializing)
-- [Opening](repositories/opening)
 
-## [Cloning](cloning/)
+***
+
+## Cloning
 
 > How to clone repositories
 
-- [HTTP/HTTPS](cloning/http/)
+- [HTTP/HTTPS](cloning/)
 - [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,29 +1,130 @@
 ---
 layout: full
 menu_item: guides
-title: Cloning Guides
-description: How to clone repositories
+title: HTTP/HTTPS Guide
+description: How to clone with HTTP/HTTPS
 ---
 
-[Return to all guides](../)
+**In order to run examples, you will need to [Install NodeGit](../../install/basics)
+first.**
+
+[Return to cloning guides](../)
 
 * * *
 
-### [HTTP/HTTPS](http/)
+HTTP/HTTPS
+----------
+
+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 = {};
+```
+
+**If you are using HTTP the OS X issue below does not affect you.**
+
+#### 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);
+```
 
-  > Emulates `git clone https://github.com/nodegit/test`
+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.
 
-  For cloning HTTP or HTTPS repositories from servers like GitHub.
+### Handling clone failure
 
-### [SSH w/ Agent](ssh-with-agent/)
+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.
 
-  > Emulates `git clone git@github.com:nodegit/test`
+``` javascript
+var errorAndAttemptOpen = function() {
+  return Git.Repository.open(local);
+};
+```
 
-  For cloning SSH repositories using an SSH agent.
+This will be called as part of the Promise resolution in the final step.
 
-### [GitHub Two Factor Auth](gh-two-factor/)
+### The Promise chain
 
-  > Emulates `git clone https://gh-token:-oauth-basic@github.com/nodegit/test`
+Lastly in our clone operation, we'll assemble a Promise chain to handle errors
+and work with the `Git.Repository` instance result.
 
-  For cloning repositories from GitHub when two-factor authorization is
-  enabled.
+``` 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/http/README.md b/guides/cloning/http/README.md
diff --git a/guides/cloning/http/index.js → guides/cloning/index.js b/guides/cloning/http/index.js → guides/cloning/index.js
diff --git a/guides/install/README.md b/guides/install/README.md
@@ -1,26 +1,43 @@
 ---
 layout: full
 menu_item: guides
-title: Install Guides
+title: Install Basics
 description: How to install NodeGit
 ---
 
-[Return to all guides](../)
+[Return to install guides](../)
 
 * * *
 
-### [Basics](basics/)
+<a name="with-npm"></a>From NPM
+-------------------------------
 
-  Learn how to install NodeGit
+To install from the NPM repository you can issue the following command:
 
-### [From source](from-source/)
+``` bash
+npm install nodegit
+```
 
-  Learn how to build NodeGit from source
+<a name="from-github"></a>From GitHub
+-------------------------------------
 
-### [Atom Shell](atom-shell/)
+This is required to contribute or run the examples.
 
-  Learn how to use NodeGit with Atom Shell
+Start by cloning the repository, chances are you will only need the latest
+commit, so you can pass the `--depth` flag to make a shallow clone:
 
-### [Nw.js](nw.js/)
+``` bash
+git clone --depth=1 https://github.com/nodegit/nodegit
+```
 
-  Learn how to use NodeGit with NW.js
+Change your directory into the newly created nodegit folder.
+
+``` bash
+cd nodegit
+```
+
+Now you can issue the local installation command:
+
+``` bash
+npm install
+```