/brz/remove-bazaar

========================

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}