GitHubclass

Synopsis

Interface to GitHub.

This class uses the GitHub v3 API, documented here: http://developer.github.com/v3/.

Constructor: GitHub

Synopsis

var gh = new GitHub(username, password);

Create a new GitHub connection.

Details

Once connected, you may access the methods and member variables of the gh instance/object. The API maintains the following member variables:

  • {string} gh.username - username of the authenticated user.
  • {string} gh.password - password of the authenticated user.
  • {object} gh.user - current information about the authenticated user.
  • {int} gh.status - HTTP status code of the last transaction with GitHub API.

Arguments

  • {string} username - GitHub username for authentication.
  • {string} password - GitHub password for authentication.

Notes

If the authentication fails or some other error is reported by GitHub, the error message is thrown.

Back to top


Function: GitHub.getUser

Synopsis

var user = gh.getUser();
var user = gh.getUser(username);

Get information about a GitHub user, or the currently authenticated user.

Arguments

  • {string} username - GitHub user to get information for.

Returns

  • {object} user - information about the user.

Back to top


Function: GitHub.editUser

Synopsis

var result = gh.editUser(userInfo);

Update the authenticated user.

The userInfo object has the following form:

  • {string} name - optional
  • {string} email - optional
  • {string} blog - optional
  • {string} company - optional
  • {string} location - optional
  • {boolean} hireable - optional
  • {string} bio - optional

Arguments

  • {object} userInfo - Object containing information to update for the authenticated user.

Returns

  • {object} result - Object containing the information about the authenticated user.

Back to top


Function: GitHub.getEmails

Synopsis

var emails = gh.getEmails();

Get email addresses for the authenticated user.

Returns

  • {array} emails - array of email addresses for the user.

Back to top


Function: GitHub.addEmails

Synopsis

var emails = gh.addEmails(newEmails);

Add email address(es).

Arguments

  • {array} newEmails - array of email addresses to add. returrn {array} emails - array of emails for user, after the additions.

Back to top


Function: GitHub.deleteEmails

Synopsis

gh.DeleteEmails(newEmails);

Delete email address(es).

Arguments

  • {array} newEmails - array of email addresses to delete.

Note

This method will throw a descriptive error {object} if GitHub reports an error.

Back to top


Function: GitHub.listFollowers

Synopsis

var followers = gh.listFollowers();
var followers = gh.listFollowers(username);

List followers of the specified GitHub user, or the currently authenticated user.

Arguments

  • {string} username - GitHub username to get followers for.

Returns

  • {array} followers - array of objects describing each user that is following the specified user.

Back to top


Function: GitHub.listFollowing

Synopsis

var following = gh.listFollowing();
var following = gh.listFollowing(username);

List users that the specified GitHub user, or the currently authenticated user, is following.

Arguments

  • {string} username - GitHub username to get followers for.

Returns

  • {array} following - array of objects describing each user that is being following by the specified user.

Back to top


Function: GitHub.amFollowing

Synopsis

var amFollowing = gh.amFollowing(username);

Check if authenticated user is following another user.

Arguments

  • {string} username - GitHub username to check if following.

Returns

  • {boolean} amFollowing - true if authenticated user is following the specfied user.

Back to top


Function: GitHub.follow

Synopsis

var success = gh.follow(username);

Follow a user.

Arguments

  • {string} username - GitHub username to follow.

Returns

  • {boolean} success - true if authenticaed user is following the specified user.

Back to top


Function: GitHub.unfollow

Synopsis

var success = gh.unfollow(username);

Stop following a user.

Arguments

  • {string} username - GitHub username to stop following.

Returns

  • {boolean} success - true if authenticated user is no longer following the specified user.

Back to top


Function: GitHub.listKeys

Synopsis

var keys = gh.listKeys();

List public keys for the authenticated user.

Returns

  • {array} keys - array of objects describing each of the publich keys for the authenticated user.

Back to top


Function: GitHub.getKey

Synopsis

var key = gh.getKey(id);

Get a single public key for the authenticated user.

Arguments

  • {string} id - id of the key to retrieve.

Notes

The GitHub.listKeys method returns an array of objects, one per key. Each object contains the id of the key.

Back to top


Function: GitHub.createKey

Synopsis

var response = gh.createKey(title, key);

Create a public key.

