[Summary view] [Print] [Text view]

   1  @title Diffusion User Guide: Commit Hooks
   2  @group userguide
   3  
   4  Guide to commit hooks in hosted repositories.
   5  
   6  = Overview =
   7  
   8  Phabricator installs pre-receive/pre-commit hooks in hosted repositories
   9  automatically. They enforce a few rules automatically (like preventing
  10  dangerous changes unless a repository is configured to allow them). They can
  11  also enforce more complex rules via Herald, using the "Commit Hook:
  12  Branches/Tags/Bookmarks" and "Commit Hook: Commit Content" rule types.
  13  
  14  Herald rules are flexible, and can express many of the most common hooks that
  15  are often installed on repositories (like protecting branches, restricting
  16  access to repositories, and requiring review).
  17  
  18  However, if Herald isn't powerful enough to enforce everything you want to
  19  check, you can install additional custom hooks. These work mostly like normal
  20  hooks, but with a few differences.
  21  
  22  = Installing Custom Hooks =
  23  
  24  With hosted repositories, you can install hooks by dropping them into the
  25  relevant directory of the repository on disk:
  26  
  27    - **SVN** Put hooks in `hooks/pre-commit-phabricator.d/`.
  28    - **Git** Put hooks in `hooks/pre-receive-phabricator.d/`.
  29    - **Mercurial** Phabricator does not currently support custom hooks in
  30      Mercurial.
  31  
  32  These hooks act like normal `pre-commit` or `pre-receive` hooks:
  33  
  34    - Executables in these directories will be run one at a time, in alphabetical
  35      order.
  36    - They'll be passed the arguments and environment that normal hooks are
  37      passed.
  38    - They should emit output and return codes like normal hooks do.
  39    - These hooks will run only after all the Herald rules have passed and
  40      Phabricator is otherwise ready to accept the commit or push.
  41  
  42  These additional variables will be available in the environment, in addition
  43  to the variables the VCS normally provides:
  44  
  45    - `PHABRICATOR_REPOSITORY` The callsign of the repository the hook is
  46      executing for.
  47    - `PHABRICATOR_USER` The Phabricator username that the session is
  48      authenticated under.
  49    - `PHABRICATOR_REMOTE_ADDRESS` The connection's remote address (that is,
  50      the IP address of whoever is pushing or committing).
  51    - `PHABRICATOR_REMOTE_PROTOCOL` The protocol the connection is using (for
  52      example, "ssh" or "http").