Using Breezy with GitHub

GitHub: the largest code-hosting site

This tutorial looks at how Breezy and GitHub can be used together.

Accessing code in GitHub using Breezy

Getting the code for a project

Breezy users can grab code from GitHub using regular GitHub URLs:

brz branch git://github.com/owner/name

where owner is the name of the owner and name is the repository name. Here are some examples:

brz branch https://github.com/inkscape/inkscape
brz branch git://github.com/KDE/amarok
brz branch https://github.com/python/cpython

You can then browse the code locally using your favorite editor or IDE and change the code if you wish.

To access a non-default branch, specify the ‘branch’ segment parameter:

brz branch https://github.com/inkscape/inkscape,branch=backports

Publishing your changes

Having fixed that annoying bug or added that cool feature you’ve always wanted, it’s time to impress your friends and make the world a better place by making your code available to others. As explained earlier, GitHub is a code hosting service so you can push your branch to it and others can access your code from there.

The first time you use GitHub, you will need to log into to your GitHub account with Breezy. This can be done by running brz github-login. This will prompt you for your password, and store the authentication token in ~/.config/breezy.

You can now use either brz publish to upload the changes back to GitHub, or brz propose to upload to the changes to GitHub and create merge proposal.

Both brz publish and brz propose will create a fork of the upstream repository and then push your local changes to the active branch (or another branch specify with the –name argument).

For example, running brz publish --name=my-branch in your local inkscape clone will create https://github.com/jelmer/inkscape if your GitHub username is “jelmer”, and it will open your editor to allow you to enter the merge proposal description.

Subsequent use of brz publish in the local branch (e.g. to push more commits) will update the previously created branch.

Associating branches with GitHub issues

The standard Breezy bugtracking functionality can also be used for GitHub issues.

When you commit using Breezy, use the –fixes option like this:

brz commit --fixes github:inkscape/inkscape/1234

where 1234 is the bug ID. This will add some metadata to the commit message.

You can also define a short name for a specific project, by adding an alias for a project. For example, to add an alias for dulwich:

brz config bugtracker_dulwich_url=https://github.com/dulwich/dulwich/issues/{id}