Source

bitbucketjs.bitbucket.org / src / README.text

Full commit
,__,    ,__,,__,  ,__,                   ,__,           ,__,      ,__,
|  |    |__||  |_,|  |                   |  | ,__,      |  |_,    |__|
|  |__, ,__,|  ,_||  |__, ,__, ,__, ,___,|  |/  /  ,__, |  ,_|    ,__, ,___,
|  ,_, \|  ||  |  |  ,_, \|  | |  |/ ,__||  ,  /  / __ \|  |      |  |/  __|
|  |_|  |  ||  |_,|  |_|  |  |_|  |  |__,|  |\  \|  ___/|  |_,,__,|  |\__  \
|______/|__| \___||______/ \_____/ \____||__| \__|\____/ \___||__||  |_____/
,---------------------------------------------------------------|___/------,
|  An intuitive JavaScript wrapper for the counterintuitive Bitbucket API  |
'--------------------------------------------------------------------------'

bitbucket.js makes communicating with the Bitbucket API relatively painless. Due to the asynchronous nature of this communication, methods cannot return the requested information immediately. Instead, they accept callbacks.

In general, code will take the following form:

  1. One of the constructors attached to the global bitbucket object will be called, and the resulting object assigned to a variable for reuse.

  2. One of this object's methods will be invoked to create, update, or delete a corresponding Bitbucket resource, or simply to read it.

For example:

# Create a repository object.
# This does not send a request to Bitbucket, it simple creates
# an object with access to various useful methods for doing so.
piston = new bitbucket.repository "jespern", "django-piston"

# Invoke a method on the repository object.
# The callback is in this case provides an array of followers.
piston.followers (followers) ->
  alert "#{piston} has #{followers.length} followers"

:::javascript
// Create a repository object.
// This does not send a request to Bitbucket, it simple creates
// an object with access to various useful methods for doing so.
var piston = new bitbucket.repository("jespern", "django-piston");

// Invoke a method on the repository object.
// The callback is in this case provides an array of followers.
piston.followers(function (followers) {
  alert(piston + " has " + followers.length + " followers");
});

Note: The new keyword may be omitted when calling the various constructor functions of the bitbucket object.

bitbucket.js relies upon jQuery.ajax(). Every method that communicates with Bitbucket's API accepts an options hash which it passes to jQuery.ajax(). Ajax requests are asynchronous, so one must provide a success callback. As a convenience, the following are equivalent:

piston.followers
  success: (followers) ->
    alert "#{piston} has #{followers.length} followers"

:::javascript
piston.followers({
  success: function (followers) {
    alert(piston + " has " + followers.length + " followers");
  }
});

:::coffeescript
piston.followers (followers) ->
  alert "#{piston} has #{followers.length} followers"

:::javascript
piston.followers(function (followers) {
  alert(piston + " has " + followers.length + " followers");
});

repository

bitbucket.repository(username, slug)

Creates a repository object.

cram = bitbucket.repository "brodie", "cram"

:::javascript
var cram = bitbucket.repository("brodie", "cram");

Rather than providing username and slug as separate arguments, one may provide them as a single string, separated by a slash:

cram = bitbucket.repository "brodie/cram"

:::javascript
var cram = bitbucket.repository("brodie/cram");

repository.create

bitbucket.repository.create(attrs, options)

TODO

repository::details

repo.details(options)

Retrieves the repository's details from Bitbucket. The success callback receives a hash representing the repository.

repository::update

repo.update(attrs, options)

Updates the Bitbucket repository's attributes with those in the attrs hash.

repository::destroy

repo.destroy(options)

Deletes the repository from Bitbucket.

repo.destroy
  error: -> alert "an error occurred"
  success: -> alert "successfully deleted " + repo

:::javascript
repo.destroy({
  error: function () { alert("an error occurred"); },
  success: function () { alert("successfully deleted " + repo); }
});

repository::branches

repo.branches(options)

Retrieves a hash with the repository's branch names as its keys, and corresponding changesets as its values.

pypy = bitbucket.repository "pypy/pypy"
pypy.branches (branches) ->
  console.log "names:", names = Object.keys(branches).sort()
  console.log "attrs:", Object.keys(branches[names[0]]).sort()

# eventually logs...
# names: ["32ptr-on-64bit", "arm-backend-2", "avm", ...]
# attrs: ["author", "branch", "date", "files", "message",
# "node", "parents", "raw_author", "raw_node", "revision"]

