Add open repo guide

tbranyen · Mar 13, 2015 · Feb 22, 2015 · Feb 23, 2015 · Feb 23, 2015 · Mar 1, 2015
commit c89ab3bce8bbe4d342404b1f8b3aaee212d59cd3
diff --git a/guides/repositories/README.md b/guides/repositories/README.md
@@ -5,4 +5,123 @@ title: Opening a Repository
 description: How to open and free a repository
 ---
 
+**In order to run examples, you will need to [Install NodeGit](../../install/basics)
+first.**
+
 [Return to all guides](../)
+
+* * *
+
+Opening a Repository
+--------------------
+
+This guide explains how to open a repository, and how to work with errors in a
+promise chain
+
+[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");
+```
+
+### Path to Repo
+
+The only argument to the `open` method is a path to the repo on disk. Here we
+are calculating that from our current directory using the `path` object from
+node.
+
+``` javascript
+var pathToRepo = require("path").resolve("../my-git-projects/my-project");
+```
+
+You can also point it directly to a `.git` folder to open as well
+
+``` javascript
+var pathToRepo = require("path").resolve("../my-git-projects/my-project/.git");
+```
+
+This is not necessary though as the function will check the passed directory
+for the `.git` subdirectory
+
+### Open a Repo
+
+Now that we have our path to the repo we wish to open we can do so by calling
+the `open` method on the `NodeGit.Repository` module
+
+``` javascript
+NodeGit.Repository.open(pathToRepo).then(function (repo) {
+  // Inside of this function we have an open repo
+});
+```
+
+*NOTE: We use promises to perform operations in NodeGit. This allows the node event
+loop to keep cycling through while under the hood our wrapped libgit2 code is
+performing the actions we requested and we're not waiting for it.
+
+This allows our apps to remain responsive and performant. However if you're
+not used to promises then this can take some getting used to. If you need
+an introduction you can head over to https://www.promisejs.org/ for some
+tutorials.*
+
+### Handling errors
+
+Promises will swallow errors if there isn't code to explicitly handle them.
+You can do this through any of the following 3 ways.
+
+#### Providing a second function to the `.then` method
+
+You can pass a second function parameter to the `.then` method that will have
+the reason why a promise failed in it's first argument.
+
+``` javascript
+NodeGit.Repository.open(pathToRepo).then(function (sucessfulResult) {
+  // This is the first function of the then which contains the successfully
+  // calculated result of the promise
+}, function (reasonForFailure) {
+  // This is the second function of the then which contains the reason the
+  // promise failed
+});
+```
+
+#### Including a `.catch` in a chain
+
+You can also append a `.catch` to the end of a promise chain which will
+receive any promise failure that isn't previously caught
+
+``` javascript
+NodeGit.Repository.open(pathToRepo).then(function (sucessfulResult) {
+  // This is the first function of the then which contains the successfully
+  // calculated result of the promise
+})
+.catch(function (reasonForFailure) {
+  // failure is handled here
+});
+```
+
+#### Finishing a chain with `done`
+
+If you append a `.done` at the end of your chain, you will have any error that
+wasn't previously handled by the above 2 methods thrown.
+
+``` javascript
+NodeGit.Repository.open(pathToRepo).then(function (sucessfulResult) {
+  // This is the first function of the then which contains the successfully
+  // calculated result of the promise
+})
+.done(function () {
+  // If we have a .done then the error will be thrown if there was an error that
+  // wasn't caught by either providing a 2nd function to the `.then` or a
+  // `.catch` function
+});
+```
diff --git a/guides/repositories/index.js b/guides/repositories/index.js
@@ -0,0 +1,39 @@
+// 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 NodeGit = require("../../../");
+
+// Using the `open` method from the `NodeGit.Repository` module, we can open
+// a repository using NodeGit
+var pathToRepo = require("path").resolve("../my-git-projects/my-project");
+
+// In NodeGit we use Promises to make callbacks easier to deal with.
+//
+// For more information visit https://www.promisejs.org/
+NodeGit.Repository.open(pathToRepo).then(function (repo) {
+  // In this function we have a repo object that we can perform git operations
+  // on.
+  // NOTE: Many NodeGit objects will appear as empty objects if inspected in
+  // the console. This is a known issue. You can track it's progress at
+  // https://github.com/nodegit/nodegit/issues/307
+})
+// Promises will swallow errors and not report them unless you have supplied
+// a second function to the `.then` or end the chain with either a `.catch` or
+// a `.done`
+.then(function (successfulResult) {
+  // This is the first function of the then which contains the successfully
+  // calculated result of the promise
+}, function (reasonForFailure) {
+  // This is the second function of the then which contains the reason the
+  // promise failed
+})
+.catch(function (reasonForFailure) {
+  // You can also provide a catch function which will contain the reason why
+  // any above promises that weren't handled have failed
+})
+.done(function() {
+  // If we have a .done then the error will be thrown if there was an error that
+  // wasn't caught by either providing a 2nd function to the `.then` or a
+  // `.catch` function
+});