bk config-etc(7.3ce) BitKeeper User's Manual bk config-etc(7.3ce)
NAME
bk config-etc - configuring BitKeeper
DESCRIPTION
BitKeeper config files contain repository configuration information
including project description, licensing information, user preferences,
BK/Web preferences, and contact information. Config file entries take
the form of key-value pairs. This page describes the various configu-
ration keys and their possible values.
Each BitKeeper repository must have some minimum configuration informa-
tion available in order to properly execute BitKeeper commands. Repos-
itory configuration information is searched for in the following
places, in order:
`bk root`/BitKeeper/etc/config This repository's config file
`bk root -P`/BitKeeper/etc/config Product repository config file
`bk dotbk`/config Personal config file
/etc/BitKeeper/etc/config Per-machine config file
`bk bin`/config Per-installation config file
`bk root`/BitKeeper/log/config This repository's config file
`bk root -P`/BitKeeper/log/config Product repository config file
$BK_CONFIG Environment variable
The BitKeeper/log/config file[s] are not version controlled but the
BitKeeper/etc/config file[s] are. Having two gives you a way to have
repository specific values that do not propagate.
For detailed information about how all the search order works, or to
CONFIG FILE ENTRIES
AUTOFIX
The bk check command can automatically fix a number of problems found
in a repository. The default is that this variable is on in newly cre-
ated repositories, and that the variable will be passed through as the
"-f" option to bk check. To enable or disable autofix, one of the fol-
lowing should be in your configuration:
autofix:yes
autofix:no
AUTOPOPULATE
Cause all (nested) pull operations to use the --auto-populate option
(thus bringing in missing components as needed). Default is no.
auto_populate:yes
auto_populate:no
BAM SIZE
The optional BAM variable controls how large a binary needs to be to be
stored in BAM. The size is compared to the size of the initial checkin
only. Example values the variable may hold are:
BAM: on
BAM: off
BAM: 1K
BAM: 64K
A "K" suffix means multiply by 1024, a "M" suffix means multiply by
1024^2. The default size, if not specified, is 64K.
BK/WEB PREFERENCES
BK/Web preferences can be specified your configuration. If these pref-
erences are specified, information given will appear on the BK/Web site
for the project.
bkweb specify the BK/Web address for a project
homepage the home page for your project or company
master the location from which source can be cloned
For example,
bkweb: http://mysql.bkbits.net:8080/mysql-5.0
master: bk://mysql.bkbits.net/mysql-5.0
homepage: http://www.mysql.com
CHECKOUT MODE
Specify checkout mode for a repository. If unset, the default is
"none". To change the default, add or change the following line to/in
your configuration:
checkout:<option>
where option is one of:
get Automatically do a bk get <file> after doing a bk delta <file>.
(Checkout in read-only mode.)
edit Automatically do a bk edit <file> after doing a bk delta <file>.
Note: This will also adjust the modification time of the s.file to
be two seconds before the modification time of the gfile, which is
needed in order to prevent make(1) from attempting to re-get the
file. (Checkout in edit mode.)
last Preserve the previous state of <file>. This is like checkout:none
for a clone. If the file was later locked and then checked in, it
will be checked out again with a lock.
none Clear the gfile after doing a bk delta <file>. (This is the
default.)
For those repositories with BAM data, there is a checkout mode specifi-
cally for BAM files:
BAM_checkout:option
where option is as above.
The BitKeeper support team recommends "BAM_checkout:last".
CLOCK SKEW
When BitKeeper is looking for modified files, file time stamps can be
compared to a per-repo database to determine when files are unmodified
leading to a substantial performance improvement in larger reposito-
ries. The "clock_skew" parameter controls how old a file must be
before file time stamps are to be trusted. A certain amount of clock
skew is strongly advised since the use of network file systems can
cause the time stamps to be incorrect. The time is in seconds and
defaults to 604800 (one week).
clock_skew: on # use system defaults
clock_skew: 86400 # one day
clock_skew: off # disable trusting of time stamps
CLONE DEFAULT
When cloning a nested collection, if the -s option is not used, then
the "clone_default" option specifies the default set of compo-
nents/aliases to clone. If "clone_default" is not set then "ALL" is
implied.
clone_default: THERE # always match remote repository
clone_default: PRODUCT # only the product, no components
clone_default: ALL # all components cloned by default
clone_default: MYALIAS # clone MYALIAS by default
COMPRESSION
By default, when you setup a repository in compatibility mode, the com-
pression algorithm will be set to gzip in your configuration as fol-
lows:
compression:gzip
This results in the compression of stored s.files. To make the reposi-
tory use no compression by default, change the compression line your
configuration to be:
compression:none
pression.
DESCRIPTION
The config file must contain a one line description of the contents of
the repository.
description: cross-platform C-like GUI programming language
KEYWORD EXPANSION
Keyword expansion is turned OFF by default. To have keyword expansion
flags applied to a file automatically upon checkin, add the keyword
preference to your configuration.
Keyword preference options are:
sccs expand SCCS keywords (%keyword%).
expand1 expand keywords in the first line that contains keywords
only (avoids printf conflicts).
rcs expand rcs keywords ($keyword$)
For example, having
keyword: sccs, expand1
in the config file will expand SCCS keywords only in the first line
encountered that contains sccs keywords. Note: Setting this option
affects only files created subsequently.
LINE TERMINATION
The UNIX and Windows operating systems use different characters to rep-
resent line terminations (eoln). BitKeeper, by default, sets the eoln
preference to native when an sfile is created. This means that files
checked out on Windows will have the Windows eoln and files checked out
on UNIX will have the UNIX eoln.
When a file is created, the line termination is taken from the "eoln"
configuration variable. It is a per-file flag that may be overridden
with the bk admin command.
Line-termination preference options are:
native Set line termination to the native sequence for the platform
("\n" on UNIX and Linux; "\r\n" on Windows). (This is the
default.)
unix Force line termination to the UNIX standard ("\n").
windows Force line termination to the Windows standard ("\r\n").
To force the UNIX eoln mode on all platforms, your configuration must
have this:
eoln:unix
To force Windows line termination use:
eoln:windows
In general, the default of native line terminations is the right answer
and for exceptions the bk admin command may be used to set this option
on a per file basis.
PARALLEL
By default, BitKeeper runs some processes in parallel to gain perfor-
mance. The defaults are 8 way parallel for NFS and 3 way parallel for
local file systems. You may override the defaults for all cases like
so:
parallel:12
Setting the value to 0 will disable parallelism.
PARTIAL CHECK
BitKeeper may be configured to do a full repository integrity check
after each update. The integrity check validates both internal Bit-
Keeper metadata and file checksums. The integrity checks have been
shown to catch hardware problems such as bad memory chips, bad disk
drives, and software problems such as NFS inserting blocks of nulls in
the middle of files. Unless you have a larger repository (more than
5,000 files and/or more than 100MB) then you may want to enable full
checks all the time.
By default, BitKeeper will run in partial_check mode, which means a
full check is performed no more than once per week and only partial
checks are performed when the repository is updated.
You may control the frequency of the full checks with the following
variable, units are in days. To force a full check every two days:
check_frequency: 2
The following will disable the partial_check mode and force BitKeeper
to perform full integrity checks on every update (safest but at a per-
formance cost):
partial_check: off
PULL STATISTICS
It is possible to make pull print statistics in a format compatible
with diffstats by adding this to your configuration:
stats_after_pull: on
Note that gathering the statistics needs another pass over the data so
if you are very performance sensitive, you might want to keep this
option off.
SYNC
In some environments it may be safer to have BitKeeper do an fsync(2)
after each update of a history file. Some Linux file systems perform
poorly because fsync(2) is implemented as a system wide sync(2).
The default is not to flush but the default may be overridden with:
sync:on
TRIGGER PATHS
By default, triggers are stored in the repository under the Bit-
Keeper/triggers/ directory and this is the only directory searched when
looking for triggers. More than one triggers directory may be used by
setting the triggers variable. The format is one or more paths sepa-
rated by a vertical bar, each path has "BitKeeper/triggers" appended to
it and the resulting path is scanned for triggers. For example, if you
wanted to run triggers from /etc/BitKeeper/triggers and from the repos-
itories' BitKeeper/triggers, set the variable as follows in your con-
figuration:
triggers: /etc|.
The directories are processed in the order found in the variable.
There are several special values which are interpreted:
. This is the default, it means `bk -R pwd`/BitKeeper/triggers is
scanned for triggers.
$BK_DOTBK
If present, `bk dotbk`/BitKeeper/triggers is scanned for triggers.
$BK_BIN
If present, `bk bin`/BitKeeper/triggers is scanned for triggers.
$NONE
If present, with no other values, then no triggers are processed.
$PRODUCT
If present, `bk -P pwd`/BitKeeper/triggers is scanned for triggers.
This only applies when in a component repository of a nested col-
lection. It is a way to run product level triggers in each compo-
nent.
$SOMETHING_ELSE
All other paths starting with "$" are ignored, that character is
reserved.
UPGRADE URL
The upgrade command normally looks for new versions of BitKeeper here:
http://upgrades.bitkeeper.com/upgrades/ but that location may be over-
ridden by setting the upgrade_url field to an different URL.
For example,
upgrade_url: http://www.example.com/bk-release/
The contents of that directory will need to be manually mirrored from
BitKeeper Inc.
USER PREFERENCES
Repository preferences can be defined in your configuration: The gen-
eral format for the repository preference config file is
[filter]preference:option
The optional filter can be any of the following:
no filter preference:option
empty filter []preference:option
per user [jdoe]preference:option
per host [@xyz.com]preference:option
per pathname [:/path/to/repo]preference:option
per user@host [jdoe@xyz.com]preference:option
per repository [:/path/to/repo]preference:option
[@xyz.com:/path/to/repo]preference:option
[jdoe@xyz.com:/path/to/repo]preference:option
Preferences can be listed multiple times with different filters. The
filters are examined in order and the first line that matches the cur-
rent user, host, and pathname is used. So in general the most restric-
tive directives should appear first.
SEE ALSO
bk admin
bk config-gui
bk config
bk setup
bk upgrade
CATEGORY
Overview
Admin
BitKeeper Inc 1E1 bk config-etc(7.3ce)
Admin