README.md 5.22 KB
Newer Older
1 2
NodeGit
-------
3

4
> Node bindings to the [libgit2](http://libgit2.github.com/) project.
5

Tim's avatar
Tim committed
6 7 8 9 10 11
<table>
  <thead>
    <tr>
      <th>Linux</th>
      <th>OS X</th>
      <th>Windows</th>
12
      <th>Coverage</th>
Tim's avatar
Tim committed
13 14 15 16 17 18
      <th>Dependencies</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2" align="center">
19
        <a href="https://travis-ci.org/nodegit/nodegit"><img src="https://api.travis-ci.org/nodegit/nodegit.svg?branch=master"></a>
Tim's avatar
Tim committed
20 21 22 23
      </td>
      <td align="center">
        <a href="https://ci.appveyor.com/project/timbranyen/nodegit"><img src="https://ci.appveyor.com/api/projects/status/e5a5q75l9yfhnfv2?svg=true"></a>
      </td>
24 25 26
      <td align="center">
        <a href="https://coveralls.io/r/nodegit/nodegit"><img src="https://coveralls.io/repos/nodegit/nodegit/badge.svg" alt="Coverage Status"></a>
      </td>
Tim's avatar
Tim committed
27 28 29 30 31 32
      <td align="center">
        <a href="https://david-dm.org/nodegit/nodegit"><img src="https://david-dm.org/nodegit/nodegit.svg"></a>
      </td>
    </tr>
  </tbody>
</table>
33

Tyler Wanek's avatar
Tyler Wanek committed
34 35
**Stable (libgit2#master): 0.20.0**
**Stable (libgit2@v0.26.0): 0.26.0**
Michael Robinson's avatar
Michael Robinson committed
36

37 38
## Have a problem? Come chat with us! ##

39
Visit [slack.libgit2.org](http://slack.libgit2.org/) to sign up, then join us in #nodegit.
Tim's avatar
Tim committed
40

41
## Maintained by ##
42
Tim Branyen [@tbranyen](http://twitter.com/tbranyen),
Tim Branyen's avatar
Tim Branyen committed
43 44
John Haley [@johnhaley81](http://twitter.com/johnhaley81), and
Max Korp [@maxkorp](http://twitter.com/MaximilianoKorp) with help from tons of
45
[awesome contributors](https://github.com/nodegit/nodegit/contributors)!
46

47
### Alumni Maintainers ###
Tim Branyen's avatar
Tim Branyen committed
48
Steve Smith [@orderedlist](https://twitter.com/orderedlist),
49 50
Michael Robinson [@codeofinterest](http://twitter.com/codeofinterest), and
Nick Kallen [@nk](http://twitter.com/nk)
51

52
## API Documentation. ##
Michael Robinson's avatar
Michael Robinson committed
53

54
[http://www.nodegit.org/](http://www.nodegit.org/)
55

56 57 58 59 60 61 62 63 64
## Getting started. ##

NodeGit will work on most systems out-of-the-box without any native
dependencies.

``` bash
npm install nodegit
```

Tim Branyen's avatar
Tim Branyen committed
65 66 67
If you receive errors about libstdc++, which are commonly experienced when
building on Travis-CI, you can fix this by upgrading to the latest
libstdc++-4.9.
68

Tim Branyen's avatar
Tim Branyen committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
In Ubuntu:

``` sh
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install libstdc++-4.9-dev
```

In Travis:

``` yaml
addons:
  apt:
    sources:
      - ubuntu-toolchain-r-test
    packages:
      - libstdc++-4.9-dev
```

88 89 90 91 92 93 94 95 96 97
In CircleCI:

``` yaml
  dependencies:
    pre:
      - sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
      - sudo apt-get update
      - sudo apt-get install -y libstdc++-4.9-dev
```

98 99 100 101 102 103
If you receive errors about *lifecycleScripts* preinstall/install you probably miss *libssl-dev*
In Ubuntu:
```
sudo apt-get install libssl-dev
```

Tim Branyen's avatar
Tim Branyen committed
104 105 106
If you are still encountering problems while installing, you should try the
[Building from source](http://www.nodegit.org/guides/install/from-source/)
instructions.
107

108
## API examples. ##
tim's avatar
tim committed
109

110 111 112
### Cloning a repository and reading a file: ###

``` javascript
Tim Branyen's avatar
Tim Branyen committed
113
var Git = require("nodegit");
114

Tim Branyen's avatar
Tim Branyen committed
115 116
// Clone a given repository into the `./tmp` folder.
Git.Clone("https://github.com/nodegit/nodegit", "./tmp")
117
  // Look up this known commit.
118 119
  .then(function(repo) {
    // Use a known commit sha from this repository.
120
    return repo.getCommit("59b20b8d5c6ff8d09518454d4dd8b7b30f095ab5");
121
  })
122
  // Look up a specific file within that commit.
123 124 125
  .then(function(commit) {
    return commit.getEntry("README.md");
  })
126
  // Get the blob contents from the file.
127
  .then(function(entry) {
Tim's avatar
Tim committed
128 129 130 131 132
    // Patch the blob to contain a reference to the entry.
    return entry.getBlob().then(function(blob) {
      blob.entry = entry;
      return blob;
    });
133
  })
134
  // Display information about the blob.
135
  .then(function(blob) {
Aoyama, Shotaro's avatar
Aoyama, Shotaro committed
136 137
    // Show the path, sha, and filesize in bytes.
    console.log(blob.entry.path() + blob.entry.sha() + blob.rawsize() + "b");
138 139 140 141 142 143

    // Show a spacer.
    console.log(Array(72).join("=") + "\n\n");

    // Show the entire file.
    console.log(String(blob));
Tim's avatar
Tim committed
144 145 146
  })
  .catch(function(err) { console.log(err); });

147 148
```

149
### Emulating git log: ###
150

151
``` javascript
Tim Branyen's avatar
Tim Branyen committed
152
var Git = require("nodegit");
Nick Kallen's avatar
Nick Kallen committed
153

154
// Open the repository directory.
Tim Branyen's avatar
Tim Branyen committed
155
Git.Repository.open("tmp")
156
  // Open the master branch.
157
  .then(function(repo) {
158
    return repo.getMasterCommit();
159
  })
160
  // Display information about commits on master.
161
  .then(function(firstCommitOnMaster) {
162
    // Create a new history event emitter.
163
    var history = firstCommitOnMaster.history();
Nick Kallen's avatar
Nick Kallen committed
164

165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
    // Create a counter to only show up to 9 entries.
    var count = 0;

    // Listen for commit events from the history.
    history.on("commit", function(commit) {
      // Disregard commits past 9.
      if (++count >= 9) {
        return;
      }

      // Show the commit sha.
      console.log("commit " + commit.sha());

      // Store the author object.
      var author = commit.author();

      // Display author information.
182
      console.log("Author:\t" + author.name() + " <" + author.email() + ">");
183 184 185 186 187 188

      // Show the commit date.
      console.log("Date:\t" + commit.date());

      // Give some space and show the message.
      console.log("\n    " + commit.message());
189
    });
Nick Kallen's avatar
Nick Kallen committed
190

191
    // Start emitting events.
Nick Kallen's avatar
Nick Kallen committed
192
    history.start();
Tim Branyen's avatar
Tim Branyen committed
193
  });
Michael Robinson's avatar
Michael Robinson committed
194
```
195

196 197
For more examples, check the `examples/` folder.

198 199 200 201 202 203 204
## Unit tests. ##

You will need to build locally before running the tests.  See above.

``` bash
npm test
```