Git bz configuration

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development > Git

Git bz requires python (2.7.1 should work).

Optionally, if you plan on sending bugs to Bugzilla from git, you'll need to tell it your username and password or if you have Chrome or Firefox installed on your dev machine, and have logged into Bugzilla at least once from that machine, git-bz can use that.


Get ready

Note: If you are using a KohaDevBox you do not have to download and configure git-bz, you should follow KohaDevBox's instructions instead and jump to the "Using git-bz" section.

Download git-bz

In your home directory, run:

 git clone
 cd ~/git-bz
 git fetch origin
 git checkout -b apply_on_cascade origin/apply_on_cascade

This apply_on_cascade branch contain some specific changes compared to the original fishsoup.

If you want to use the old fishsoup branch and use the koha-community repository, you can run:

 git clone
 cd ~/git-bz
 git fetch origin
 git checkout -b fishsoup origin/fishsoup

Configure git-bz

symlink git-bz somewhere that's in your $PATH. For example,

sudo ln -s ~/git-bz/git-bz /usr/local/bin/git-bz

will often work.

You might need to add /usr/local/bin/ to your path. To do that edit ~/.bash_profile with your favorite editor and add :/usr/local/bin to the path. (If you're using the terminal in your virtual machine's desktop environment use ~/.profile instead of ~/.bash_profile.)

export PATH

(An alternative to symlinking and adding /usr/local/bin/ to your path is simply to add /home/USERNAME/git-bz to your path using the model code snippet above.)

Log out and back in and it should work.

Then change to your koha git checkout

cd ~/kohaclone


git config bz.default-tracker
git config bz.default-product Koha
git config --global /bugzilla3
git config --global true
git config --global core.whitespace trailing-space,space-before-tab
git config --global apply.whitespace fix

If you don't mind storing your Bugzilla credentials in your config files, run the following commands.

git config --global U
git config --global PW

These are --global to avoid keeping your username and password in the clear in the repository, but keeping them in your global .gitconfig isn't great either.

If you don't want to store your password in your config files, use git-credential

git config --global credential.helper 'cache --timeout 3600'  # timeout in seconds
git config --global credential. U
git config --global true

replacing U with your Bugzilla username and PW with your Bugzilla password. You need to set your user name and password (or setup git-credential) regardless of whether or not you intend to upload patches using git-bz (FIXME: is this a bug?).

Now you are ready to do some work with git-bz

Using git-bz

Check out a branch where xxxxx is your bug number:

git checkout -b bug_xxxxx origin/master

Bugs with one patch

Submitting a patch

This command simply attaches the last commit to the listed bug -- no need to git format-patch

git bz attach xxxxx HEAD

With -e, allows editing of the attachments on the listed bug -- obsoleting old attachments, etc. (This operation can time out rather quickly, if you get a "traceback" from Python try once more and be quicker.)

git bz attach -e xxxxx HEAD
  • HEAD attaches the last commit to the bug.


Apply a patch from Bugzilla

git bz apply xxxxx

<Test it>

You can apply the patches interactively [i] if you want to change the order or only apply certain patches.

Signing off

If you're signing off on a patch and want to attach the signed off patch to the bug you can use:

git commit --amend -s 

and then:

git bz attach -e xxxx HEAD

The -e option will let you edit the bug report attributes. It is handy to switch the status to Signed Off.

If you forgot, it's time to open your bug in Bugzilla using the URL and change the bug's status to Signed Off

Bugs with more than one patch

Getting the patches

If a bug has more than one patch, you can still get all of them the same way as described above:

git bz apply xxxx

This will walk you through all the patches and let you choose which ones you want to apply.

Signing off

If you are signing off more than one patch (after testing them, of course) you can do this:

Put the following alias in your .git/config file:

so = "!f() { git rebase --interactive --exec 'git commit --amend --signoff --no-edit' HEAD~$1; }; f"
Note: This alias is already defined if you are using a KohaDevBox