Arguments

  • {string} title - The title for the key.
  • {string} key - The text of the RSA/DSA/etc. key to add.

Returns

  • {object} response - The key that was added, or an object with descriptive information about why the key could not be added.

Discussion

The GitHub WWW site allows you to upload RSA/DSA/etc. keys to allow git:repoURI authentication. You will generate the key (file) on your workstation and upload it to GitHub using this method. The title is a string that identifies the key, e.g. "my workstation."

Back to top


Function: GitHub.updateKey

Synopsis

var response = GitHub.updateKey(id, title, key);

Update an existing public key.

Arguments

  • {string} id - id of the key to update.
  • {string} title - The title for the key.
  • {string} key - The text of the RSA/DSA/etc. key to add.

Returns

  • {object} response - The key that was updated, or an object with descriptive information about why the key could not be updated.

Back to top


Function: GitHub.deleteKey

Synopsis

var success = GitHub.deleteKey(id);

Delete a public key.

Arguments

  • {string} id - id of the key to delete.

Returns

  • {boolean} success - true if the key was deleted.

Back to top


Function: GitHub.listRepos

Synopsis

var repos = gh.listRepos();
var repos = gh.listRepos(user);
var repos = gh.listRepos(user, type);

List repositories for the specified user. The type variable may be "all", "owner", "member" or "public" (default).

Arguments

  • {string} user - username of user to get repositories for. If ommitted, it is the current authenticated user.
  • {string} type - type of repositories to get.

Returns

  • {array} repos - array of repo objects.

Back to top


Function: GitHub.listOrgRepos

Synopsis

var repos = gh.listOrgRepos(org);

List repositories for the specified organization.

Arguments

  • {string} org - name of organization

Returns

  • {array} repos - array of repo objects.

Back to top


Function: GitHub.getRepository

Synopsis

var info = gh.getRepository(repo);

Get information about a repository.

Arguments

  • {string} repo - name of repository to get information about (e.g. mschwartz/SilkJS or SilkJS)

Back to top


Function: GitHub.editRepository

Synopsis

var repoInfo = gh.editRepository(name, config);

Update a repository's settings.

The config object has the following members:

  • {string} name - required, name of repository.
  • {string} description - optional
  • {string} homepage - optional
  • {boolean} private - optional, true to create a private repository, false to create a public one. Private repositories require a paid GitHub account. Default is false.
  • {boolean} has_issues - optional, true to enable issues for the repository, false to diaable them. Default is true.
  • {boolean} has_wiki - optional, true to enable the wiki for this repository, false to disable it. Default is true.
  • {boolean} has_downloads - optional, true to enable downloads for this repository, false to disable them. Default is true.
  • {int} team_id - the id of the team that will be granted access to this repository. This is only valid when creating a repo in an organization.

Arguments

  • {string} name - name of repository to update, e.g. mschwartz/SilkJS or just SilkJS
  • {object} config - object describing the attributes of the repository to be updated. See notes above.

Returns

  • {object} repo - object describing the created repository.

Back to top


Function: GitHub.listContributors

Synopsis

var contributors = gh.listcontributors(repo);

Get list of contributors for a repository.

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {array} contributors - array of objects describing each contributor.

Back to top


Function: GitHub.listLanguages

Synopsis

var languages = gh.listLanguages(repo);

Get list of languages of a repository (programming languages).

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {object} collaborators - object/hash; key is language (e.g. "C"), value is (lines of code?)

Back to top


Function: GitHub.listTeams

Synopsis

var teams = gh.listTeams(repo);

Get list of teams for a repository.

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {array} collaborators - array of objects describing each team.

Back to top


Function: GitHub.listTags

Synopsis

var tags = gh.listTags(repo);

Get list of tags for a repository.

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {array} tags - array of objects describing each tag.

Back to top


Function: GitHub.listBranches

Synopsis

var branches = gh.listBranches(repo);

Get list of branches for a repository.

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {array} tags - array of objects describing each branch.

Back to top


Function: GitHub.listCollaborators

Synopsis

var collaborators = gh.listCollaborators(repo);

Get list of collaborators for a repository.

Arguments

  • {string} repo - name of repo, e.g. "mschwartz/SilkJS" or "SilkJS" if the authenticated user is "mschwartz"

Returns

  • {array} collaborators - array of objects describing each collaborator.

Back to top


Function: GitHub.isCollaborator