:::javascript
var pypy = bitbucket.repository("pypy/pypy");
pypy.branches(function (branches) {
  var names = Object.keys(branches).sort();
  var attrs = Object.keys(branches[names[0]]).sort();
  console.log("names:", names);
  console.log("attrs:", attrs);
});

// eventually logs...
// names: ["32ptr-on-64bit", "arm-backend-2", "avm", ...]
// attrs: ["author", "branch", "date", "files", "message",
// "node", "parents", "raw_author", "raw_node", "revision"]

repository::changeset

repo.changeset(rev, options)

Retrieves the changeset specified by rev.

pypy = bitbucket.repository "pypy/pypy"
pypy.changeset "23235feffeef", (changeset) ->
  console.log "attrs:", Object.keys(changeset).sort()

# eventually logs...
# attrs: ["author", "branch", "date", "files", "message",
# "node", "parents", "raw_author", "raw_node", "revision"]

:::javascript
var pypy = bitbucket.repository("pypy/pypy");
pypy.changeset("23235feffeef", function (changeset) {
  console.log("attrs:", Object.keys(changeset).sort());
});

// eventually logs...
// attrs: ["author", "branch", "date", "files", "message",
// "node", "parents", "raw_author", "raw_node", "revision"]

repository::changesets

repo.changesets([params], options)

Retrieves some number of the repository's changesets. The optional params hash is used to specify start and limit parameters.

pypy = bitbucket.repository "pypy/pypy"
pypy.changesets start: "23235feffeef", limit: 5, (data) ->
  console.log "attrs:", Object.keys(data).sort()
  console.log "limit:", data.changesets.length
  console.log "attrs:", Object.keys(data.changesets[0]).sort()

# eventually logs...
# attrs: ["changesets", "count", "limit", "start"]
# limit: 5
# attrs: ["author", "branch", "date", "files", "message",
# "node", "parents", "raw_author", "raw_node", "revision"]

:::javascript
var pypy = bitbucket.repository("pypy/pypy");
pypy.changesets({start: "23235feffeef", limit: 5}, function (data) {
  console.log("attrs:", Object.keys(data).sort());
  console.log("limit:", data.changesets.length);
  console.log("attrs:", Object.keys(data.changesets[0]).sort());
});

// eventually logs...
// attrs: ["changesets", "count", "limit", "start"]
// limit: 5
// attrs: ["author", "branch", "date", "files", "message",
// "node", "parents", "raw_author", "raw_node", "revision"]

repository::diffstat

repo.diffstat(rev, options)

Retrieves the diffstat for the changeset specified by rev.

pypy = bitbucket.repository "pypy/pypy"
pypy.diffstat "688bcf1a07ed", (diffstats) ->
  console.log "attrs:", Object.keys(diffstats[0]).sort()
  console.log "added:", diffstats[0].diffstat.added
  console.log "removed:", diffstats[0].diffstat.removed

# eventually logs...
# attrs: ["diffstat", "file", "type"]
# added: 14
# removed: 9

:::javascript
var pypy = bitbucket.repository("pypy/pypy");
pypy.diffstat("688bcf1a07ed", function (diffstats) {
  console.log("attrs:", Object.keys(diffstats[0]).sort());
  console.log("added:", diffstats[0].diffstat.added);
  console.log("removed:", diffstats[0].diffstat.removed);
});

// eventually logs...
// attrs: ["diffstat", "file", "type"]
// added: 14
// removed: 9

repository::directory

repo.directory(rev, [path], options)

TODO

repository::file

repo.file(rev, path, options)

TODO

repository::followers

repo.followers(options)

TODO

repository::create_issue

repo.create_issue(attrs, options)

TODO

repository::update_issue

repo.update_issue(id, attrs, options)

TODO

repository::delete_issue

repo.delete_issue(id, options)

TODO

repository::issue

repo.issue(id, options)

TODO

repository::create_issue_comment

repo.create_issue_comment(id, attrs, options)

TODO

repository::update_issue_comment

repo.update_issue_comment(id, comment_id, attrs, options)

TODO

repository::delete_issue_comment

repo.delete_issue_comment(id, comment_id, options)

TODO

repository::issue_comment

repo.issue_comment(id, comment_id, options)

TODO

repository::issue_comments

repo.issue_comments(id, options)

TODO

repository::issue_followers

repo.issue_followers(id, options)