Until you have this alias defined, you can sign off the number of patches you want with the following git command:

git so X

where X is the number of patches to sign-off

Attaching patches

Now it's time for attaching the patches to the bug. To attach the last X patches, run:

git bz attach -e xxxxx HEAD~X..HEAD

Since the last HEAD is not mandatory (if missing it will default to HEAD), this command is similar to:

git bz attach -e xxxxx HEAD~X..

So if you have 2 patches to attach, you can do this with:

git bz attach -e xxxxx HEAD~2..

Uncomment the # before each patch you would like to obsolete before saving. You will have to be pretty fast here, if you dawdle git bz will bring back a nasty error, but you can simply rerun the command (making your edits faster this time) to avoid it.

To specify a more complex range of commits, see gitrevisions(7) for details.


Full documentation can be found at


No patch applied

So, you have a bug, and type something like:

dpavlin@koha-dev:/srv/kohaclone$ git bz apply 7161
Bug 7161 - Open Library - Larger image, Read, borrow and checked-out status

and nothing happens after it? It's quite possible that bug doesn't have patch attached.

Or, if it does have file attached (which you can see under attachments) it might have application/octet-stream type instead of patch. Go into details > Edit details and check patch checkbox.

Now git-bz will work as expected:

dpavlin@koha-dev:/srv/kohaclone$ git bz apply 7161
Bug 7161 - Open Library - Larger image, Read, borrow and checked-out status

Open Library - Larger image, Read, borrow and checked-out status
Apply? [yn] y

Applying: Bug-7161 Open Library - Larger image, Read, borrow and checked-out status

Reset branch to clean master

Abort application of patches from e-mail

git am --abort

Remove all local changes and revert your checkout to clean upstream master

git reset --hard origin/master

git bz attach -e timeout

If you are not fast enough git bz attach -e might time-out on you with a long python stack trace similar to this:

dpavlin@koha-dev:/srv/koha_ffzg$ git bz attach -e 7161 HEAD
Traceback (most recent call last):
File "/usr/local/bin/git-bz", line 2142, in <module>
File "/usr/local/bin/git-bz", line 1622, in do_attach
attach_commits(bug, commits, edit_comments=global_options.edit)
File "/usr/local/bin/git-bz", line 1572, in attach_commits
bug.create_patch(description, body, filename, patch, obsoletes=obsoletes, status=status)
File "/usr/local/bin/git-bz", line 1188, in create_patch
response = self.server.send_post("/attachment.cgi", fields, files)
File "/usr/local/bin/git-bz", line 948, in send_post
return self.send_request("POST", url, data=body, headers={ 'Content-Type': content_type })
File "/usr/local/bin/git-bz", line 884, in send_request
response = connection.getresponse()
File "/usr/lib/python2.6/", line 990, in getresponse
File "/usr/lib/python2.6/", line 391, in begin
version, status, reason = self._read_status()
File "/usr/lib/python2.6/", line 355, in _read_status
raise BadStatusLine(line)

To fix it, just re-try the command and it should work.

Known bugs

  1. --mail option can't send to other recipients - maybe should have a repository-specific configuration option?
  2. default statuses aren't the default Bugzilla ones - maybe the koha-community ones should be added by a repository-specific configuration option and maybe activated automatically if it sees in use?
  3. not possible to apply patches without -3 - should have a config or option to suppress it.
  4. only handles ASCII characters in commit message

Known problems

$ /usr/local/bin/git-bz
-su: /usr/local/bin/git-bz : /usr/bin/python : mauvais interpr├ęteur: Aucun fichier ou dossier de ce type
$ ls /usr/bin/py*
/usr/bin/pydoc2.6  /usr/bin/pygettext2.6  /usr/bin/python2.6
# ln -s /usr/bin/python2.6 /usr/bin/python

But if the above happens, your python installation is probably broken and you just made the problem worse if there's a package manager...

Developer handbook

Personal tools