[thirdparty/git.git] / contrib / ciabot / INSTALL

= Installation instructions =

Two scripts are included.  The Python one (ciabot.py) is faster and
more capable; the shell one (ciabot.sh) is a fallback in case Python
gives your git hosting site indigestion. (I know of no such sites.)

It is no longer necessary to modify the script in order to put it
in place; in fact, this is now discouraged. It is entirely
configurable with the following git config variables:

ciabot.project = name of the project
ciabot.repo = name of the project repo for gitweb/cgit purposes
ciabot.xmlrpc  = if true, ship notifications via XML-RPC
ciabot.revformat = format in which the revision is shown

The revformat variable may have the following values
raw -> full hex ID of commit
short -> first 12 chars of hex ID
describe -> describe relative to last tag, falling back to short

ciabot.project defaults to the directory name of the repository toplevel.
ciabot.repo defaults to ciabot.project lowercased.
ciabot.xmlrpc defaults to True
ciabot.revformat defaults to 'describe'.

This means that in the normal case you need not do any configuration at all,
however setting ciabot.project will allow the hook to run slightly faster.

Once you've set these variables, try your script with -n to see the
notification message dumped to stdout and verify that it looks sane.

To live-test these scripts, your project needs to have been registered with
the CIA site.  Here are the steps:

1. Open an IRC window on irc://freenode/commits or your registered
   project IRC channel.

2. Run ciabot.py and/or ciabot.sh from any directory under git
   control.

You should see a notification on the channel for your most recent commit.

After verifying correct function, install one of these scripts either
in a post-commit hook or in an update hook.

In post-commit, run it without arguments. It will query for
current HEAD and the latest commit ID to get the information it
needs.

In update, call it with a refname followed by a list of commits:
You want to reverse the order git rev-list emits because it lists
from most recent to oldest.

/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
Commit	Line	Data
64840701 ER	1	= Installation instructions =
	2
	3	Two scripts are included. The Python one (ciabot.py) is faster and
	4	more capable; the shell one (ciabot.sh) is a fallback in case Python
	5	gives your git hosting site indigestion. (I know of no such sites.)
	6
	7	It is no longer necessary to modify the script in order to put it
	8	in place; in fact, this is now discouraged. It is entirely
	9	configurable with the following git config variables:
	10
df1effa6	11	ciabot.project = name of the project
64840701	12	ciabot.repo = name of the project repo for gitweb/cgit purposes
df1effa6	13	ciabot.xmlrpc = if true, ship notifications via XML-RPC
64840701 ER	14	ciabot.revformat = format in which the revision is shown
64840701 ER	15
64840701 ER	16	The revformat variable may have the following values
	17	raw -> full hex ID of commit
	18	short -> first 12 chars of hex ID
	19	describe -> describe relative to last tag, falling back to short
df1effa6 ER	20
	21	ciabot.project defaults to the directory name of the repository toplevel.
	22	ciabot.repo defaults to ciabot.project lowercased.
	23	ciabot.xmlrpc defaults to True
	24	ciabot.revformat defaults to 'describe'.
	25
	26	This means that in the normal case you need not do any configuration at all,
	27	however setting ciabot.project will allow the hook to run slightly faster.
64840701 ER	28
	29	Once you've set these variables, try your script with -n to see the
	30	notification message dumped to stdout and verify that it looks sane.
	31
df1effa6 ER	32	To live-test these scripts, your project needs to have been registered with
	33	the CIA site. Here are the steps:
	34
	35	1. Open an IRC window on irc://freenode/commits or your registered
	36	project IRC channel.
	37
	38	2. Run ciabot.py and/or ciabot.sh from any directory under git
	39	control.
	40
	41	You should see a notification on the channel for your most recent commit.
	42
64840701 ER	43	After verifying correct function, install one of these scripts either
	44	in a post-commit hook or in an update hook.
	45
	46	In post-commit, run it without arguments. It will query for
	47	current HEAD and the latest commit ID to get the information it
	48	needs.
	49
	50	In update, call it with a refname followed by a list of commits:
	51	You want to reverse the order git rev-list emits because it lists
	52	from most recent to oldest.
	53
	54	/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} \| tac)