TODO

repository::issues

repo.issues([params], options)

TODO

repository::create_component

repo.create_component(name, options)

Creates a component with the specified name.

Bitbucket's issue tracker allows an issue to be categorized by the component to which it pertains. Components are case-sensitive strings which appear in a drop-down in the UI (since there's a many-to-one relationship between issues and components).

repo.create_component "ui",
  error: -> alert "an error occurred"
  success: -> alert "component created"

:::javascript
repo.create_component("ui", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("component created"); }
});

repository::update_component

repo.update_component(id, name, options)

Updates the name of the component specified by id.

repo.update_component 42084, "user interface",
  error: -> alert "an error occurred"
  success: -> alert "component updated"

:::javascript
repo.update_component(42084, "user interface", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("component updated"); }
});

repository::delete_component

repo.delete_component(id, options)

Deletes the component specified by id.

repo.delete_component 42084,
  error: -> alert "an error occurred"
  success: -> alert "component deleted"

:::javascript
repo.delete_component(42084, {
  error: function () { alert("an error occurred"); },
  success: function () { alert("component deleted"); }
});

repository::component

repo.component(id, options)

TODO

repository::components

repo.components(options)

TODO

repository::create_milestone

repo.create_milestone(name, options)

Creates a milestone with the specified name.

Bitbucket's issue tracker allows an issue to be categorized by the milestone to which it pertains. Components are case-sensitive strings which appear in a drop-down in the UI (since there's a many-to-one relationship between issues and milestones).

repo.create_milestone "launch",
  error: -> alert "an error occurred"
  success: -> alert "milestone created"

:::javascript
repo.create_milestone("launch", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("milestone created"); }
});

repository::update_milestone

repo.update_milestone(id, name, options)

Updates the name of the milestone specified by id.

repo.update_milestone 12575, "launch!",
  error: -> alert "an error occurred"
  success: -> alert "milestone updated"

:::javascript
repo.update_milestone(12575, "launch!", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("milestone updated"); }
});

repository::delete_milestone

repo.delete_milestone(id, options)

Deletes the milestone specified by id.

repo.delete_milestone 12575,
  error: -> alert "an error occurred"
  success: -> alert "milestone deleted"

:::javascript
repo.delete_milestone(12575, {
  error: function () { alert("an error occurred"); },
  success: function () { alert("milestone deleted"); }
});

repository::milestone

repo.milestone(id, options)

TODO

repository::milestones

repo.milestones(options)

TODO

repository::create_version

repo.create_version(name, options)

Creates a version with the specified name.

Bitbucket's issue tracker allows an issue to be categorized by the version to which it pertains. Components are case-sensitive strings which appear in a drop-down in the UI (since there's a many-to-one relationship between issues and versions).

repo.create_version "1.0",
  error: -> alert "an error occurred"
  success: -> alert "version created"

:::javascript
repo.create_version("1.0", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("version created"); }
});

repository::update_version

repo.update_version(id, name, options)

Updates the name of the version specified by id.

repo.update_version 18799, "v1.0",
  error: -> alert "an error occurred"
  success: -> alert "version updated"

:::javascript
repo.update_version(18799, "v1.0", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("version updated"); }
});

repository::delete_version

repo.delete_version(id, options)

Deletes the version specified by id.

repo.delete_version 18799,
  error: -> alert "an error occurred"
  success: -> alert "version deleted"

:::javascript
repo.delete_version(18799, {
  error: function () { alert("an error occurred"); },
  success: function () { alert("version deleted"); }
});

repository::version

repo.version(id, options)

TODO

repository::versions

repo.versions(options)

TODO

repository::privileges

repo.privileges([flags], options)

Retrieves a hash comprised of users and/or groups with access to the repository, and their corresponding access levels.

