Ubuntu Manpage: git-notifier - script to be used with git as a post-receive hook

NAME

       git-notifier - script to be used with git as a post-receive hook

SYNOPSIS

       git-notifier [options]

DESCRIPTION

       git-notifier  is  a  script to be used with git as a post-receive hook. Once installed, it
       emails out a summary of all changes each time a user pushes an update to  the  repository.
       Different  from  other  similar  scripts, git-notifier sends exactly one email per change,
       each of which includes a complete diff of all modifications as well as the set of branches
       from  which  the  new revision can be reached. The scripts ensure that that each change is
       mailed out only exactly once by keeping a state file of already reported revisions.

       In addition, git-notifier also mails updates when branches or annotated tags  are  created
       or  removed;  and  it  furthermore mails a revision summary if a head moves to now include
       commits already reported previously (e.g., on fast-forwards).

       If a commit message contains [nodiff], the generated mail will not include a  diff.  If  a
       commit message contains [nomail], no mail will be send for that change.

       git-notifier supports the options below. Alternatively to giving them on the command line,
       all of them can alse be set via git config hooks.<option>. For example, to set a recipient
       address, do git config hooks.mailinglist git-updates@foo.com.

       For full documentation, see the homepage at: http://www.icir.org/robin/git-notifier/.

INSTALLATION

       The basic installation is simple: just run the script from hooks/post-receive, as in:

       #!/bin/sh

       /full/path/to/git-notifier

       By default, the script will send its mails to the user running the git-notifier (i.e., the
       one doing the update). As that's usually not the desired recipient, an  alternative  email
       address  can  be  specified  via  command  line or git options, see the mailinglist option
       below.

OPTIONS

--allchanges <branches>
Lists <branches> for which all changes made to them should be mailed out as
straight diffs to their previous state, independent of whether the corresponding
commit has already been reported in the past. For merge commits, the mails include
the full diff (i.e., git's diff -m). This might for example make sense for master
if one wants to closely track any modification applied.

<branches> is a list of comma-separated names of heads to treat this way.

--branches <branches>
Lists <branches> to include/exclude in reporting. By default, all branches are
included. If this option is specified, only branches listed are included.
Alternatively, one can prefix a branch with - to exclude it: then all but the
excluded ones are reported.

<branches> is a list of comma-separated names of heads to treat this way.

--config=PATH
PATH to alternative configuration file.

--debug
Run the script in debug mode, which means that it will (1) log more verbosely and
to stderr, and (2) run git-notifier with the --debug and --noupdate options.

--diff [rev1...] rev2
Mails out diffs between all revisions on the first parent's way from rev1 to rev2.
This option produces output similar to that of a head moving forward which is
listed with --allchanges. If rev1 is skipped, rev2~1 is assumed.

This option is primarily for debugging and retropective (re-)generation of this
outut, and does not change the current notifier state in any way. The main
difference to --manual is that it considers only revision on the first parent's
path, and mails out actual diffs between these.

--emailprefix
Specifies a prefix for the mails' subject line. If the prefix contain an %r, that
will be replace with the repositories name. Default is [git/%r]. Note that the name
of this option is compatible with some of other git notification scripts.

--hostname <name>
Defines the hostname to use when building the repository path shown in the
notification mails. Default is the canonical name of the system the script is
running on.

--ignoreremotes
If given, git-notifier will not report any commits that are already known by any
configured remote repository.

--gitbasedir=DIRECTORY
Specifies a base DIRECTORY for the git repository. If not given, the current
directory is the default.

-h, --help
show help message and exit

--link <url>
Specifies a <url> that will be included into notification mails for locating a
changeset online. The <url> can contain a %s placeholder that will be replaced with
the corresponding git revision number. The <url> can also contain an %r placeholder
that will be replaced with the name of the repository.

--log <file>
Write logging information into the given <file>. Default is git-notifier.log inside
the repository.

--mailcmd <command>
Specifies the command to use for sending mail. Default is /usr/sbin/sendmail.

--mailinglist <address>
Specifies the recipient for all generated mails. Default is mailing to the system
account that is running the script.

--mailserver <host>
SMTP server to use for outgoing mails. Default is None, in which case mail gets
sent through the local sendmail (or whatever --mailcmd defines alternatively).

--mailsubjectlen <max>
Limits subjects of generated mails to <max> characters. Default os no limit.

--manual [rev1..] rev2
Mails out notifications for all revisions on the way from rev1 to rev2. If rev1 is
skipped, rev2~1 is assumed.

This option is primarily for debugging and retropective (re-)generation of this
output, and does not change the current notifier state in any way.

--maxage <days>
Limits the age of commits to report. No commit older than this many days will
trigger a commit notification. Default is 30 days; zero disables the age check.

--maxdiffsize <size>
Limits the <size>of mails by giving a maximum number of kilobytes that a diff may
have. If the diff for a change is larger than this value, a notification mail is
still send out but the diff is excluded (and replaced with a note saying so).
Default is 50K.

--mergediffs <branches>
Lists <branches> for which merges should include the full diff, including all
changes that are already part of branch commits.

<branches> is a list of command-separated names of heads to treat this way.

--noupdate
Does not update the internal state file, meaning that any updates will be reported
again next time the script is run.

--replyto <email>
Adds a Reply-To: <email> header to outgoing mails.

--repouri=URI
full URI for the repository

--sender <address>
Defines the sender <address> for all generated mails. Default is the user doing the
update (if gitolite is used, that's the gitolite acccount doing the push, not the
system account running git-notifier.)

--update-only
Does not send out any mail notifications but still updates the index. In other
words, all recent changes will be marked as "seen", without reporting them.

--users <file>
This is only for installations using gitolite <XXX>, for which the default sender
address for all mails would normally be the gitolite user account name of the
person doing the push. With this option, one can alternatively specify a file that
maps such account names to alternative addresses, which will then be used as the
sender for mails.

Note that even if --users is not given, git-notifier will still look for such a
file in ../conf/sender.cfg, relative to the top-level repository directory. In
other words, you can check a file sender.cfg containing the mappings into
gitolite's config/ directory and it should Just Work.

--version
Shows program's version number and exit

FILES

       git-notifier.conf

              This  is  the  git-notifier  configuration file, which provides system-wide default
              configuration values. Configuration  data  is  taken  in  the  following  order  of
              precedence:

              1. command-line options

              2. repository-specific configuration (via git config hooks.<option>)

              3. this file

              In  the default configuration file shipped with git-notifier, options are specified
              with their default value  where  possible,  but  are  left  commented.  Uncommented
              options override the default value.

       ../conf/sender.cfg

              This  is  only for installations using gitolite <XXX>, for which the default sender
              address for all mails would normally be the  gitolite  user  account  name  of  the
              person doing the push.

              The  file  must  consist of line of the form <gitolite-user> <sender>, where sender
              will be used for the mails and can include spaces. Empty lines and  lines  starting
              with  #  are  ignored.  It's  ok if for a user no entry is found, in which case the
              default value will be used.

              For example, if there's a gitolite user account "joe", one could  provide  a  users
              file like this:

              joe Joe Smith <joe@foo.bar>

              Now all mails triggered by Joe will have the specified sender.

BUGS

       Report bugs on https://github.com/rsmmr/git-notifier/issues

LICENSE

       git-notifier comes with a BSD-style license.

AUTHOR

       Robin    Sommer    <robin@icir.org>.   This   manpage   is   written   by   Lev   Lamberov
       <l.lamberov@gmail.com>.

                                                                                  GIT-NOTIFIER(1)