From 170f40c2d1220e66c3084dafc135745357660956 Mon Sep 17 00:00:00 2001 From: "Owen W. Taylor" Date: Sat, 5 Sep 2009 09:50:38 -0400 Subject: Split out documentation Move the documentation from a giant comment at the start of the file into a separate asciidoc document. Among other revisions an 'EXAMPLE SESSION' section is added to give a sense of the normal workflow. Add a Makefile and asciidoc.conf for converting the asciidoc into HTML or a man page. --- .gitignore | 2 + Makefile | 14 +++ asciidoc.conf | 18 +++ git-bz | 205 +-------------------------------- git-bz.txt | 358 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 396 insertions(+), 201 deletions(-) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 asciidoc.conf create mode 100644 git-bz.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f5323c0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +git-bz.1 +git-bz.html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..45576f6 --- /dev/null +++ b/Makefile @@ -0,0 +1,14 @@ +%.xml: %.txt + asciidoc -f asciidoc.conf -d manpage -b docbook $< + +%.html: %.txt + asciidoc -f asciidoc.conf -d manpage $< + +%.1: %.xml + xmlto man $< + +upload-html: git-bz.html + DEST=`git config local.upload-html-dest` ; \ + if [ $$? = 0 ] ; then : ; else echo "upload location not configured" ; exit 1 ; fi ; \ + scp $< $$DEST + diff --git a/asciidoc.conf b/asciidoc.conf new file mode 100644 index 0000000..258607e --- /dev/null +++ b/asciidoc.conf @@ -0,0 +1,18 @@ +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +Git Bz + +Git Bz Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/git-bz b/git-bz index 6a9315d..c76757d 100755 --- a/git-bz +++ b/git-bz @@ -26,207 +26,10 @@ # ============ # Copy or symlink somewhere in your path. # -# Usage -# ===== -# -# git bz add-url [options] [ | ] -# -# For each specified commit, rewrite the commit message to add a reference -# to the given bug. You should only do this if you haven't already pushed -# the commit publically. You won't need this very often, since -# 'git bz file' and 'git bz attach' do this automaticlaly. -# -# If the bug number is already found in the commit message, then does nothing. -# -# Example: -# -# # Add a bug URL to the last commit -# git bz attach 1234 HEAD -# -# The default behavior is to append the bug URL to the commit body. See the -# section 'Add URL Method' below for how to change this. -# -# git bz apply [options] -# -# For each patch attachment (except for obsolete patches) of the specified -# bug, prompts whether to apply. If prompt is agreed to runs 'git am' on -# the patch to apply it to the current branch. Aborts if 'git am' fails to -# allow cleaning up conflicts. -# -# Examples: -# -# # Apply patches from the given bug -# git bz apply bugzillla.gnome.org:1234 -# -# # Same, but add the bug URL to the commit messages -# git bz apply -u bugzillla.gnome.org:1234 -# -# git bz attach [options] [ | ] -# -# For each specified commit, formats as a patch and attaches to the -# specified bug, with the subject of the commit as the description and -# the body of the commit as the comment. The patch formatting is as -# for 'git format-patch'. Unlike 'git format-patch', specifying a single -# commit means just that commit, not everything after that commit. -# -# Prompts before actually doing anything to avoid mistakes. -# -# If -e/--edit is specified, then the user can edit the description and -# comment for each patch, and (by uncommenting lines) obsolete old patches. -# -# The commit message will automatically be rewritten to include a reference -# to the bug (see 'git bz add-url'). This can be suppressed with the -# -n/--no-add-url option. -# -# Examples: -# -# # Attach the last commit -# git bz attach bugzilla.gnome.org:1234 HEAD -# -# # Attach everything starting at an old commit -# git bz attach bugzilla.gnome.org:1234 b50ea9bd^.. -# -# git bz edit [ | | ] -# -# Allows doing common operations on a Bugzilla bug without going to -# your web browser. An editable buffer is brought up in a git-like -# fashion, where you can add comments, resolve a bug, and change -# the status of patches. -# -# If the argument identifies a commit or commits rather than a bug -# then each bug referred to in the commits is edited in turn. -# -# If -p/--pushed is specified, then git-bz will attempt to automatically -# determine the correct comments, attachment changes, and resolution -# for the bug from applying the specified commits to the project's -# official repository. You'll have a chance to edit these changes and -# add additional comments. See 'git bz push' for a convenient interface -# to push commits and do this at the same time. -# -# git bz file [options] [[]/] [ | ] -# -# Like 'attach', but files a new bug. Opens an editor for the user to -# enter the summary and description for the bug. If only a single commit -# is named, the summary defaults to the subject of the commit. The product and -# component must be specified unless you have configured defaults. -# -# The commit message will automatically be rewritten to include a reference to -# the newly filed bug (see 'git bz add-url') before attaching the patch. This -# can be suppressed with the -n/--no-add-url option. -# -# Examples: -# -# # File the last commit as a new bug on the default tracker -# git bz file my-product/some-component HEAD -# -# # File a bug with a series of patches starting from an old commit -# # on a different bug tracker -# git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^.. -# -# git bz push [options] [ ...] -# -# Exactly like 'git push', but 'git bz edit --pushed' is done for each -# bug referenced in the newly pushed commits. -# -# Note that "newly pushed commits" are commits that were added to any -# existing branch by the push. Commits don't have to be pushed to master -# to be considered newly pushed. However, commits pushed to on newly -# created branches will be ignored. -# -# Authentication -# ============== -# In order to use git-bz you need to already be logged into the bug tracker -# in your web browser, and git-bz reads your browser cookie. Currently only -# Firefox 3 and Epiphany are supported, and only on Linux. Patches to -# add more support and to allow configuring username/password directly -# per bug tracker accepted. -# -# Bug references -# ============== -# Ways to refer to a bug: -# : bug # on the default bug tracker -# : : bug # on the given host -# : : bug # on the given bug tracker alias (see below) -# : An URL of the form http:///show_bug.cgi?id= -# -# Add URL Method -# ============== -# You can configure 'git bz add-url', and the --add-url option of 'git -# bz [apply|attach|file]' to add the URL different ways or to add a -# non-URL bug reference, using the git config variable -# 'bz.add-url-method'. -# -# It has the form -# -# : -# -# Method is: -# subject-prepend - prepend to the subject (separated with a space) -# subject-append - apend to the subject (separated with a space) -# body-prepend - prepend to the body (separated with a blank line) -# body-append - append to the body (separated with a blank line) -# -# Format supports the following escapes: -# %u - the bug URL -# %d - the bug # -# %n - a newline -# %% - a percent -# -# Examples: -# # The default -# git config bz.add-url-method body-append:%u -# # 'Bug 34323 - Speed up frobnification' -# git config bz.add-url-method subject-prepend:Bug %d - -# -# Aliases -# ======= -# You can create short aliases for different bug trackers as follows -# -# git config --global bz-tracker.gnome.host bugzilla.gnome.org -# -# And you can set the default bug tracker with: -# -# git config --global bz.default-tracker gnome -# -# Per-Repository configuration -# ============================ -# Setting the default tracker, product and component in the local -# config for a repository is useful. Assuming that a global -# 'gnome' alias has been set up as above: -# -# git config bz.default-tracker gnome -# git config bz.default-product gnome-shell -# git config bz.default-component general -# -# Note the absence of --global; configuring a default product and component -# globally is seldom useful. -# -# Per-Tracker Configuration -# ========================= -# git-bz needs some configuration specific to the bugzilla instance (tracker), -# in particular it needs to know initial field values to use when submitting -# bugs; legal values for some fields depend on the instance. -# -# You can also set whether to use http or https by setting the 'https' variabe -# For https, *certificates are not checked* so you are completely vulnerable -# to DNS spoofing and man-in-the-middle attacks. Blame httplib. -# -# Configuration comes from 4 sources, in descending order of priority -# -# 1) git configuration variables specified for the alias. -# -# git config --global bz-tracker.gnome.default-severity trivial -# -# 2) git configuration variables specified for the host -# -# git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial -# -# 3) Host specific configuration in this file, see the CONFIG variable below -# -# 4) Default configuration in this file, see the DEFAULT_CONFIG variable below -# -# In general, settings that are necessary to make a popular bugzilla instance -# work should be submitted back to me and go in the CONFIG variable. +# Documentation +# ============= +# See http://git.fishsoup.net/man/git-bz.html +# (generated from git-bz.txt in this directory.) # DEFAULT_CONFIG = \ """ diff --git a/git-bz.txt b/git-bz.txt new file mode 100644 index 0000000..3db24e8 --- /dev/null +++ b/git-bz.txt @@ -0,0 +1,358 @@ +git-bz(1) +========= + +NAME +---- +git-bz - Command line integration of git with Bugzilla + +SYNOPSIS +-------- +[verse] +'git bz add-url' ( | ) +'git bz apply' [-n | --no-add-url] +'git bz attach' [-n | --no-add-url] [-e |--edit] [] ( | ) +'git bz edit' ( | | ) +'git bz edit' --pushed ( | ) +'git bz file' [-n | --no-add-url] [[]/] ( | ) +'git bz push' [ ...] + +DESCRIPTION +------------ + +git-bz is a tool for integrating the Git command line with the +Bugzilla bug-tracking system. Operations such as attaching patches to bugs, +applying patches in bugs to your current tree, and closing bugs once +you've pushed the fixes publically can be done completely from the +command line without having to go to your web browser. + +Authentication for git-bz is done by reading the cookies for the +Bugzilla host from your web browser. In order to do this, git-bz needs +to know how to access the cookies for your web browser; git-bz +currently is able to do this for Firefox, Epiphany, and Chromium on +Linux. + +EXAMPLE SESSION +--------------- + +Before getting started, you configure the default Bugzilla instance, product and +component for your repository: + +---------------------------------------- +git config bz.default-tracker bugzilla.example.com +git config bz.default-product TiddlyWinks +git config bz.default-component AI-Engine +---------------------------------------- + +Someone has found a bug in your code, and filed bug 43215 in +bugzilla.example.com. You've come up with a fix for that patch +locally, but you want the bug reporter to test it, so you attach the change +you made locally to the bug report as a patch: + +---------------------------------------- +git bz attach 43215 HEAD +---------------------------------------- + +This automatically rewrites the commit to add the URL of the bug to the commit for +future reference. The reporter finds some problems in testing, so you come up +with a new up with a new version of the change and modify your commit using +'git command --amend'. To attach the new version, you run: + +---------------------------------------- +git bz attach -e HEAD +---------------------------------------- + +You don't have to specify the bug number this time since git-bz will +find it it in the bug. The -e option (short for --edit) allows you to +edit the comment for the bug to say what you've changed and pick +patches to obsolete. Now everybody's happy with the change. To push +your changes and close the bug, you run: + +---------------------------------------- +git bz push +---------------------------------------- + +This does 'git bz push', adds a comment that the commits were pushed and +marks the patches committed. The changes it is making to the bug will be +shown in your editor to give you a chance to confirm them and add +extra comments if desired. + +Other useful commands are 'git bz file' to file a new bug rather than +attaching patches to an existing one, 'git bz apply' to apply patches from +a bug to the current tree, and 'git bz edit' to add comments to or +close bug reports. + +COMMON OPTIONS +-------------- + +-b;; +--bugzilla;; + Bug tracker to use. Used for 'git bz file' and to resolve bug references. + Generally, it's more useful to configure this with 'git config' instead. + See the section <>. + +-u;; +--add-url;; + Rewrite commits to add the bug URL. (This is the default and will not normally + need to be specified.) + +-n;; +--no-add-url;; + Don't rewrite commits to add the bug URL + +COMMANDS +-------- + +add-url +~~~~~~~ + +'git bz add-url' ( | ) + +For each specified commit, rewrite the commit message to add a +reference to the given bug. You should only do this if you haven't +already pushed the commit publically. You won't need this very often, +since 'git bz file' and 'git bz attach' do this automatically. It +might be useful if you want to record the bug information but don't +want to attach it immediately. + +If the bug number is already found in the commit message, then does nothing. + +Example: + +---------------------------------------- +# Add a bug URL to the last commit +git bz attach 1234 HEAD +---------------------------------------- + +The default behavior is to append the bug URL to the commit body. See the +section <> below for how to change this. + +apply +~~~~~ + +'git bz apply' [-n | --no-add-url] + +For each patch attachment (except for obsolete patches) of the specified +bug, prompts whether to apply. If prompt is agreed to runs 'git am' on +the patch to apply it to the current branch. Aborts if 'git am' fails to +allow cleaning up conflicts. + +Examples: + +---------------------------------------- +# Apply patches from the given bug +git bz apply bugzillla.gnome.org:1234 +---------------------------------------- + +The commit messages will automatically be rewritten to include a +reference to the bug (see 'git bz add-url'). This can be suppressed +with the -n/--no-add-url option. + +attach +~~~~~~ + +'git bz attach' [-n | --no-add-url] [-e |--edit] [ | ] + +For each specified commit, formats as a patch and attaches to the +specified bug, with the subject of the commit as the description and +the body of the commit as the comment. The patch formatting is as +for 'git format-patch'. Unlike 'git format-patch', specifying a single +commit means just that commit, not everything after that commit. + +Prompts before actually doing anything to avoid mistakes. + +The commit message will automatically be rewritten to include a reference +to the bug (see 'git bz add-url'). This can be suppressed with the +-n/--no-add-url option. + +-e;; +--edit;; + allow the user to edit the description and comment for each patch, + and (by uncommenting lines) obsolete old patches. + +Examples: +---------------------------------------- +# Attach the last commit +git bz attach bugzilla.gnome.org:1234 HEAD + +# Attach everything starting at an old commit +git bz attach bugzilla.gnome.org:1234 b50ea9bd^.. +---------------------------------------- + +edit +~~~~ + +'git bz edit' ( | | ) +'git bz edit' --pushed ( | ) + +Allows doing common operations on a Bugzilla bug without going to +your web browser. An editable buffer is brought up in a git-like +fashion, where you can add comments, resolve a bug, and change +the status of patches. + +If the argument identifies a commit or commits rather than a bug +then each bug referred to in the commits is edited in turn. + +-p;; +--pushed;; + Attempt to automatically determine the correct comments, attachment + changes, and resolution for the bug from applying the specified commits + to the project's official repository. You'll have a chance to edit these + changes and add additional comments. See 'git bz push' for a convenient + interface to push commits and do this at the same time. + +file +~~~~ + +'git bz file' [-n | --no-add-url] [[]/] ( | ) + +Like 'attach', but files a new bug. Opens an editor for the user to +enter the summary and description for the bug. If only a single commit +is named, the summary defaults to the subject of the commit. The product and +component must be specified unless you have configured defaults. + +The commit message will automatically be rewritten to include a reference to +the newly filed bug (see 'git bz add-url') before attaching the patch. This +can be suppressed with the -n/--no-add-url option. + +Examples: + +---------------------------------------- +# File the last commit as a new bug on the default tracker +git bz file my-product/some-component HEAD + +# File a bug with a series of patches starting from an old commit +# on a different bug tracker +git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^.. +---------------------------------------- + +push +~~~~ + +'git bz push' [ ...] + +Exactly like 'git push', but 'git bz edit --pushed' is done for each +bug referenced in the newly pushed commits. + +Note that ``newly pushed commit'' are commits that were added to any +existing branch by the push. Commits don't have to be pushed to master +to be considered newly pushed. However, commits pushed to on newly +created branches will be ignored. + +AUTHENTICATION +-------------- +In order to use git-bz you need to already be logged into the bug tracker +in your web browser, and git-bz reads your browser cookie. Currently only +Firefox 3 and Epiphany are supported, and only on Linux. Patches to +add more support and to allow configuring username/password directly +per bug tracker accepted. + +BUG REFERENCES +-------------- +Ways to refer to a bug: + +:: bug # on the default bug tracker + +::: bug # on the given host + +::: bug # on the given bug tracker alias (see below) + +:: An URL of the form http:///show_bug.cgi?id- + +[[add-url-method]] +ADD URL METHOD +-------------- +You can configure 'git bz add-url', and the --add-url option of 'git +bz [apply|attach|file]' to add the URL different ways or to add a +non-URL bug reference, using the git config variable ++bz.add-url-method+. + +It has the form + + : + +Method is: + +subject-prepend:: prepend to the subject (separated with a space) +subject-append:: append to the subject (separated with a space) +body-prepend:: prepend to the body (separated with a blank line) +body-append:: append to the body (separated with a blank line) + +Format supports the following escapes: + +%u:: the bug URL +%d:: the bug # +%n:: a newline +%%:: a percent + +---------------------------------------- +# The default +git config bz.add-url-method body-append:%u +# 'Bug 34323 - Speed up frobnification' +git config bz.add-url-method subject-prepend:Bug %d - +---------------------------------------- + +ALIASES +------- +You can create short aliases for different bug trackers as follows + +---------------------------------------- +git config --global bz-tracker.gnome.host bugzilla.gnome.org +---------------------------------------- + +And you can set the default bug tracker with: + +---------------------------------------- +git config --global bz.default-tracker gnome +---------------------------------------- + +[[per-repository-configuration]] +PER-REPOSITORY CONFIGURATION +---------------------------- +Setting the default tracker, product and component in the local +config for a repository is useful. Assuming that a global +'gnome' alias has been set up as above: + +---------------------------------------- +git config bz.default-tracker gnome +git config bz.default-product gnome-shell +git config bz.default-component general +---------------------------------------- + +Note the absence of --global; configuring a default product and component +globally is seldom useful. + +PER-TRACKER CONFIGURATION +------------------------- +git-bz needs some configuration specific to the bugzilla instance (tracker), +in particular it needs to know initial field values to use when submitting +bugs; legal values for some fields depend on the instance. + +You can also set whether to use http or https by setting the 'https' variabe +For https, *certificates are not checked* so you are completely vulnerable +to DNS spoofing and man-in-the-middle attacks. Blame httplib. + +Configuration comes from 4 sources, in descending order of priority + +1. git configuration variables specified for the alias. ++ +---------------------------------------- +git config --global bz-tracker.gnome.default-severity trivial +---------------------------------------- ++ +2. git configuration variables specified for the host ++ +---------------------------------------- +git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial +---------------------------------------- ++ +3. Host specific configuration in the git-bz script, see the CONFIG variable. ++ +4. Default configuration in the git-bz script, see the DEFAULT_CONFIG variable. + +In general, settings that are necessary to make a popular bugzilla instance +work should be submitted back to me and go in the CONFIG variable. + +Author +------ +Written by Owen Taylor . + -- cgit v1.2.3