git-data.js

High-level wrapper for GitHub's Git Database API.

Features

• 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

Install

$ npm install git-data

Compatibility

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.

API

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
})

repo.createFile(path, FileType)

Create a file. If the file exists, the existing file will be returned instead.

Params

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.

Example

const readme = await repo.createFile('Readme.md')
const packageJson = await repo.createFile('package.json')
const yamlFile = await repo.createFile('test.yaml', YAMLBlob)

repo.readFile(path, FileType)

Read a file. If the file doesn't exist, an error will be thrown.

Params

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.

Example

const testFile = await repo.readFile('a/b/c/test.txt')
const config = await repo.readFile('.eslintrc', JSONBlob)

Update files

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"
  }
}

repo.deleteFile(path)

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.

Params

Param | Type | Description --- | --- | --- path | String |

Example

await repo.deleteFile('a/b/c/test.txt')
await repo.deleteFile('.eslintrc')

repo.commit(message)

Commit all repo changes. If the repo was updated since you first started making file changes, GitHub will return a 409 conflict error.

Params

Param | Type | Description --- | --- | --- message | String | commit message

Example

try {
  await repo.commit('this is a commit message')
} catch (err) {
  if (err.status === 409) repo.invalidate()
  console.error(err.stack)
}

repo.invalidate()

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()

License

MIT