/brz/remove-bazaar : revision 2977.1.7

1

Configuration reference

2

#######################

2

=======================

3

4

Information on how to configure Bazaar.

5

8

9

10

Environment variables

11

=====================

11

---------------------

12

13

While most configuration is handled by configuration files, some options

13

14

which may be semi-permanent can also be controlled through the environment.

14

15

16

BZR_EMAIL

16

---------

17

~~~~~~~~~

18

17

19

Override the email id used by Bazaar. Typical format::

18

20

19

21

"John Doe <jdoe@example.com>"

21

23

See also the ``email`` configuration value.

22

24

23

25

BZR_PROGRESS_BAR

24

----------------

26

~~~~~~~~~~~~~~~~

27

25

28

Override the progress display. Possible values are "none", "dots", "tty"

26

29

27

30

BZR_SIGQUIT_PDB

28

---------------

31

~~~~~~~~~~~~~~~

32

29

33

Control whether SIGQUIT behaves normally or invokes a breakin debugger.

30

34

0 = Standard SIGQUIT behavior

31

35

1 = Invoke breakin debugger (default)

32

36

33

37

BZR_HOME

34

--------

38

~~~~~~~~

39

35

40

Override the home directory used by Bazaar.

36

41

37

42

BZR_SSH

38

-------

43

~~~~~~~

44

39

45

Select a different SSH implementation.

40

46

41

47

BZR_PDB

42

-------

48

~~~~~~~

49

43

50

Control whether to launch a debugger on error.

44

51

0 = Standard behavior

45

52

1 = Launch debugger

46

53

47

54

BZR_REMOTE_PATH

48

---------------

55

~~~~~~~~~~~~~~~

56

49

57

Path to the Bazaar executable to use when using the bzr+ssh protocol.

50

58

51

59

See also the ``bzr_remote_path`` configuration value

52

60

53

61

BZR_EDITOR

54

----------

62

~~~~~~~~~~

63

55

64

Path to the editor Bazaar should use for commit messages, etc.

56

65

57

66

BZR_PLUGIN_PATH

58

---------------

67

~~~~~~~~~~~~~~~

68

59

69

The path to the plugins directory that Bazaar should use.

60

70

61

71

BZRPATH

62

-------

72

~~~~~~~

73

63

74

The path where Bazaar should look for shell plugin external commands.

64

75

65

76

66

77

Configuration files

67

===================

78

-------------------

68

79

69

80

Location

70

--------

81

~~~~~~~~

71

82

72

83

Configuration files are located in ``$HOME/.bazaar`` and are

73

84

sometimes referred to as ``ini files``:

87

98

can do so in ``locations.conf``.

88

99

89

100

General format

90

--------------

101

~~~~~~~~~~~~~~

91

102

92

103

An ini file has three types of contructs: section headers, section

93

104

variables and comments.

94

105

95

106

Comments

96

~~~~~~~~

107

^^^^^^^^

108

97

109

