Skip to content

Commit 27407be

Browse files
tbranyenJohn Haley
tbranyen
authored and
John Haley
committed
More consistent guides
1 parent b1c1b5b commit 27407be

File tree

5 files changed

+190
-33
lines changed

5 files changed

+190
-33
lines changed

‎guides/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ description: Learning NodeGit
2626

2727
> How to clone repositories
2828
29-
- [HTTP/HTTPS clone](cloning/http/)
29+
- [HTTP/HTTPS](cloning/http/)
3030
- [SSH w/ Agent](cloning/ssh-with-agent/)
3131
- [GitHub Two Factor Auth](cloning/gh-two-factor/)
3232

‎guides/cloning/README.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
---
22
layout: full
33
menu_item: guides
4-
return_to:
5-
"All Guides": ../
64
title: Cloning Guides
75
description: How to clone repositories
86
---
97

10-
### [HTTP/HTTPS clone](http/)
8+
### [HTTP/HTTPS](http/)
119

1210
> Emulates `git clone https://github.com/nodegit/test`
1311

‎guides/cloning/gh-two-factor/README.md‎

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: full
33
menu_item: guides
4-
title: HTTP Clone Guide
4+
title: GitHub Two Factor Auth Guide
55
description: How to clone with GitHub Two Factor Authorization
66
---
77

@@ -10,8 +10,8 @@ first.**
1010

1111
[Return to cloning guides](../)
1212

13-
HTTP/HTTPS clone
14-
----------------
13+
GitHub Two Factor Auth
14+
----------------------
1515

1616
This guide explains how to clone a repository, and in the case of failure,
1717
attempt to open the existing path.
@@ -33,16 +33,35 @@ However, in your project you will most likely be using the following command:
3333
var Git = require("nodegit");
3434
```
3535

36+
### GitHub Personal OAuth Token
37+
38+
Before you can clone a repository, you'll need a GitHub OAuth application
39+
token. You can find more information on generating one here:
40+
41+
[Creating an access token for command-line use](
42+
https://help.github.com/articles/creating-an-access-token-for-command-line-use/
43+
)
44+
45+
Once you have this token you'll assign it to a variable in your project, for
46+
this example, we'll call it `GITHUB_TOKEN`.
47+
48+
``` javascript
49+
var GITHUB_TOKEN = "<GH_TOKEN>";
50+
```
51+
52+
Keep this variable a secret. If you accidentally commit this key to a public
53+
GitHub repository they will immediately revoke it.
54+
3655
### Clone URL
3756

3857
The first argument to the `clone` method is a URL.
3958

40-
In this example we're going to clone one of our test repositories from GitHub.
41-
You could easily substitute this with any valid http or https Git repository
42-
URL.
59+
In this example we're going to clone one of our private test repositories from
60+
GitHub. You could easily substitute this with any valid http or https Git
61+
repository URL.
4362

4463
``` javascript
45-
var cloneURL = "https://github.com/nodegit/test";
64+
var cloneURL = "https://github.com/nodegit/private";
4665
```
4766

4867
### Clone path
@@ -84,22 +103,38 @@ cloneOptions.remoteCallbacks = {
84103
};
85104
```
86105

87-
### Invoking the clone method
106+
#### GitHub credentials for Two Factor Auth
88107

