Permalink
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...
owtaylor committed Sep 5, 2009
1 parent 18e6fdc commit 170f40c2d1220e66c3084dafc135745357660956
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
@@ -0,0 +1,2 @@
+git-bz.1
+git-bz.html
View
@@ -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
@@ -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 = \
"""
Oops, something went wrong.

0 comments on commit 170f40c

Please sign in to comment.