hubfs.js


Github API wrapper to writeFile and readFile

$3

A mixin for Octokat.js that
provides a simple wrapper for writing to and reading from a repo. It
replicates node.js fs.readFile and fs.writeFile. It has a few special
features:

1. Minimize requests

By default it tries to use the Github contents
API to read, write with a
single request and update a file with 3 requests: (a) tries to write; (b)
gets sha for existing file; (c) writes update

2. Read and update large files

The contents API cannot read or update files larger than 1Mb. Hubfs
switches to the git API to read and
update files up to 100Mb

3. Simultaneous writes

Repeatedly writing to the contents API will result in an
error
because of delays updating the HEAD, and making multiple simultaneous
writes will result in the same problem of Fast Forward commits. Hubfs will
automatically queue up requests and switch to using the git API for
multiple parallel writes. It will batch together multiple writes to the
same repo in commits of up to 10 files, but will make commits as quickly as
it can.

Limitations

- Repeat writes do not currently respect options.flags='wx' (they will
overwrite existing files)

- Maximum batch size for commits cannot be changed, awaiting upstream
async issue

$3

No longer operates as a Octokat mixin, instead new instances are created
with an options object with the owner, repo and auth, which is passed
to Octokat.

$3

| parameter | type | description |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| options | Object | options.owner Github repo owner, options.repo repo name, options.auth (optional) passed through to a new
Octokat instance |

$3

``js
var Hubfs = require('Hubfs')

var options = {
owner: 'github_username',
repo: 'github_repo_name'
auth: {
username: "USER_NAME",
password: "PASSWORD"
}
}

var gh = Hubfs(options)
`


Returns Object, returns and instance of Hubfs with two methods readFile and writeFile.

$3

Asynchronously writes data to a file on Github, replacing the file if it
already exists. data can be a string or a buffer.

The encoding option is ignored if data is a buffer. It defaults to 'utf8'.

The file path is always interpreted from the root of the repo, whether or
not it is preceded by a slash.

$3

| parameter | type | description |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filename | String | |
| data | String\,Buffer | |
| [options] | Object | _optional:_ options.encoding='utf8' options.flag='w' default will overwrite, 'wx' will fail if path exists. options.message Commit message. options.branch='master' branch to write to. |
| callback | Function | |

$3

`js
gh.writeFile('message.txt', 'Hello Github', function (err) {
if (err) throw err
console.log('It\'s saved!')
})
`

$3

Asynchronously read a file on Github.

The file path is always interpreted from the root of the repo, whether or
not it is preceded by a slash.

The callback is passed two arguments (err, data), where data is the
contents of the file.

If no encoding is specified, then the raw buffer is returned.

$3

| parameter | type | description |
| ----------- | -------- | --------------------------------------------------------------------------------------------------------- |
| filename | String | |
| [options] | Object | _optional:_ options.encoding=null (returns Buffer) options.ref='master' name of the commit/branch/tag |
| callback | Function | |

$3

`js
gh.readFile('/my_folder/my_file.txt', function (err, data) {
if (err) throw err
console.log(data)
})
`

Installation

Requires nodejs.

`sh
$ npm install hubfs.js
`

Tests

`sh
$ npm test
``