Skip to content

Commit e814a4c

Browse files
tbranyentbranyen
committed
Integrating Guides
1 parent 92497a3 commit e814a4c

File tree

11 files changed

+443
-0
lines changed

11 files changed

+443
-0
lines changed

‎generate/index.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
var fs = require('fs');
2+
var path = require('path');
3+
var fse = require('fs-extra');
4+
var glob = require('glob').sync;
15
var generatedData = require('./lib/generated_data');
26
var writeApiDocs = require('./lib/write_api_docs');
37
var addConvenienceMethods = require('./lib/add_convenience_methods.js');
@@ -11,3 +15,15 @@ var fullData;
1115
addConvenienceMethods(baseData).then(function(fullData) {
1216
writeApiDocs(fullData);
1317
});
18+
19+
// Copy convenience methods in.
20+
fse.removeSync('guides');
21+
fse.copySync('generate/nodegit/guides/', 'guides');
22+
23+
glob('guides/**/README.md').forEach(function(file) {
24+
var dir = path.dirname(file);
25+
var filename = path.basename(file);
26+
27+
// Rename README.md => index.md
28+
fs.renameSync(file, dir + "/" + 'index.md');
29+
});

‎guides/cloning/gh-two-factor/index.js‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Require in NodeGit, since we want to use the local copy, we're using a
2+
// relative path. In your project, you will use:
3+
//
4+
// var NodeGit = require('nodegit');
5+
var Git = require('../../../');
6+
7+
// To clone with two factor auth enabled, you have to use a GitHub OAuth token
8+
// over HTTPS.
9+
var GITHUB_TOKEN = '<GH_TOKEN>';
10+
11+
// Using the `clone` method from the `Git.Clone` module, bring down the NodeGit
12+
// test repository from GitHub.
13+
var cloneURL = 'https://github.com/nodegit/private';
14+
15+
// Ensure that the `tmp` directory is local to this file and not the CWD.
16+
var localPath = require('path').join(__dirname, 'tmp');
17+
18+
// Simple object to store clone options.
19+
var cloneOptions = {};
20+
21+
// This is a required callback for OS X machines. There is a known issue
22+
// with libgit2 being able to verify certificates from GitHub.
23+
cloneOptions.remoteCallbacks = {
24+
certificateCheck: function() { return 1; },
25+
credentials: function() {
26+
return Git.Cred.userpassPlaintextNew(GITHUB_TOKEN, 'x-oauth-basic');
27+
}
28+
};
29+
30+
// Invoke the clone operation and store the returned Promise.
31+
var cloneRepository = Git.Clone.clone(cloneURL, localPath, cloneOptions);
32+
33+
// If the repository already exists, the clone above will fail. You can simply
34+
// open the repository in this case to continue execution.
35+
var errorAndAttemptOpen = function() {
36+
return Git.Repository.open(localPath);
37+
};
38+
39+
// Once the repository has been cloned or opened, you can work with a returned
40+
// `Git.Repository` instance.
41+
cloneRepository.catch(errorAndAttemptOpen)
42+
.then(function(repository) {
43+
// Access any repository methods here.
44+
console.log('Is the repository bare? %s', Boolean(repository.isBare()));
45+
})
46+
.catch(function(ex) {
47+
console.log(ex, ex.stack);
48+
});

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

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

‎guides/cloning/http/index.js‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Require in NodeGit, since we want to use the local copy, we're using a
2+
// relative path. In your project, you will use:
3+
//
4+
// var NodeGit = require('nodegit');
5+
var Git = require('../../../');
6+
7+
// Using the `clone` method from the `Git.Clone` module, bring down the NodeGit
8+
// test repository from GitHub.
9+
var cloneURL = 'https://github.com/nodegit/test';
10+
11+
// Ensure that the `tmp` directory is local to this file and not the CWD.
12+
var localPath = require('path').join(__dirname, 'tmp');
13+
14+
// Simple object to store clone options.
15+
var cloneOptions = {};
16+
17+
// This is a required callback for OS X machines. There is a known issue
18+
// with libgit2 being able to verify certificates from GitHub.
19+
cloneOptions.remoteCallbacks = {
20+
certificateCheck: function() { return 1; }
21+
};
22+
23+
// Invoke the clone operation and store the returned Promise.
24+
var cloneRepository = Git.Clone.clone(cloneURL, localPath, cloneOptions);
25+
26+
// If the repository already exists, the clone above will fail. You can simply
27+
// open the repository in this case to continue execution.
28+
var errorAndAttemptOpen = function() {
29+
return Git.Repository.open(localPath);
30+
};
31+
32+
// Once the repository has been cloned or opened, you can work with a returned
33+
// `Git.Repository` instance.
34+
cloneRepository.catch(errorAndAttemptOpen)
35+
.then(function(repository) {
36+
// Access any repository methods here.
37+
console.log('Is the repository bare? %s', Boolean(repository.isBare()));
38+
});

‎guides/cloning/http/index.md‎

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

‎guides/cloning/index.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
layout: default
3+
menu_item: guides
4+
return_to:
5+
"All Guides": ../
6+
title: Cloning Guides
7+
description: How to clone repositories
8+
---
9+
10+
### [HTTP/HTTPS clone](http/)
11+
12+
> Emulates `git clone https://github.com/nodegit/test`
13+
14+
For cloning HTTP or HTTPS repositories from servers like GitHub.
15+
16+
### [SSH w/ Agent](ssh-with-agent/)
17+
18+
> Emulates `git clone git@github.com:nodegit/test`
19+
20+
For cloning SSH repositories using an SSH agent.
21+
22+
### [GitHub Two Factor Auth](gh-two-factor/)
23+
24+
> Emulates `git clone https://gh-token:-oauth-basic@github.com/nodegit/test`
25+
26+
For cloning repositories from GitHub when two-factor authorization is
27+
enabled.

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

Whitespace-only changes.

0 commit comments

Comments
 (0)