nodegit · tbranyen · Mar 13, 2015 · Feb 22, 2015 · Feb 23, 2015 · Feb 23, 2015
diff --git a/README.md b/README.md
@@ -63,82 +63,6 @@ npm install nodegit
 If you encounter problems while installing, you should try the Building from
 source instructions below.
 
-## Building from source. ##
-
-If you wish to help contribute to NodeGit it is useful to build locally.
-
-``` bash
-# Fetch this project.
-git clone git://github.com/nodegit/nodegit.git
-
-# Enter the repository.
-cd nodegit
-
-# Install all dependencies, run the code generation scripts, and build.
-npm install
-```
-
-If you encounter errors, you most likely have not configured the dependencies correctly.
-
-### Installing dependencies: ###
-
-#### Mac OS X ####
-
-- [Install XCode Command Line Tools](http://railsapps.github.io/xcode-command-line-tools.html)
-
-#### Linux ####
-
-Using APT in Ubuntu:
-
-``` bash
-sudo apt-get install build-essential
-```
-
-Using Pacman in Arch Linux:
-
-``` bash
-sudo pacman -S base-devel
-```
-
-Note that GCC/G++ 4.7+ are required, as the library makes use of some c++11 std calls.
-
-#### Windows ####
-
-- [Download and install Python](https://www.python.org/download/windows).
-- [Download and install VS Express](http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop).
-
-You may have to add a build flag to the installation process to successfully install.  
-Try first without, if the build fails, try again with the flag.
-
-*Allegedly the order in which you install Visual Studio could trigger this error.*
-
-``` bash
-npm install nodegit --msvs_version=2013
-# Or whatever version you've installed.
-```
-
-##### A note on environment variables in Windows #####
-In many of the npm scripts (and examples above), things are run like
-`BUILD_ONLY=true npm install`. This sets the `BUILD_ONLY` environment variable
-to true for the duration of that command. This doesn't work in windows, however
-there is a solution. You can use cmd to call a command inside of cmd (very meta)
-with the variable set, and it only lasts for the duration of the inner call to cmd.
-So for the above example, you would run `cmd /C "set BUILD_ONLY=true && npm install"`.
-See here for more details:
-[SuperUser](http://superuser.com/questions/223104/setting-environment-variable-for-just-one-command-in-windows-cmd-exe).
-
-### Debug build: ###
-
-In order to track down possible bugs, you will need a debug buid so you
-can get a backtrace with [gdb](http://www.gnu.org/software/gdb/) or
-[lldb](http://lldb.llvm.org/).
-
-If you're building for the first time, run `npm run installDebug` (or `BUILD_ONLY=true npm link`)
-
-Note that you should run `rm -rf build/Release` (or `rd /s /q build/Release` in Windows) to make sure a release build doesn't get loaded instead of the debug build.
-
-If you're doing a subsequent rebuild of NodeGit in debug, the clean function will cause a lot of extraneous recompilation of things you probably didn't change (like the vendor dependencies). If you need to regenerate the C++ files and recompile you can run `npm run rebuildDebug`, or `npm run recompileDebug` if you've manually updated the C++ files and don't want them to regenerate.
-
 ## API examples. ##
 
 ### Cloning a repository and reading a file: ###

diff --git a/guides/README.md b/guides/README.md
@@ -0,0 +1,34 @@
+---
+layout: guides
+menu_item: guides
+title: Guides
+description: Learning NodeGit
+---
+
+## Install
+
+> How to install NodeGit
+
+- [Basics](install/)
+- [From source](install/from-source)
+- [Atom Shell](install/atom-shell/)
+- [NW.js](install/nw.js/)
+
+***
+
+## Repository
+
+> How to work with repositories
+
+- [Opening](repositories/)
+- [Initializing](repositories/initializing)
+
+***
+
+## Cloning
+
+> How to clone repositories
+
+- [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
@@ -0,0 +1,130 @@
+---
+layout: full
+menu_item: guides
+title: HTTP/HTTPS Guide
+description: How to clone with HTTP/HTTPS
+---
+
+**In order to run examples, you will need to [Install NodeGit](../../install/basics)
+first.**
+
+[Return to cloning guides](../)
+
+* * *
+
+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 NodeGit = require("../../../");
+```
+
+However, in your project you will most likely be using the following command:
+
+``` javascript
+var NodeGit = 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 = NodeGit.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 NodeGit.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()));
+  });
+```