High-level wrapper for GitHub's Git Database API.
- Promise based
- usable in browsers
- filesystem style API
- no one-file-change-per-commit limitation
- commit once for arbitrarily many file changes
- build GitHub-backed apps like Cloud9 and GitBook
$ npm install git-data
git-data.js requires a Promise implementation. If you are targeting older browsers, you should make a Promise polyfill available globally. See here for details.
git-data.js exposes a GitHub object that wraps the Git Data API, as well as a Repo object that provides the high-level filesystem API. To use the library, you will need a GitHub access token. For testing purposes, you can generate a personal access token here.
const GitHub = require('git-data')
const g = new GitHub({
token: 'your access token here'
})
const repo = g.repo({
owner: 'nucleartide', // required
repo: 'git-data.js', // required
branch: 'master', // required
commitPrefix: '[fix]' // optional, prepended to every commit message
})
Create a file. If the file exists, the existing file will be returned instead.
Param | Type | Description |
---|---|---|
path |
String | |
FileType |
Class | Optional. Pass in a class that extends Blob to override file type detection. See JSONBlob for an example. |
const readme = await repo.createFile('Readme.md')
const packageJson = await repo.createFile('package.json')
const yamlFile = await repo.createFile('test.yaml', YAMLBlob)
Read a file. If the file doesn't exist, an error will be thrown.
Param | Type | Description |
---|---|---|
path |
String | |
FileType |
Class | Optional. Pass in a class that extends Blob to override file type detection. See JSONBlob for an example. |
const testFile = await repo.readFile('a/b/c/test.txt')
const config = await repo.readFile('.eslintrc', JSONBlob)
This depends on the blob type. For the built-in Blob types, you may only set strings on Blobs, and you can set any JSON on JSONBlobs.
readme.content = 'this is a readme'
packageJson.content = {
"dependencies": {
"git-data": "0.1.0"
}
}
Delete a file. Deleted files may not be updated. If the file doesn't exist, an error will be thrown.
Note that you may only delete files (Git blobs), not directories.
Param | Type | Description |
---|---|---|
path |
String |
await repo.deleteFile('a/b/c/test.txt')
await repo.deleteFile('.eslintrc')
Commit all repo changes. If the repo was updated since you first started making file changes, GitHub will return a 409 conflict error.
Param | Type | Description |
---|---|---|
message |
String | commit message |
try {
await repo.commit('this is a commit message')
} catch (err) {
if (err.status === 409) repo.invalidate()
console.error(err.stack)
}
Invalidate all file changes and clear the repo's cached tree and commit SHA. Use this in the case of commit conflicts.
Note that all Blobs returned by the repo may no longer be updated.
repo.invalidate()
MIT