Whereas most methods are thin wrappers around jQuery.ajax(), this method makes two requests (Bitbucket's privileges and group-privileges endpoints are clusterfucks). The responses are transformed into a single, normalized data structure which is then passed to the success callback.

repo = bitbucket.repository "acme/acme-framework"
repo.privileges (privileges) ->
  console.log privileges

# eventually logs...
# {
#   "mwells": "admin"
#   "bpayne": "admin"
#   "swilson": "write"
#   "acme/developers": "write"
#   "acme/qa": "read"
#   "arogers": "write"
#   "ystokes": "read"
#   "nsteele": "write"
#   "msandoval": "read"
#   "tkelly": "read"
#   "thawkins": "write"
#   "jmoreno": "write"
# }

:::javascript
var repo = bitbucket.repository("acme/acme-framework");
repo.privileges(function (privileges) {
  console.log(privileges);
});

// eventually logs...
// {
//   "mwells": "admin",
//   "bpayne": "admin",
//   "swilson": "write",
//   "acme/developers": "write",
//   "acme/qa": "read",
//   "arogers": "write",
//   "ystokes": "read",
//   "nsteele": "write",
//   "msandoval": "read",
//   "tkelly": "read",
//   "thawkins": "write",
//   "jmoreno": "write"
// }

By default, all users and groups with access to the repository will appear in the hash, including members of groups with access. In the example above, ystokes, msandoval, and tkelly have no direct access to acme/acme-framework; rather, they have read access as members of acme/qa. If a user with direct access also belongs to one or more groups with access, the highest of the access levels applies. For example, the write access mwells and bpayne are afforded as members of acme/developers is trumped by their direct admin access.

One may provide flags to refine the result set:

flags       result set
======================================================================
0b111 (7)   groups with access, and all users with access
0b110 (6)   groups with access, and users with access via groups
0b101 (5)   groups with access, and users with direct access
0b100 (4)   groups with access
0b011 (3)   all users with access
0b010 (2)   users with access via groups
0b001 (1)   users with direct access

One may be interested only in users with direct access, for example:

repo.privileges (0b001, privileges) ->
  console.log privileges

# eventually logs...
# {
#   "mwells": "admin"
#   "bpayne": "admin"
#   "swilson": "read"
# }

:::javascript
repo.privileges(1, function (privileges) {
  console.log(privileges);
});

// eventually logs...
// {
//   "mwells": "admin",
//   "bpayne": "admin",
//   "swilson": "read"
// }

repository::tags

repo.tags(options)

TODO

repository::wiki_page

repo.wiki_page([title], options)

TODO

repository::url

repo.url(components...)

Used internally to calculate request URLs.

repository::toString

repo.toString()

Returns the repository's string representation in the form "username/slug".

repositories

bitbucket.repositories([params], options)

TODO

user

bitbucket.user(username)

Returns a new user object.

user.create

bitbucket.user.create(attrs, options)

Creates a Bitbucket user. The attrs hash should contain values for username, password, and email.

Related: creating a user.

user::details

user.details(options)

Retrieves the user's details from Bitbucket. The success callback receives a hash representing the user.

jespern = bitbucket.user "jespern"
jespern.details (details) ->
  console.log details.first_name + " " + details.last_name

# eventually logs...
# Jesper Noehr

:::javascript
jespern = bitbucket.user("jespern");
jespern.details(function (details) {
  console.log(details.first_name + " " + details.last_name);
});

// eventually logs...
// Jesper Noehr

user::events

user.events([params], options)

TODO

user::followers

user.followers(options)

TODO

user::privileges

user.privileges([flags], options)

TODO

user::repositories

user.repositories(options)

TODO

user::add_email_address

user.add_email_address(address, options)

TODO

user::set_primary_email_address

user.set_primary_email_address(address, options)

TODO

user::remove_email_address

user.remove_email_address(address, options)

TODO

user::email_address

user.email_address(address, options)

TODO

user::email_addresses

user.email_addresses(options)

TODO

user::add_ssh_key

user.add_ssh_key(attrs, options)

TODO

user::update_ssh_key

user.update_ssh_key(id, attrs, options)

TODO

user::remove_ssh_key

user.remove_ssh_key(id, options)

TODO

user::ssh_keys

user.ssh_keys(options)

TODO

user::url

user.url(components...)

Used internally to calculate request URLs.

send_invitation

bitbucket.send_invitation(address, access, repository, options)

Sends an invitation to the owner of the specified e-mail address, offering him read, write, or admin access (as specified by access) to the specified repository. If and when he accepts the invitation, he'll be prompted to create a Bitbucket account (unless he already has one).

bitbucket.send_invitation "brodie@sf.io", "write", "pypy/pypy",
  error: -> alert "an error occurred"
  success: -> alert "brodie@sf.io has been invitated"

:::javascript
bitbucket.send_invitation(
  "brodie@sf.io", "write", "pypy/pypy", {
  error: function () { alert("an error occurred"); },
  success: function () { alert("brodie@sf.io has been invitated"); }
});