c680696e40
Summary: Most binaries don't need hooks. Let's not require them. This might not be very long lived since Simon is working on removing lua hooks, but this was a trivial fix. Reviewed By: johansglock Differential Revision: D20140026 fbshipit-source-id: cc74b37459f63c5dd550c5779b72aa1d6531202c |
||
---|---|---|
.. | ||
content-stores/src | ||
hooks-tests/src | ||
src | ||
README.md |
Commit Hooks
This document explains how to author and configure commit hooks for Mononoke.
Overview
Two types of hooks are supported (note that both are pre-commit hooks):
PerChangeset
runs once per changeset.PerAddedOrModifiedFile
runs once per added or modified file per changeset.
Individual hooks are declared as follows in the server.toml
file that
contains the configuration for a repo:
[[hooks]]
# The name of your hook. Must be unique within this file.
name="my_hook"
# Path to the Lua script that implements your hook.
# Relative paths are resolved relative to the root of the config repo.
path="my_hook.lua"
# This must be either "PerChangeset" or "PerAddedOrModifiedFile".
hook_type="PerAddedOrModifiedFile"
# The following property is optional.
# If specified and there is a line in the commit message that matches
# the specified value, then the hook is not run for that commit.
bypass_commit_string="@ignore-conflict-markers"
# The following property is optional.
# If specified, the hook can be bypassed by specifying `--pushvars KEY=VALUE`
# when running `hg push`.
bypass_pushvar="KEY=VALUE"
Enabled hooks must be declared in [[bookmark.hooks]]
:
[[bookmarks.hooks]]
# Note how this matches the "name" property in [[hooks]].
hook_name="my_hook"
Here is an example of a hook to prevent Perl files from being checked in:
-- file my_hook.lua
function hook (ctx)
if ctx.file.path:match("\\.perl$") then
return false, "Boo: scary Perl!"
else
return true
end
Lua API
Your hook must be implemented in Lua. The entry point to your hook must be a
global function named hook()
. This function should return up to three
values:
success
(boolean
) This should betrue
if the hook was satisfied andfalse
if it was not. If this istrue
, thendescription
andlong_description
must benil
.description
(string
ornil
) If the hook was not satisfied, this must provide a short description of the failure, used to summarize this failure with other similar failures.long_description
(string
ornil
) If the hook was not satisfied, this should provide a long description of the failure with suggestions for how the user should approach fixing this hook failure. Mononoke will usedescription
if this is not provided, but this message needs to stand alone (description
is not automatically added to this message).
Here are some common properties of hooks:
The ctx
argument passed to the hook function always has at least the following
fields:
key | description |
---|---|
config_strings |
(table of string ) Contains string configs defined per repository config |
config_ints |
(table of int ) Contains int configs defined per repository config |
regex_match(regex, string) |
(function ) Returns a boolean indicating whether the string matches the supplied regex |
The type file
is a table with the following fields:
key | description |
---|---|
path |
(string ) Path to the file relative to the repo root. |
is_added() |
Returns a boolean indicating whether the file was added as part of the changeset |
is_deleted() |
Returns a boolean indicating whether the file was deleted as part of the changeset |
is_modified() |
Returns a boolean indicating whether the file was modified as part of the changeset |
len() |
Returns a number that is the length of the file in bytes. (Only present if is_deleted() returns false .) |
text() |
Returns a string containing the contents of the file, or nil if the file is binary or too large. (Only present if is_deleted() returns false .) |
path_regex_match(regex) |
Returns a boolean indicating whether the file's path matches the supplied regex |
PerChangeset
Your hook()
function receives a single ctx
argument, which is a table with
the following additional fields:
key | description |
---|---|
info |
(table ) Described below. |
files |
(table ) List of objects of type file , described above. |
file_text(path) |
(function ) Takes the relative path to a file in the repo and returns its contents, or nil if the file does not exist, is binary, or too large. |
parse_commit_msg() |
(function ) Returns a table with phabricator tags parsed. |
is_valid_reviewer(user) |
(function ) Returns whether a user can review the commit. |
ctx.info
is a table with the following fields:
key | description |
---|---|
author |
(string ) The author of the changeset. This should be something like "Stanislau Hlebik <stash@fb.com>" . |
comments |
(string ) The commit message. |
parent1_hash |
(string or nil ) p1 for the commit as a hex string, if it exists. |
parent2_hash |
(string or nil ) p2 for the commit as a hex string, if it exists. |
PerAddedOrModifiedFile
Your hook()
function receives a single ctx
argument, which is a table with
the following additional fields:
key | description |
---|---|
file |
(table ) Object of type file , described above. (Note is_deleted() will return false .) |