Git spindle for BitBucket

git bucket or git bb lets you use your BitBucket account from the command line. Among other things, it lets you create and fork repositories, or file pull requests.

Basic usage

The first time you use git bb, it will ask you for your BitBucket username and password. These are stored in ~/.gitspindle. Never share this file with anyone as it gives full access to your BitBucket account.

git bb whoami

A simple command to try out is git bb whoami, which tells you what BitBucket thinks about who you are. For example:

dennis@lightning:~$ git bb whoami
Dennis Kaarsemaker
Dennis Kaarsemaker
Profile:  https://bitbucket.org/seveas
Website:  http://www.kaarsemaker.net/
Location: The Netherlands
RSA key   ...N0nFw3oW5l (Dennis Kaarsemaker (git))
git bb whois <user>...

If you want to see this information about other users, use git bb whois:

dennis@lightning:~$ git bb whois bblough
Bill Blough
Profile:  https://bitbucket.org/bblough
git bb repos [--no-forks] [<user>]

List all repositories owned by a user, by default you. Specify --no-forks to exclude forked repositories.

git bb add-public-keys [<key>...]

Add SSH public keys (default: ~/.ssh/*.pub) to your account.

git bb public-keys [<user>]

Display all public keys of a user, in a format that can be added to ~/.authorized_keys.

Using multiple accounts

git bb supports using more than one account. To use a non-default, you have to tell git bb which account to use using --account:

$ git bb --account test-account clone seveas/whelk
git bb add-account <alias>

To add a new account, use the add-account command.

git bb config [--unset] <key> [<value>]

Set, get or unset a configuration variable in ~/.gitspindle. Similar to git config, but only single-level keys are allowed, and the section is hardcoded to be the current account.

Interacting with repositories

git bb create [--private] [--team=<team>] [--description=<description>]

Create a (possibly private) repository on BitBucket for your current repository. An optional description can be given too. After running this command, a repository will be created on BitBucket and your local repository will have BitBucket as remote “origin”, so git push origin master will work.

By default the repository is created under your account, but you can specify a team to create the repository for.

git bb set-origin [--ssh|--http] [--triangular [--upstream-branch=<branch>]]

Fix the configuration of your repository’s remotes. The remote “origin” will be set to your BitBucket repository. If “origin” is a fork, an “upstream” remote will be set to the repository you forked from.

All non-tracking branches with a matching counterpart in “origin” will be set to track “origin” (push and pull to it). Use --triangular to set remotes in a triangular fashion where git pull pulls from “upstream” and git push pushes to “origin”. This also sets the configuration option remote.pushDefault, so that new branches are pushed to “origin” even if they track a branch in “upstream”. All non-tracking branches are set up to track a matching counterpart in “upstream” except if --upstream-branch explicitly specifies a branch like “master” in “upstream” that all branches should track.

For “origin”, an SSH url is used. For “upstream”, set-origin defaults to adding a git url, but this can be overridden. For private repos, SSH is used.

git bb clone [--ssh|--http] [--triangular [--upstream-branch=<branch>]] [--parent] [git-clone-options] <repo> [<dir>]

Clone a BitBucket repository by name (e.g. seveas/whelk) or URL. The “origin” remote will be set and, like with set-origin, if “origin” is a fork the “upstream” remote will be set too. The option --triangular can be used for a triangular setup.

Defaults to cloning from a git url, but this can be overridden. For private repos, SSH is used.

This command accepts all options git clone accepts and will forward those to git clone.

git bb cat <file>...

Display the contents of a file on BitBucket. File can start with repository names and refs. For example: master:bin/git-bb, git-spindle:master:bin/git-bb or seveas/git-spindle:master:bin/git-bb.

git bb ls [<dir>...]

Display the contents of a directory on BitBucket. Directory can start with repository names and refs. For example: master:bin/git-bb, git-spindle:master:bin/git-bb or seveas/git-spindle:master:bin/git-bb.

git bb fork [--ssh|--http] [--triangular [--upstream-branch=<branch>]] [<repo>]

Fork another person’s git repository on BitBucket and clone that repository locally. The repository can be specified as a (git) url or simply username/repo. Like with set-origin, the “origin” and “upstream” remotes will be set up too. The option --triangular can be used for a triangular setup.

Defaults to cloning from a git url, but this can be overridden.

Calling fork in a previously cloned-but-not-forked repository will create a fork of that repository and set up your remotes.

git bb forks [<repo>]

List all forks of this repository, highlighting the original repository.

git bb add-remote [--ssh|--http] <user> [<name>]

Add a users fork as a remote using the specified name or the user’s login as name for the remote. Defaults to adding an http url, but this can be overridden. For private repos SSH is used.

git bb fetch [--ssh|--http] <user> [<refspec>]

If you don’t want to add a user’s fork as a remote, but to want to fetch some refs from it, you can use the fetch command. You can tell it which refs to fetch, and if you don’t give a refspec, it will fetch all branches.

git bb browse [--parent] [<repo>] [<section>]

Browse a repository (or its parent) on BitBucket. By default the repository’s homepage is opened, but you can specify a different section, such as src, src, commits, branches, pull-requests, downloads, admin, issues or wiki.

git bb mirror [--ssh|--http] [<repo>]

Mirror a repository from BitBucket. This is similar to clone, but clones into a bare repository and maps all remote refs to local refs. When run without argument, the current repository will be updated. You can also specify user/* as repository to mirror all repositories of a user.

Administering repositories

git bb privileges [<repo>]

List all people with access to this repository. Beware that BitBucket aggressively caches permissions and it can take up to a minute for a change in permissions to be reflected in the output of this command. The owner of the repository is also not listed in the output.

git bb add-privilege [--admin|--read|--write] <user>...

Grant people read, write or admin access to this repository.

git bb remove-privilege <user>...

Revoke access to this repository.

git bb invite [--read|--write|--admin] <email>...

Invite users by e-mail to collaborate on this repository.

git bb deploy-keys [<repo>]

List all deploy keys for this repository

git bb add-deploy-key <key>...

Add a deploy key to a repository, which can be used to fetch and push data via ssh.

git bb remove-deploy-key <key>...

Remove a deploy key by id. Use the git bb deploy-keys command to see the id’s of your deploy keys.

Issues and pull requests

git bb issues [<repo>] [--parent] [<filter>...]

List all open issues for the current repository, or the one specified in the <repo> argument. If you run this outside a repository, or with – as <repo>, it will list issues in all your repositories. When you specify --parent, this will operate on the parent repositoryD.

You can specify filters in the form filter=value to filter issues. Supported filters are:

  • status, accepted values: new, open, resolved, on hold, invalid, duplicate, wontfix

  • priority, accepted values; trivial, minor, major, critical, blocker

  • title

  • is_spam, accepted values: true, false

Filter values can be prefixed with ! to negate the match, ~, or ^ or $ to indicate a ‘contains’, ‘starts with’ or ‘ends with’ operation.

git bb issue [<repo>] [--parent] [<issue>...]

Shows details about the mentioned issue numbers. As with issues, you can use the --parent option to use the parent repository. If you do not specify an issue number, you will be prompted for a message that will be used to create a new issue.

git bb pull-request [--yes] [<yours:theirs>]

Files a pull request to merge branch “yours” (default: the current branch) into the upstream branch “theirs” (default: the tracked branch of “yours” if it is in the upstream repository, otherwise the default branch of the upstream repository, usually “master”). Like for a commit message, your editor will be opened to write a pull request message. The comments of said message contain the shortlog and diffstat of the commits that you’re asking to be merged. Note that if you use any characterset in your logs and filenames that is not ascii or utf-8, git bb will misbehave.

git bb apply-pr <pr-number>

BitBucket makes it easy for you to merge pull requests, but if you want to keep your history linear, this one is for you. It applies a pull request using git cherry-pick instead of merging.

Snippets

git bb snippet [--description=<description>] <file>...

Creates a snippet (with optional description) from the named files. If you specify - as filename, stdin will be used, making it easy to pipe command output to BitBucket, for example: fortune | git bb snippet -

git bb snippets [<user>]

List your snippets, or those created by another user.