octokit.js provides a minimal higher-level wrapper around git's plumbing commands, exposing an API for manipulating GitHub repositories, users, groups, and gists. It is being developed in the context of github-book, an EPUB3 editor for GitHub.
This package can also be used in nodejs
or as an AMD module in the browser.
- Works in
nodejs
, a AMD module in the browser, a bower library - Simple
read
andwrite
methods for text and binary files - Creating gists, Pull Requests, forks, and new Repositories
ETag
Caching- Promises instead of callbacks (for better error-handling and progress updating)
- Progress Notifications for multistep operations
- Starring and Following repositories, users, and organizations
- Editing Team and Organization Membership
- User/Org/Repo events and notifications
- Listeners for rate limit changes
- Public Keys
- Hooks (commit, comment, etc)
All asynchronous methods return a Common-JS Promise. See jQuery.Deferred or Node's Q for more information.
Create an Octokit instance.
var gh = new Octokit({
username: "YOU_USER",
password: "YOUR_PASSWORD"
});
Or if you prefer OAuth, it looks like this:
var gh = new Octokit({
token: "OAUTH_TOKEN"
});
define(['octokit'], function(Octokit) {
var gh = new Octokit({
username: "YOU_USER",
password: "YOUR_PASSWORD"
});
});
Install instructions:
npm install octokit --save
var Octokit = require('octokit');
var gh = Octokit.new({
username: "YOU_USER",
password: "YOUR_PASSWORD"
});
This file can be included using the bower package manager:
bower install octokit --save
var repo = gh.getRepo(username, reponame);
Show repository information
repo.getInfo()
.done(function(repo) {})
.fail(function(err) {});
List all branches in a Repository
repo.getBranches()
.done(function(branches) {});
Fork a repository
repo.fork()
.done(function() {});
Create a Pull Request
repo.createPullRequest()
.done(function() {});
Get recent commits to the repository
var options = {};
repo.getCommits(options)
.done(function(commits) {});
List Repository events
repo.getEvents()
.done(function(events) {});
List Issue events for the repository
repo.getIssueEvents()
.done(function(events) {});
List events for a network of Repositories
repo.getNetworkEvents()
.done(function(events) {});
List unread notifications for authenticated user pertaining to this repository
var options = {};
repo.getNotifications(options)
.done(function(events) {});
Get programming language counts (CoffeeScript, Ruby, Shell)
repo.getLanguages()
.done(function(events) {});
Additional methods are available for a specific branch in a repository
Get the Default branch of a repository
var branch = repo.getDefaultBranch();
Get a specific branch of a repository
var branch = repo.getBranch("BRANCH_NAME");
Read a file from the branch
var isBinary = false;
branch.read('PATH/TO/FILE.txt', isBinary)
.done(function(contents) {})
.fail(function(err) {});
Remove a file from the branch
var message = "OPTIONAL COMMIT MESSAGE";
branch.remove('PATH/TO/FILE.txt', message)
.done(function() {});
Read the contents (raw) of a file or directory
branch.contents('DIRECTORY/PATH')
.done(function(contents) {});
or
branch.contents('DIRECTORY/PATH/FILE.txt')
.done(function(contents) {});
Move a file
var message = "OPTIONAL COMMIT MESSAGE";
branch.move('PATH/TO/FILE.txt', 'NEW/PATH/TO/FILE.txt', message)
.done(function() {});
Write a file (update or add)
var content = "Contents of the file";
var message = "OPTIONAL COMMIT MESSAGE";
var isBinary = false;
branch.write('PATH/TO/FILE.txt', content, message, isBinary)
.done(function() {});
Write multiple files (update or add) in one commit
var contents = {
"FILE1.txt": "Contents of the file",
"FILE2.txt": {isBase64: true, content: "BASE_64_ENCODED_STRING"}
}
branch.write(contents, message)
.done(function() {});
Get recent commits to a branch
var options = {};
branch.getCommits(options)
.done(function(commits) {});
Create a new branch
branch.createBranch("new-branch-name")
.done(function() {});
The methods on a branch or repo use the following low-level methods.
repo.git.getRef(...) .done(function(result) {});
repo.git.createRef(...) .done(function(result) {});
repo.git.deleteRef(...) .done(function(result) {});
repo.git.getBranches() .done(function(result) {});
repo.git.getBlob(...) .done(function(result) {});
repo.git.getSha(...) .done(function(result) {});
repo.git.getTree(...) .done(function(result) {});
repo.git.postBlob(...) .done(function(result) {});
repo.git.updateTree(...) .done(function(result) {});
repo.git.postTree(...) .done(function(result) {});
repo.git.commit(...) .done(function(result) {});
repo.git.updateHead(...) .done(function(result) {});
repo.git.getCommits(...) .done(function(result) {});
var user = gh.getUser("ANY_GITHUB_USERNAME");
Show user information for a particular user. Also works for organizations.
user.getInfo()
.done(function(user) {})
.fail(function(err) {});
List public repositories for a particular user.
user.getRepos()
.done(function(repos) {});
List organizations the user is in.
user.getOrgs()
.done(function(orgs) {});
List all gists of a particular user.
user.getGists()
.done(function(gists) {});
List users following this user.
user.getFollowers()
.done(function(users) {});
List users this user is following.
user.getFollowing()
.done(function(users) {});
Get Received events for this user.
user.getReceivedEvents()
.done(function(events) {});
Get all events for this user.
user.getEvents()
.done(function(events) {});
The Authenticated User contains the following methods in addition to all the methods in the User API.
Get the authenticated user.
var user = gh.getUser();
List unread notifications for the user.
gh.getNotifications()
.done(function(notifications) {})
.fail(function(err) {});
List private and public repositories of the current authenticated user.
user.getRepos()
.done(function(repos) {});
Follow another user.
var username "SOME_OTHER_USERNAME";
user.follow(username)
.done(function(orgs) {});
Stop following another user.
var username "SOME_OTHER_USERNAME";
user.unfollow(username)
.done(function(orgs) {});
var gist = gh.getGist(3165654);
Read the contents of a Gist.
gist.read()
.done(function(gist) {});
Update the contents of a Gist. Please consult the documentation on GitHub.
var delta = {
"description": "the description for this gist",
"files": {
"file1.txt": {
"content": "updated file contents"
},
"old_name.txt": {
"filename": "new_name.txt",
"content": "modified contents"
},
"new_file.txt": {
"content": "a new file"
},
"delete_this_file.txt": null
}
};
gist.update(delta)
.done(function(gist) {});
Create a Gist
var files = {
'file1.txt': {content: 'String file contents'}
};
gh.getGist().create(files)
.done(function(gist) {});
Delete the Gist
gist.delete()
.done(function(gist) {});
Fork the Gist
gist.fork()
.done(function(gist) {});
Star the Gist
gist.star()
.done(function() {});
Unstar the Gist
gist.unstar()
.done(function() {});
Check if the Gist is starred
gist.isStarred()
.done(function() {});
Retreive a zen message (to test the API works).
gh.getZen()
.done(function(msg) {})
.fail(function(err) {});
Add a listener for rateLimit
changes
function listener(rateLimitRemaining, rateLimit, method, path, data, raw, isBase64) {
// ...
};
gh.onRateLimitChanged(listener);
List repositories for a particular organization. Includes private repositories if you are authorized.
gh.getOrgRepos(orgname)
.done(function(repos) {});
For multistep operations users can listen to updates by registering a listener at promise.progress(function(obj) {})
.
For more details see jQuery's deferred.progress documentation.
##Setup
github-client
has the following dependencies:
- Underscore
- Base64 (for basic auth or binary files). You can leave this if you are not using basic auth or binary files.
If you are not using NodeJS or requireJS include these before github-client
:
<script src="lib/underscore-min.js">
<script src="lib/base64.js">
Switched to a native request
implementation (thanks @mattpass). Adds support for GitHub gists, forks and pull requests.
Adds support for organizations and fixes an encoding issue.
Smart caching of latest commit sha.
Added support for OAuth.
Support for Moving and removing files.
Consider commit messages.
Initial version.