var isCollaborator = gh.isCollaborator(repo, user);

Determine if a user is a collaborator for a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} oUser - name of a user to check.

Returns

  • {boolean} isCollaborator - true if user is a collaborator.

Back to top


Function: GitHub.addCollaborator

var success = gh.addCollaborator(repo, user);

Add a user as a collaborator for a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} oUser - name of a user to add.

Returns

  • {boolean} success - true if user added as a collaborator.

Back to top


Function: GitHub.removeCollaborator

var success = gh.removeCollaborator(repo, user);

Remove a user as a collaborator for a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} oUser - name of a user to remove.

Returns

  • {boolean} success - true if user removed as a collaborator.

Back to top


Function: GitHub.getCommit

Synopsis

var commit = gh.getCommit(repo, sha);

Get a single commmit.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} sha - sha string that identifies the commit

Returns

  • {object} commit - info about the commit

Back to top


Function: GitHub.listComments

Synopsis

var comments = gh.listComments(repo); // get comments for repository
var comments = gh.listComments(repo, sha); // get comments for a single commit

List comments for a repository or a single commit

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} sha - sha string that identifies the commit

Returns

  • {Object} comments - array of comments

Back to top


Function: GitHub.createCommitComment

Synopsis

var comment = gh.createCommitComment(repo, sha, config);

Create a commit comment

The config parameter is an object with the following members:

  • {string} body - required, body of the comment
  • {string} commit_id - required, SHA of the commit to comment on
  • {number} line - required, line number in the file to comment on
  • {string} path - required, relative path of file to comment on
  • {number} position - required - line index in the diff to comment on

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} sha - sha string that identifies the commit
  • {object} config - see description above.

Returns

  • {object} comment - resulting comment information

Back to top


Function: GitHub.getCommitComment

Synopsis

var comment = gh.getCommitComment(repo, id);

Get a single commit comment

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} id - sha string that identifies the commit comment

Returns

  • {object} comment - resulting comment information

Back to top


Function: GitHub.updateCommitComment

Synopsis

var comment = gh.updateCommitComment(repo, id, body);

Get a single commit comment

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} id - sha string that identifies the commit comment
  • {string} body - new text for the comment

Returns

  • {object} comment - resulting comment information

Back to top


Function: GitHub.compareCommits

Synopsis

var info = gh.compareCommits(repo, base, head);

Compare two commits

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} base - SHA of base commit
  • {string} head - SHA of head commit

Returns

  • {object} info - comparison information about the two commits

Back to top


Function: GitHub.deleteCommitComment

Synopsis

var success = gh.deleteCommitComment(repo, id);

Delete a commit comment.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} id - sha string that identifies the commit comment

Returns

  • {boolean} success - true if comment deleted

Notes

If an error occurs, an exception is thrown.

Back to top


Function: GitHub.listDownloads

Synopsis

var downloads = gh.listDownloads(repo);

List downloads for a repository

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {array} downloads - array of objects describing each download item

Back to top


Function: GitHub.getDownload

Synopsis

var download = gh.getDownload(repo, id);

Get a single download

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} id - id of the download to get

Returns

  • {object} downloads - object describing each download item

Back to top


Function: GitHub.createDownload

Synopsis

var success = gh.createDownload(repo, path);
var success = gh.createDownload(repo, path, description);
var success = gh.createDownload(repo, path, description, contentType);

Create a download for a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} path - path to file to upload (e.g. the download file to create).
  • {string} description - description of the download.
  • {string} contentType - content-type of file (MIME type)

Returns

  • {boolean} success - true if download was created

Back to top


Function: GitHub.deleteDownload

Synopsis

var success = gh.deleteDownload(repo, id);

Delete a download.

The id parameter can be determined by looking at the id emmber of the object for the download returned by GitHub.listDownloads().

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} id - id of download to delete.

Returns

  • {boolean} success - true if the download was deleted.

Back to top


Function: GitHub.listForks

Synopsis

var forks = gh.listForks(repo);
var forks = gh.listForks(repo, sort);

List forks of a repo.

The sort parameter may be one of the following:

  • 'newest'
  • 'oldest'
  • 'watchers'

Default value for sort is 'newest'

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} sort - one of the above values

Returns

  • {Array} forks - array of objects describing each of the forks for the repo

Back to top


Function: GitHub.createFork

