← 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: Robert Collins
  • Date: 2006-07-20 13:00:31 UTC
  • mto: (1852.9.1 Tree.compare().)
  • mto: This revision was merged to the branch mainline in revision 1890.
  • Revision ID: robertc@robertcollins.net-20060720130031-d26103a427ea10f3
Start tree implementation tests.

Show diffs side-by-side

added added

removed removed

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