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.

1 files changed, 358 insertions, 0 deletions

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' <bug reference> (<commit> | <revision range>)
+'git bz apply' [-n | --no-add-url] <bug reference>
+'git bz attach' [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
+'git bz edit' (<bug reference> | <commit> | <revision range>)
+'git bz edit' --pushed (<commit> | <revision range>)
+'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
+'git bz push' [<repository> <refspec>...]
+
+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 <<per-repository-configuration, ``Per-Repository Configuration''>>.
+
+-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' <bug reference> (<commit> | <revision range>)
+
+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 <<add-url-method, ``Add URL Method''>> below for how to change this.
+
+apply
+~~~~~
+
+'git bz apply' [-n | --no-add-url] <bug reference>
+
+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] <bug reference> [<commit> | <revision range>]
+
+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' (<bug reference> | <commit> | <revision range>)
+'git bz edit' --pushed (<commit> | <revision range>)
+
+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] [[<product>]/<component>] (<commit> | <revision range>)
+
+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' [<repository> <refspec>...]
+
+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:
+
+<id>:: bug # on the default bug tracker
+
+<host>:<id>:: bug # on the given host
+
+<alias>:<id>:: bug # on the given bug tracker alias (see below)
+
+<url>:: An URL of the form http://<hostname>/show_bug.cgi?id-<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>:<format>
+
+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 <otaylor@fishsoup.net>.
+