← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/setting_up_email.txt

  • Committer: Ian Clatworthy
  • Date: 2007-06-06 11:51:37 UTC
  • mto: This revision was merged to the branch mainline in revision 2527.
  • Revision ID: ian.clatworthy@internode.on.net-20070606115137-iq6sk13d8p356bo8
explicit format saving test

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/setting_up_email.txt
 
1
================
 
2
Setting up email
 
3
================
 
4
 
 
5
Description of the various ways to specify to Bazaar your email address for
 
6
commits.
 
7
 
 
8
Why set up an email address with Bazaar?
 
9
========================================
 
10
Bazaar stores the specified email address in revisions when they're
 
11
created so that people can tell who commited which revisions.  The
 
12
email addresses are not verified, therefore they could be bogus, so
 
13
you have to trust the people involved in your project.  Additionally,
 
14
the email address in a revision gives others a way to contact the
 
15
author of a revision for credit and/or blame.  :)
 
16
 
 
17
How to set up your email address 
 
18
================================
 
19
Bazaar will try to guess an email address based on your username and the
 
20
hostname if none is set.  This will probably not be what you want, so three
 
21
ways exist to tell Bazaar what email to use:
 
22
 
 
23
You can set your email in one of several configuration files.  Like
 
24
other configuration values, you can set it in ``bazaar.conf`` as a
 
25
general setting.  If you want to override the value for a particular
 
26
branch, or set of branches, you can use ``locations.conf``.
 
27
``.bzr/branch/branch.conf`` will also work, but will cause all commits
 
28
to that branch to use the same email address, even if someone else
 
29
does them.
 
30
 
 
31
The order of precedence is
 
32
 
 
33
 1. If the ``$BZR_EMAIL`` environment variable is set.
 
34
 #. If an email is set for your current branch in the ``locations.conf``
 
35
    file.
 
36
 #. If an email is set four your current branch in the
 
37
    ``.bzr/branch/branch.conf`` file.
 
38
 #. If an email is set in the ``bazaar.conf`` default configuration file.
 
39
 #. If the `$EMAIL` environment variable is set.
 
40
 #. Bazaar will try to guess based on your username and the hostname.
 
41
 
 
42
To check on what Bazaar thinks your current email is, use the ``whoami``
 
43
("who am i?") command::
 
44
 
 
45
    % bzr whoami
 
46
    Joe Cool <joe@example.com>
 
47
    
 
48
Setting email via the 'whoami' command
 
49
======================================
 
50
You can use the whoami command to set your email globally::
 
51
 
 
52
    % bzr whoami 'Joe Cool <joe@example.com>'
 
53
 
 
54
or only for the current branch::
 
55
 
 
56
    % bzr whoami --branch 'Joe Cool <joe@example.com>'
 
57
 
 
58
These modify your global ``bazaar.conf`` or branch ``branch.conf`` file, respectively.
 
59
 
 
60
Setting email via default configuration file
 
61
============================================
 
62
To use the default ini file, create the file ``$HOME/.bazaar/bazaar.conf`` (on
 
63
Windows this is ``%APPDATA%\bazaar\2.0\bazaar.conf``) and set an email address
 
64
as shown below.  Please note that the word DEFAULT is case sensitive, and
 
65
must be in upper-case.
 
66
::
 
67
 
 
68
    [DEFAULT]
 
69
    email=Your Name <name@isp.com>
 
70
 
 
71
 
 
72
For more information on the ini file format, see ConfiguringBzr.
 
73
 
 
74
Setting email on a per-branch basis
 
75
===================================
 
76
 
 
77
The second approach is to set email on a branch by branch basis by
 
78
using the ``$HOME/.bazaar/locations.conf`` configuration file,
 
79
thusly::
 
80
 
 
81
    [/some/branch/location]
 
82
    email=Your Name <name@other-isp.com>
 
83
 
 
84
This will set your email address in the branch at ``/some/branch/location``,
 
85
overriding the default specified in the ``bazaar.conf`` above.
 
86
 
 
87
Setting email via environment variable
 
88
--------------------------------------
 
89
The final method Bazaar will use is checking for the ``$BZR_EMAIL``
 
90
and ``$EMAIL`` environment variables.  Generally, you would use this
 
91
method to override the email in a script context.  If you would like
 
92
to set a general default, then please see the ini methods above.
 
93
 
 
94
Concerns about spam
 
95
===================
 
96
Some people want to avoid sharing their email address so as not to get
 
97
spam.  Bazaar will never disclose your email address, unless you publish
 
98
a branch or changeset in a public location.  It's recommended that you
 
99
*do* use a real address, so that people can contact you about your work,
 
100
but it's not required.  You can use an address which is obfuscated, which
 
101
bounces, or which goes through an anti-spam service such as
 
102
`spamgourmet.com`.