Synopsis

var success = gh.createFork(repo);
var success = gh.createFork(repo, org);

Create a fork for the authenticated user.

If the org parameter is supplied, it is an organization login; the repository will be forked into this organization.

Forking a repository happens asynchronously. Therefore, you may have to wait a short period before accessing the git objects. If this takes longer than 5 minutes, contact GitHub customer support.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} org - organization to fork into.

Returns

  • {boolean} success - true if fork request was accepted.

Back to top


Function: GitHub.listRepoDeployKeys

Synopsis

var keys = gh.listRepoDeployKeys(repo);

List Repo Deploy Keys.

See Also:

http://help.github.com/deploy-keys/
http://developer.github.com/v3/repos/keys/

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {Array} keys - array of repo deploy keys.

Back to top


Function: GitHub.getRepoDeployKey

Synopsis

var key = gh.getRepoDeployKey(repo, id);

Get a specific repo deploy key by id.

See Also:

http://help.github.com/deploy-keys/
http://developer.github.com/v3/repos/keys/

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {int} id - id of key to return.

Returns

  • {Object} key - object containing information for a key.

Back to top


Function: GitHub.createRepoDeployKey

Synopsis

var key = gh.createRepoDeployKey(repo, title, key);

This function creates a repo deploy key with the given title and SSH-type key (e.g. DSA or RSA string).

See Also:

http://help.github.com/deploy-keys/
http://developer.github.com/v3/repos/keys/

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} title - title for the key.
  • {string} key - the RSA or DSA key to add.

Returns

  • {Object} key - information about the created key.

Back to top


Function: GitHub.editRepoDeployKey

Synopsis

var key = gh.editRepoDeployKey(repo, id, title, key);

This function updates a repo deploy key with the given title and SSH-type key (e.g. DSA or RSA string).

See Also:

http://help.github.com/deploy-keys/
http://developer.github.com/v3/repos/keys/

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {int} id - id of key to update.
  • {string} title - title for the key.
  • {string} key - the RSA or DSA key to add.

Returns

  • {Object} key - information about the created key, or false if an error occurred.

Back to top


Function: GitHub.deleteRepoDeployKey

Synopsis

var success = gh.getRepoDeployKey(repo, id);

Delete a specific repo deploy key by id.

See Also:

http://help.github.com/deploy-keys/
http://developer.github.com/v3/repos/keys/

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {int} id - id of key to delete.

Returns

  • {boolean} success - true if key was deleted.

Back to top


Function: GitHub.listWatchers

Synopsis

var watchers = gh.listWatchers(repo);

Lists watchers of a repository.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {Array} watchers - array of watchers information

Back to top


Function: GitHub.listWatching

Synopsis

var repos = gh.listWatching(user);

List repos being watched by a user.

Arguments

  • {string} user - GitHub user name.

Returns

  • {Array} repos - array of repo information.

Back to top


Function: GitHub.amWatching

Synopsis

var amWatching = gh.amWatching(repo);

Check if current user is watching a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {boolean} amWatching - true if user is watching the repo.

Back to top


Function: GitHub.watch

Synopsis

var success = gh.watch(repo);

Watch a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {boolean} success - true if watch request was successful.

Back to top


Function: GitHub.stopWatching

Synopsis

var success = gh.stopWatching(repo);

Stop watching a repo.

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.

Returns

  • {boolean} success - true if unwatch request was successful.

Back to top


Function: GitHub.getBlob

Synopsis

var blob = gh.getBlob(repo, sha);

Get a blob.

The returned blob has the following members:

  • {string} content: content of the blob
  • {string} encoding: encoding of the blob (e.g. "utf-8")

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {string} sha - sha of the blob to get

Returns

  • {Object} blob - object of the form described above.

Back to top


Function: GitHub.createBlob

Synopsis

var sha = gh.createBlob(repo, obj);

Create a blob.

The obj parameter describes the blob to be created, and has the following members:

  • {string} content: content of the blob
  • {string} encoding: encoding of the blob (e.g. "utf-8")

Arguments

  • {string} repo - name of repo, e.g. mschwartz/SilkJS or SilkJS if the authenticated user is mschwartz.
  • {object} obj - description of blob, see above.

Returns

  • {string} sha - the sha of the created blob, or false if an error occurred.

Back to top


blog comments powered by Disqus