Skip to content
Browse files

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.
  • Loading branch information...
1 parent 18e6fdc commit 170f40c2d1220e66c3084dafc135745357660956 @owtaylor owtaylor committed Sep 5, 2009
Showing with 396 additions and 201 deletions.
  1. +2 −0 .gitignore
  2. +14 −0 Makefile
  3. +18 −0 asciidoc.conf
  4. +4 −201 git-bz
  5. +358 −0 git-bz.txt
View
2 .gitignore
@@ -0,0 +1,2 @@
+git-bz.1
+git-bz.html
View
14 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
+
View
18 asciidoc.conf
@@ -0,0 +1,18 @@
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Git Bz</refmiscinfo>
+<refmiscinfo class="version"></refmiscinfo>
+<refmiscinfo class="manual">Git Bz Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
View
205 git-bz
@@ -26,207 +26,10 @@
# ============
# Copy or symlink somewhere in your path.
#
-# Usage
-# =====
-#
-# git bz add-url [options] <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 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] <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
-#
-# # Same, but add the bug URL to the commit messages
-# git bz apply -u bugzillla.gnome.org:1234
-#
-# git bz attach [options] <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.
-#
-# 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 [<bug reference> | <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.
-#
-# 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] [[<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^..
-#
-# git bz push [options] [<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 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:
-# <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
-# ==============
-# 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 - 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 = \
"""
View
358 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>.
+

0 comments on commit 170f40c

Please sign in to comment.
Something went wrong with that request. Please try again.