← 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: joe blow
  • Date: 2007-02-27 21:24:38 UTC
  • mto: (2293.1.5 bzr.dev)
  • mto: This revision was merged to the branch mainline in revision 2311.
  • Revision ID: joe@blow.com-20070227212438-ndpq6lsmn9ahroz5
Updated documents for grammer, spelling, and clarity.

Show diffs side-by-side

added added

removed removed

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