Skip to content

Commit a434143

Browse files
tbranyentbranyen
committed
Updated readme
1 parent 7e7872c commit a434143

2 files changed

Lines changed: 103 additions & 51 deletions

File tree

‎README.md‎

Lines changed: 103 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Node.js libgit2 bindings
33

44
Created by Tim Branyen [@tbranyen](http://twitter.com/tbranyen)
55

6-
Currently under active development, `nodegit` provides asynchronous native bindings to the `libgit2` C API.
6+
Currently under active development (and seeking contributors), `nodegit` provides asynchronous native bindings to the `libgit2` C API.
77

88
Building and installing
99
-----------------------
@@ -19,13 +19,22 @@ This will install and configure everything you need to use `nodegit`.
1919
### Mac OS X/Linux/Unix ###
2020

2121
#### Install `nodegit` by cloning source from __GitHub__ and running the `configure`, `make`, and `make install` commands: ####
22-
\*Note: `nodegit` assumes your library path exists at `~/.node_libraries`.\*
22+
\*Note: `nodegit` assumes your library path exists at `~/.node_libraries` you can change this by specifying a new path\*
2323

2424
$ git clone git://github.com/tbranyen/nodegit.git
2525
$ cd nodegit
26+
2627
$ ./configure
2728
$ make
2829
$ make install
30+
31+
$ make install NODE_LIB_PATH=/path/to/your/libraries
32+
33+
\*Updating to a new version\*
34+
35+
$ make update
36+
37+
$ make update NODE_LIB_PATH=/path/to/your/libraries
2938

3039
### Windows via Cygwin ###
3140

@@ -37,81 +46,123 @@ Instructions on compiling `Node.js` on a Windows platform can be found here:
3746
API Example Usage
3847
-----------------
3948

40-
### Convenience API ###
41-
__ Reading a repository and commit data: __
49+
### git log emulation ###
50+
51+
#### Convenience API ####
4252

4353
var git = require( 'nodegit' );
4454

45-
// Read the current repository
55+
// Read a repository
4656
git.repo( '.git', function( err, repo ) {
47-
// If success err will be 0, else throw an error message.
57+
// Success is always 0, failure is always an error string
4858
if( err ) { throw err; }
4959

50-
// Work within the master branch
60+
// Use the master branch
5161
repo.branch( 'master', function( err, branch ) {
52-
// If success err will be 0, else throw an error message.
5362
if( err ) { throw err; }
5463

5564
// Iterate over the revision history
5665
branch.history.each( function( i, commit ) {
57-
// Emulator git log
58-
console.log( 'Author:', commit.author().name, '<' + commit.author().email + '>' );
59-
console.log( 'Date:', commit.time().toDateString() );
60-
console.log( commit.message() );
66+
67+
// Print out `git log` emulation
68+
console.log( commit.author.name + '<' + commit.author.email + '>' );
69+
console.log( commit.time );
70+
console.log( '\n' );
71+
console.log( commit.message );
72+
console.log( '\n' );
6173
});
6274
});
6375

64-
// Read a commit with a SHA1
65-
this.commit( '5f2aa9407f7b3aeb531c621c3358953841ccfc98', function( err, commit ) {
66-
// If success err will be 0, else throw an error message.
67-
if( err ) { throw err; }
68-
69-
console.log( 'Message', commit.message );
70-
console.log( 'Author name', commit.author().name );
71-
console.log( 'Author email', commit.author().email );
72-
73-
// Memory cleanup is *not* required, but would be nice if you remembered :)
74-
repo.free();
75-
});
76+
// Memory cleanup
77+
repo.free();
7678
});
7779

78-
### Raw API ###
79-
__ Accomplishing the same thing as above: __
80+
#### Raw API ####
8081

8182
var git = require( 'nodegit' ).raw;
8283

8384
// Create instance of Repo constructor
8485
var repo = new git.Repo();
85-
// Read the current repository
86-
repo.open( '.git', function( err ) {
87-
// If success will return 0, if an error message throw it as an error string.
88-
if( err ) { throw err };
89-
90-
// Create object id and set hash
91-
var oid = new git.Oid();
92-
oid.mkstr( '5f2aa9407f7b3aeb531c621c3358953841ccfc98' );
93-
94-
// Create commit object
95-
var commit = new git.Commit();
96-
97-
// Lookup commit
98-
commit.lookup( repo, oid, function( err, commit ) {
99-
// If success err will be 0, else throw an error message.
100-
if( err ) { throw err; }
101-
102-
console.log( 'Message', commit.message );
103-
console.log( 'Author name', commit.author().name );
104-
console.log( 'Author email', commit.author().email );
10586

106-
// Memory cleanup is *not* required, but would be nice if you remembered :)
107-
repo.free();
87+
// Read a repository
88+
repo.open( '.git', function( err ) {
89+
// Err is an integer, success is 0, use strError for string representation
90+
if( err ) {
91+
var error = new git.Error();
92+
throw error.strError( err );
93+
}
94+
95+
// Create instance of Ref constructor with this repository
96+
var ref = new git.Ref( repo );
97+
98+
// Find the master branch
99+
repo.lookupRef( ref, '/refs/heads/master', function( err ) {
100+
if( err ) {
101+
var error = new git.Error();
102+
throw error.strError( err );
103+
}
104+
105+
// Create instance of Commit constructor with this repository
106+
var commit = new git.Commit( repo ),
107+
// Create instance of Oid constructor
108+
oid = new git.Oid();
109+
110+
// Set the oid constructor internal reference to this branch reference
111+
ref.oid( oid );
112+
113+
// Lookup the commit for this oid
114+
commit.lookup( oid, function() {
115+
if( err ) {
116+
var error = new git.Error();
117+
throw error.strError( err );
118+
}
119+
120+
// Create instance of RevWalk constructor with this repository
121+
var revwalk = new git.RevWalk( repo );
122+
123+
// Push the commit as the start to walk
124+
revwalk.push( commit );
125+
126+
// Recursive walk
127+
function walk() {
128+
// Each revision walk iteration yields a commit
129+
var revisionCommit = new git.Commit( repo );
130+
131+
revwalk.next( revisionCommit, function( err ) {
132+
// Finish recursion once no more revision items are left
133+
if( err ) { return; }
134+
135+
// Create instance of Sig for author
136+
var author = new git.Sig();
137+
138+
// Set the author to the commit author
139+
revisionCommit.author( author );
140+
141+
// Convert timestamp to milliseconds and set new Date object
142+
var time = new Date( revisionCommit.time() * 1000 );
143+
144+
// Print out `git log` emulation
145+
console.log( author.name + '<' + author.email + '>' );
146+
console.log( time );
147+
console.log( '\n' );
148+
console.log( revisionCommit.message() );
149+
console.log( '\n' );
150+
151+
// Recurse!
152+
walk();
153+
});
154+
}
155+
156+
// Initiate recursion
157+
walk():
158+
});
108159
});
109160
});
110161

111162
Running tests
112163
-------------
113164

114-
__ `nodegit` library code is written adhering to a modified `JSHint`. Run these tests with `make lint`. __
165+
__ `nodegit` library code is written adhering to a modified `JSHint`. Run these checks with `make lint` in the project root. __
115166

116167
__ To run unit tests ensure the submodules `nodeunit` and `rimraf` are located in the `vendor/` subdirectory. __
117168

@@ -141,7 +192,7 @@ __ Can keep track of current method coverage at: [http://bit.ly/tb_methods](http
141192
### v0.0.2: ###
142193
* More methods implemented
143194
* More unit tests
144-
* GitHub landing page
195+
* GitHub landing page (already done)
145196
* More API development
146197

147198
### v0.0.3: ###
@@ -152,3 +203,5 @@ Getting involved
152203
----------------
153204

154205
If you find this project of interest, please document all issues and fork if you feel you can provide a patch. Testing is of huge importance; by simply running the unit tests on your system and reporting issues you can contribute!
206+
207+
__ Before submitting a pull request, please ensure both unit tests and lint checks pass. __

‎src/reference.h‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@ class Reference : public EventEmitter {
2121
static Persistent<FunctionTemplate> constructor_template;
2222
static void Initialize(Handle<v8::Object> target);
2323
git_reference* GetValue();
24-
// Synchronous
2524
int New(git_repository* repo);
2625
void SetValue(git_reference* ref);
2726
const git_oid* _Oid();

0 commit comments

Comments
 (0)