A comment is any line that starts with a "#" (sometimes called a "hash

98

110

mark", "pound sign" or "number sign"). Comment lines are ignored by

99

111

Bazaar when parsing ini files.

100

112

101

113

Section headers

102

~~~~~~~~~~~~~~~

114

^^^^^^^^^^^^^^^

115

103

116

A section header is a word enclosed in brackets that starts at the begining

104

117

of a line. A typical section header looks like this::

105

118

119

132

120

133

121

134

Section variables

122

~~~~~~~~~~~~~~~~~

135

^^^^^^^^^^^^^^^^^

123

136

124

137

A section variable resides within a section. A section variable contains a

125

138

variable name, an equals sign and a value. For example::

129

142

130

143

131

144

Variable policies

132

~~~~~~~~~~~~~~~~~

145

^^^^^^^^^^^^^^^^^

133

146

134

147

Variables defined in a section affect the named directory or URL plus

135

148

any locations they contain. Policies can be used to change how a

159

172

160

173

161

174

The main configuration file, bazaar.conf

162

----------------------------------------

175

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

163

176

164

177

The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one

165

178

section called ``[DEFAULT]``. This default section contains the default

176

189

177

190

178

191

The branch location configuration file, locations.conf

179

------------------------------------------------------

192

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

180

193

181

194

``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for

182

195

a specific branch. The format is almost identical to the default section in

195

208

check_signatures = require

196

209

197

210

The authentication configuration file, authentication.conf

198

----------------------------------------------------------

211

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

199

212

200

213

``$HOME/.bazaar/authentication.conf`` allows one to specify credentials for

201

214

remote servers. This can be used for all the supported transports and any part

210

223

.. _authentication configuration file documentation: authentication_conf.html

211

224

212

225

Common variable options

213

=======================

226

-----------------------

214

227

215

228

email

216

-----

229

~~~~~

230

217

231

The email address to use when committing a branch. Typically takes the form

218

232

of::

219

233

220

234

email = Full Name <account@hostname.tld>

221

235

222

236

editor

223

------

237

~~~~~~

238

224

239

The path of the editor that you wish to use if *bzr commit* is run without

225

240

a commit message. This setting is trumped by the environment variable

226

241

``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.

227

242

228

243

check_signatures

229

----------------

244

~~~~~~~~~~~~~~~~

245

230

246

Defines the behavior for signatures.

231

247

232

248

require

241

257

no signature is present.

242

258

243

259

create_signatures

244

-----------------

260

~~~~~~~~~~~~~~~~~

261

245

262

Defines the behaviour of signing revisions.

246

263

247

264

always

256

273

requires signatures.

257

274

258

275

recurse

259

-------

276

~~~~~~~

277

260

278

Only useful in ``locations.conf``. Defines whether or not the

261

279

configuration for this section applies to subdirectories:

262

280

268

286

branches below it.

269

287

270

288

gpg_signing_command

271

-------------------

289

~~~~~~~~~~~~~~~~~~~

290

272

291

(Default: "gpg"). Which program should be used to sign and check revisions.

273

292

For example::

274

293

275

294

gpg_signing_command = /usr/bin/gnpg

276

295

277

296

bzr_remote_path

278

---------------

297

~~~~~~~~~~~~~~~

298

279

299

(Default: "bzr"). The path to the command that should be used to run the smart

280

300

server for bzr. This value may only be specified in locations.conf, because:

281

301

286

306

It is overridden by the BZR_REMOTE_PATH environment variable.

287

307

288

308

smtp_server

289

-----------

309

~~~~~~~~~~~

310

290

311

(Default: "localhost"). SMTP server to use when Bazaar needs to send

291

312

email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.

292

313

293

314

smtp_username, smtp_password

294

----------------------------

315

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

316

295

317

User and password to authenticate to the SMTP server. If smtp_username

296

318

is set, and smtp_password is not, Bazaar will prompt for a password.

297

319

These settings are only needed if the SMTP server requires authentication

298

320

to send mail.

299

321

300

322

mail_client

301

-----------

323

~~~~~~~~~~~

324

302

325

A mail client to use for sending merge requests.

303

326

By default, bzr will try to use ``mapi`` on Windows. On other platforms, it

304

327

will try ``xdg-email``. If either of these fails, it will fall back to

322

345

:xdg-email: Use xdg-email to run your preferred mail program

323

346

324

347

submit_branch

325

-------------

348

~~~~~~~~~~~~~

349

326

350

The branch you intend to submit your current work to. This is automatically

327

351

set by ``bzr send``, and is also used by the ``submit:`` revision spec. This

328

352

should usually be set on a per-branch or per-location basis.

329

353

330

354

public_branch

331

-------------

355

~~~~~~~~~~~~~

356

332

357

A publically-accessible version of this branch (implying that this version is

333

358

not publically-accessible). Used (and set) by ``bzr send``.

334

359

335

360

336

361

Branch 6 options

337

================

362

----------------

338

363

339

364

These options apply only to branches that use the "dirstate-tags" format. They

340

365

are usually set in ``.bzr/branch/branch.conf`` automatically, but may be

341

366

manually set in ``locations.conf`` or ``bazaar.conf``.

342

367

343

368

append_revisions_only

344

---------------------

369

~~~~~~~~~~~~~~~~~~~~~

370

345

371

If set to "True" then revisions can only be appended to the log, not

346

372

removed. A branch with this setting enabled can only pull from

347

373

another branch if the other branch's log is a longer version of its

348

374

own. This is normally set by ``bzr init --append-revisions-only``.

349

375

350

376

parent_location

351

---------------

377

~~~~~~~~~~~~~~~

378

352

379

If present, the location of the default branch for pull or merge.

353

380

This option is normally set by ``pull --remember`` or ``merge

354

381

--remember``.

355

382

356

383

push_location

357

-------------

384

~~~~~~~~~~~~~

385

358

386

If present, the location of the default branch for push. This option

359

387

is normally set by ``push --remember``.

360

388

361

389

bound_location

362

--------------

390

~~~~~~~~~~~~~~

391

363

392

The location that commits should go to when acting as a checkout.

364

393

This option is normally set by ``bind``.

365

394

366

395

bound

367

-----

396

~~~~~

397

368

398

If set to "True", the branch should act as a checkout, and push each commit to

369

399

the bound_location. This option is normally set by ``bind``/``unbind``.

370

400