octop
v1.1.0
Published
A higher-level wrapper around the Github API.
Downloads
26
Readme
Octop
Octop provides a minimal higher-level wrapper around git's plumbing commands, exposing an API for manipulating GitHub repositories on the file level. It is being developed in the context of Prose, a content editor for GitHub.
This repo is now officially maintained by WeFlex.
Note: this is a fork from michael/github, thanks to DevelopmentSeed.
Installation
Either grab octop
from this repo or install via NPM:
npm install octop --save
Usage
Create a Github instance.
var github = new Github({
username: "YOU_USER",
password: "YOUR_PASSWORD",
auth: "basic"
});
Or if you prefer OAuth, it looks like this:
var github = new Github({
token: "OAUTH_TOKEN",
auth: "oauth"
});
You can use either:
- Authorised App Tokens (via client/secret pairs), used for bigger applications, created in web-flows/on the fly
- Personal Access Tokens (simpler to set up), used on command lines, scripts etc, created in GitHub web UI
See these pages for more info:
Enterprise Github instances may be specified using the apiUrl
option:
var github = new Github({
apiUrl: "https://serverName/api/v3",
...
});
Repository API
var repo = github.getRepo(username, reponame);
Show repository information
repo.show(function(err, repo) {});
Delete a repository
repo.deleteRepo(function(err, res) {});
Get contents at a particular path in a particular branch.
repo.contents(branch, "path/to/dir", function(err, contents) {});
Fork repository. This operation runs asynchronously. You may want to poll for repo.contents
until the forked repo is ready.
repo.fork(function(err) {});
Create new branch for repo. You can omit oldBranchName to default to "master".
repo.branch(oldBranchName, newBranchName, function(err) {});
List Pull Requests.
var state = 'open'; //or 'closed', or 'all'
repo.listPulls(state, function(err, pullRequests) {});
Get details of a Pull Request.
var pullRequestID = 123;
repo.getPull(pullRequestID, function(err, pullRequestInfo) {});
Create Pull Request.
var pull = {
title: message,
body: "This pull request has been automatically generated by Prose.io.",
base: "gh-pages",
head: "michael" + ":" + "prose-patch"
};
repo.createPullRequest(pull, function(err, pullRequest) {});
Retrieve all available branches (aka heads) of a repository.
repo.listBranches(function(err, branches) {});
Store contents at a certain path, where files that don't yet exist are created on the fly.
repo.write('master', 'path/to/file', 'YOUR_NEW_CONTENTS', 'YOUR_COMMIT_MESSAGE', function(err) {});
Not only can you can write files, you can of course read them.
repo.read('master', 'path/to/file', function(err, data) {});
Move a file from A to B.
repo.move('master', 'path/to/file', 'path/to/new_file', function(err) {});
Remove a file.
repo.remove('master', 'path/to/file', function(err) {});
Get information about a particular commit.
repo.getCommit('master', sha, function(err, commit) {});
Exploring files of a repository is easy too by accessing the top level tree object.
repo.getTree('master', function(err, tree) {});
If you want to access all blobs and trees recursively, you can specify 2nd argument
repo.getTree('master', true, function(err, tree) {});
Given a filepath, retrieve the reference blob or tree sha.
repo.getSha('master', '/path/to/file', function(err, sha) {});
For a given reference, get the corresponding commit sha.
repo.getRef('heads/master', function(err, sha) {});
Create a new reference.
var refSpec = {
"ref": "refs/heads/my-new-branch-name",
"sha": "827efc6d56897b048c772eb4087f854f46256132"
};
repo.createRef(refSpec, function(err) {});
Delete a reference.
repo.deleteRef('heads/gh-pages', function(err) {});
Get contributors list with additions, deletions, and commit counts.
repo.contributors(function(err, data) {});
User API
var user = github.getUser();
List all repositories of the authenticated user, including private repositories and repositories in which the user is a collaborator and not an owner.
user.repos(function(err, repos) {});
List organizations the autenticated user belongs to.
user.orgs(function(err, orgs) {});
List authenticated user's gists.
user.gists(function(err, gists) {});
List private & public events for the authenticated user.
user.events(function(err, events) {});
List unread notifications for the authenticated user.
user.notifications(function(err, notifications) {});
Show user information for a particular username. Also works for organizations.
user.show(username, function(err, user) {});
List public repositories for a particular user.
user.userRepos(username, function(err, repos) {});
Create a new repo for the authenticated user
user.createRepo({"name": "test"}, function(err, res) {});
Repo description, homepage, private/public can also be set. For a full list of options see the docs here
List repositories for a particular organization. Includes private repositories if you are authorized.
user.orgRepos(orgname, function(err, repos) {});
List all gists of a particular user. If username is ommitted gists of the current authenticated user are returned.
user.userGists(username, function(err, gists) {});
Gist API
var gist = github.getGist(3165654);
Read the contents of a Gist.
gist.read(function(err, gist) {
});
Updating 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, function(err, gist) {
});
Issues API
var issues = github.getIssues(username, reponame);
To read all the issues of a given repository
issues.list(options, function(err, issues) {});
##Setup
Github.js has the following dependency:
- btoa (included in modern browsers, an npm module is included in package.json for node)