========================
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}