89-
The way NodeGit is structured is that all [libgit2](http://libgit2.org) C
90-
methods are dynamically generated into C++. Since we're taking a
91-
class-oriented approach, we make a top level class named `Clone`. This class
92-
has a static method `clone` that we can use to bring down a repository.
108+
In order to authorize the clone operation, we'll need to respond to a low-level
109+
callback that expects credentials to be passed.
110+
111+
This function will be attached below, the above `certificateCheck` and will
112+
respond back with the OAuth token.
113+
114+
The `remoteCallbacks` object now looks like this:
115+
116+
``` javascript
117+
cloneOptions.remoteCallbacks = {
118+
certificateCheck: function() { return 1; },
119+
credentials: function() {
120+
return Git.Cred.userpassPlaintextNew(GITHUB_TOKEN, "x-oauth-basic");
121+
}
122+
};
123+
```
124+
125+
### Invoking the clone method
93126

94-
While it may look a bit verbose, it is symptomatic of a rigid convention.
127+
You can easily invoke our top-level Clone as a function passing along the three
128+
aforementioned arguments.
95129

96130
``` javascript
97131
var cloneRepository = Git.Clone(cloneURL, localPath, cloneOptions);
98132
```
99133

100-
Notice how we store the return value from `Clone.clone`. This is a [Promise]()
101-
to represent the asynchronous operation. It offers finer control flow by
102-
allowing us to capture errors and fallback if there is a clone failure.
134+
Notice how we store the return value from `Git.Clone`. This is a
135+
[Promise](https://www.promisejs.org/) to represent the asynchronous operation.
136+
It offers finer control flow by allowing us to capture errors and fallback if
137+
there is a clone failure.
103138

104139
### Handling clone failure
105140

‎guides/cloning/http/README.md‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
---
22
layout: full
33
menu_item: guides
4-
title: HTTP Clone Guide
5-
description: How to clone with HTTP
4+
title: HTTP/HTTPS Guide
5+
description: How to clone with HTTP/HTTPS
66
---
77

88
**In order to run examples, you will need to [Install NodeGit](../../install)
99
first.**
1010

1111
[Return to cloning guides](../)
1212

13-
HTTP/HTTPS clone
14-
----------------
13+
HTTP/HTTPS
14+
----------
1515

1616
This guide explains how to clone a repository, and in the case of failure,
1717
attempt to open the existing path.
@@ -86,20 +86,17 @@ cloneOptions.remoteCallbacks = {
8686

8787
### Invoking the clone method
8888

89-
The way NodeGit is structured is that all [libgit2](http://libgit2.org) C
90-
methods are dynamically generated into C++. Since we're taking a
91-
class-oriented approach, we make a top level class named `Clone`. This class
92-
has a static method `clone` that we can use to bring down a repository.
93-
94-
While it may look a bit verbose, it is symptomatic of a rigid convention.
89+
You can easily invoke our top-level Clone as a function passing along the three
90+
aforementioned arguments.
9591

9692
``` javascript
9793
var cloneRepository = Git.Clone(cloneURL, localPath, cloneOptions);
9894
```
9995

100-
Notice how we store the return value from `Clone.clone`. This is a [Promise]()
101-
to represent the asynchronous operation. It offers finer control flow by
102-
allowing us to capture errors and fallback if there is a clone failure.
96+
Notice how we store the return value from `Git.Clone`. This is a
97+
[Promise](https://www.promisejs.org/) to represent the asynchronous operation.
98+
It offers finer control flow by allowing us to capture errors and fallback if
99+
there is a clone failure.
103100

104101
### Handling clone failure
105102

‎guides/cloning/ssh-with-agent/README.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
layout: full
3+
menu_item: guides
4+
title: SSH w/ Agent Guide
5+
description: How to clone SSH with an agent
6+
---
7+
8+
**In order to run examples, you will need to [Install NodeGit](../../install)
9+
first.**
10+
11+
[Return to cloning guides](../)
12+
13+
SSH clone
14+
----------------
15+
16+
This guide explains how to clone a repository, and in the case of failure,
17+
attempt to open the existing path.
18+
19+
[View example source](index.js)
20+
21+
### Requiring NodeGit
22+
23+
In the guides directory, we like to keep our NodeGit relative to the project
24+
root.
25+
26+
``` javascript
27+
var Git = require("../../../");
28+
```
29+
30+
However, in your project you will most likely be using the following command:
31+
32+
``` javascript
33+
var Git = require("nodegit");
34+
```
35+
36+
### Clone URL
37+
38+
The first argument to the `clone` method is a URL.
39+
40+
In this example we're going to clone one of our test repositories from GitHub.
41+
You could easily substitute this with any valid http or https Git repository
42+
URL.
43+
44+
``` javascript
45+
var cloneURL = "https://github.com/nodegit/test";
46+
```
47+
48+
### Clone path
49+
50+
The second argument to the `clone` method is a path.
51+
52+
Ideally your application will clone a repository into the same folder path
53+
regardless of how or where you execute it from. Paths are relative to the
54+
current working directory in NodeGit, so you will need to normalize it first.
55+
56+
This is very simple in Node:
57+
58+
``` javascript
59+
var localPath = require("path").join(__dirname, "tmp");
60+
```
61+
62+
Now this `tmp` directory will be created along side your script, no matter how
63+
or where you execute it from.
64+
65+
### Clone options
66+
67+
The third argument to the `clone` method is an optional simple object.
68+
69+
``` javascript
70+
var cloneOptions = {};
71+
```
72+
73+
#### GitHub certificate issue in OS X
74+
75+
Unfortunately in OS X there is a problem where libgit2 is unable to look up
76+
GitHub certificates correctly. In order to bypass this problem, we're going
77+
to passthrough the certificate check.
78+
79+
*Note: this is not a problem with Windows or Linux*
80+
81+
``` javascript
82+
cloneOptions.remoteCallbacks = {
83+
certificateCheck: function() { return 1; }
84+
};
85+
```
86+
87+
### Invoking the clone method
88+
89+
You can easily invoke our top-level Clone as a function passing along the three
90+
aforementioned arguments.
91+
92+
``` javascript
93+
var cloneRepository = Git.Clone(cloneURL, localPath, cloneOptions);
94+
```
95+
96+
Notice how we store the return value from `Git.Clone`. This is a
97+
[Promise](https://www.promisejs.org/) to represent the asynchronous operation.
98+
It offers finer control flow by allowing us to capture errors and fallback if
99+
there is a clone failure.
100+
101+
### Handling clone failure
102+
103+
A naive way to handle a clone failure is to try opening the same path. Clones
104+
will most commonly fail when the directory already exists. We can define
105+
a function to attempt opening in this case.
106+
107+
``` javascript
108+
var errorAndAttemptOpen = function() {
109+
return Git.Repository.open(local);
110+
};
111+
```
112+
113+
This will be called as part of the Promise resolution in the final step.
114+
115+
### The Promise chain
116+
117+
Lastly in our clone operation, we'll assemble a Promise chain to handle errors
118+
and work with the `Git.Repository` instance result.
119+
120+
``` javascript
121+
cloneRepository.catch(errorAndAttemptOpen)
122+
.then(function(repository) {
123+
// Access any repository methods here.
124+
console.log("Is the repository bare? %s", Boolean(repository.isBare()));
125+
});
126+
```
127+

0 commit comments

Comments
 (0)