Merge branch 'jc/submodule-anchor-git-dir' into maint
[git] / contrib / hooks / multimail / doc / troubleshooting.rst
1 Troubleshooting issues with git-multimail: a FAQ
2 ================================================
3
4 How to check that git-multimail is properly set up?
5 ---------------------------------------------------
6
7 Since version 1.4.0, git-multimail allows a simple self-checking of
8 its configuration: run it with the environment variable
9 ``GIT_MULTIMAIL_CHECK_SETUP`` set to a non-empty string. You should
10 get something like this::
11
12   $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
13   Environment values:
14       administrator : 'the administrator of this repository'
15       charset : 'utf-8'
16       emailprefix : '[git-multimail] '
17       fqdn : 'anie'
18       projectdesc : 'UNNAMED PROJECT'
19       pusher : 'moy'
20       repo_path : '/home/moy/dev/git-multimail'
21       repo_shortname : 'git-multimail'
22
23   Now, checking that git-multimail's standard input is properly set ...
24   Please type some text and then press Return
25   foo
26   You have just entered:
27   foo
28   git-multimail seems properly set up.
29
30 If you forgot to set an important variable, you may get instead::
31
32   $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
33   No email recipients configured!
34
35 Do not set ``$GIT_MULTIMAIL_CHECK_SETUP`` other than for testing your
36 configuration: it would disable the hook completely.
37
38 Git is not using the right address in the From/To/Reply-To field
39 ----------------------------------------------------------------
40
41 First, make sure that git-multimail actually uses what you think it is
42 using. A lot happens to your email (especially when posting to a
43 mailing-list) between the time `git_multimail.py` sends it and the
44 time it reaches your inbox.
45
46 A simple test (to do on a test repository, do not use in production as
47 it would disable email sending): change your post-receive hook to call
48 `git_multimail.py` with the `--stdout` option, and try to push to the
49 repository. You should see something like::
50
51   Counting objects: 3, done.
52   Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done.
53   Total 3 (delta 0), reused 0 (delta 0)
54   remote: Sending notification emails to: foo.bar@example.com
55   remote: ===========================================================================
56   remote: Date: Mon, 25 Apr 2016 18:39:59 +0200
57   remote: To: foo.bar@example.com
58   remote: Subject: [git] branch master updated: foo
59   remote: MIME-Version: 1.0
60   remote: Content-Type: text/plain; charset=utf-8
61   remote: Content-Transfer-Encoding: 8bit
62   remote: Message-ID: <20160425163959.2311.20498@anie>
63   remote: From: Auth Or <Foo.Bar@example.com>
64   remote: Reply-To: Auth Or <Foo.Bar@example.com>
65   remote: X-Git-Host: example
66   ...
67   remote: --
68   remote: To stop receiving notification emails like this one, please contact
69   remote: the administrator of this repository.
70   remote: ===========================================================================
71   To /path/to/repo
72      6278f04..e173f20  master -> master
73
74 Note: this does not include the sender (Return-Path: header), as it is
75 not part of the message content but passed to the mailer. Some mailer
76 show the ``Sender:`` field instead of the ``From:`` field (for
77 example, Zimbra Webmail shows ``From: <sender-field> on behalf of
78 <from-field>``).