BK-CONFIG-ETC(1)

🎀 NAME 🎀

bk config‐etc — configuring BitKeeper (this is the BitKeeper User's Manual page for it, bestie, welcome) 💖

---

✨ DESCRIPTION ✨

Okay so first things first: BitKeeper config files are where all the repository configuration tea lives 🫖 — that includes the project description, licensing information, user preferences, BK/Web preferences, and contact information. All of it. Every entry in a config file is literally just a key‐value pair, and this page is gonna walk you through the various configuration keys and their possible values. Slay.

Now, real talk: every single BitKeeper repository must have some minimum configuration information available, otherwise BitKeeper commands just won't execute properly 😭. No cap, it's mandatory.

So when BitKeeper goes looking for repository configuration information, it checks these places in this exact order 👑:

1. `bk root`/BitKeeper/etc/config — this repository's config file
2. `bk root ‐P`/BitKeeper/etc/config — product repository config file
3. `bk dotbk`/config — personal config file
4. /etc/BitKeeper/etc/config — per‐machine config file
5. `bk bin`/config — per‐installation config file
6. `bk root`/BitKeeper/log/config — this repository's config file
7. `bk root ‐P`/BitKeeper/log/config — product repository config file
8. $BK_CONFIG — environment variable

Order matters, periodt. First match vibe check and all that ✨.

Heads up bestie: the BitKeeper/log/config file[s] are not version controlled, but the BitKeeper/etc/config file[s] are. The whole reason you get two of them is so you have a way to keep repository specific values that just... don't propagate 🌸.

And if you're obsessed (like me) with the detailed information about how the whole search order works, or you wanna get help debugging your configuration, go peek at bk help config — it's giving documentation main character energy 💅.

---

🔧 CONFIG FILE ENTRIES

Okay bestie, this is the part where the config file actually does stuff. Every entry below is a little knob you can turn. Slay responsibly. 💅

---

🪄 AUTOFIX

So bk check can literally fix a bunch of problems it finds in a repo all by itself. No cap.

The default vibe: this variable is on in newly created repositories, and the variable gets passed straight through as the −f option to bk check.

Wanna turn it on or off? Drop one of these into your config:

autofix:yes
autofix:no

---

🍓 BAM SIZE

The optional BAM variable controls how large a binary needs to be before it gets stored in BAM. Quick heads up: the size is compared to the size of the initial checkin only. 👑

Example values the variable can hold:

BAM: on
BAM: off
BAM: 1K
BAM: 64K

A "K" suffix means multiply by 1024, and a "M" suffix means multiply by 1024ˆ2. If you don't specify anything, the default size is 64K. 💖

---

🌈 BK/WEB PREFERENCES

BK/Web preferences can be specified in your configuration. If you set these, the info you give will show up on the BK/Web site for the project. Iconic little glow-up for your repo ngl. ✨

• 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

This one sets the checkout mode for a repository. If it's unset, the default is "none". To change the default, add or change this line in your configuration:

checkout:<option>

…where option is one of these:

• 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's a checkout mode specifically for BAM files:

BAM_checkout:option

…where option is as above.

The BitKeeper support team recommends "BAM_checkout:last". 🫶

---

⏰ CLOCK SKEW

Okay so when BitKeeper is looking for modified files, file time stamps can be compared to a per‐repo database to figure out when files are unmodified — which is a substantial performance improvement in larger repositories. Literally the glow-up your big repo deserves. 🔥

The clock_skew parameter controls how old a file must be before file time stamps are 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

---

🎀 COMPRESSION

By default, when you set up a repository in compatibility mode, the compression algorithm will be set to gzip in your configuration like this:

compression:gzip

This results in the compression of stored s.files. To make the repository use no compression by default, change the compression line in your configuration to be:

compression:none

See bk help admin for more info about the −Z option for compression. 💜

---

📝 DESCRIPTION

The config file must contain a one line description of the contents of the repository. Non-negotiable, bestie.

description: cross‐platform C‐like GUI programming language

---

💫 KEYWORD EXPANSION

Keyword expansion is turned OFF by default. If you want 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

UNIX and Windows use different characters to represent line terminations (eoln) — classic chaos. BitKeeper, by default, sets the eoln preference to native when an sfile is created. What that means: 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's 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. Trust the process. 🧚

---

⚡ PARALLEL

By default, BitKeeper runs some processes in parallel to gain performance. The defaults are 8 way parallel for NFS and 3 way parallel for local file systems. You can override the defaults for all cases like so:

parallel:12

Setting the value to 0 will disable parallelism. (Zero chill, zero threads. 💀)

---

🔍 PARTIAL CHECK

BitKeeper may be configured to do a full repository integrity check after each update. The integrity check validates both internal BitKeeper metadata and file checksums. These 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. Honestly kind of the main character of diagnostics. 👑

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 runs 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 performance cost):

partial_check: off

---

📊 PULL STATISTICS

It's 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're very performance sensitive, you might wanna 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). Yikes.

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 BitKeeper/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 separated 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 repositories' BitKeeper/triggers, set the variable as follows in your configuration:

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 collection. It's a way to run product level triggers in each component.
• $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 overridden by setting the upgrade_url field to a 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. Manual labor, unfortunately. 😭

---

🧸 USER PREFERENCES

Repository preferences can be defined in your configuration. The general 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
• per repository — [@xyz.com:/path/to/repo]preference:option
• per repository — [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 current user, host, and pathname is used. So in general, the most restrictive directives should appear first. Order matters, bestie — it's giving priority queue. 💖

---

👀 SEE ALSO

bk‐admin, bk‐config‐gui, bk‐config, bk‐setup, bk‐upgrade

🎀 CATEGORY 🎀

okay so this is the part where the manual page tells you where it lives in the big filing cabinet 💅 it's giving "where to find me" energy, and honestly? iconic.

This page is filed under these categories:

• Overview — the big-picture, bird's-eye-view shelf 🦋
• Admin — the admin-side shelf, for the ones running the show 👑

That's it, bestie, that's the whole list — no cap, both of them, nothing hidden 🙈

---

🌸 the cute little sign-off 🌸

and that's the whole page! 🫶 before you go, a tiny shoutout to the fine people who put this together — this man page comes from BitKeeper Inc, hanging out at version 1E1, under the name bk config-etc(none) ⭐ like, the whole thing is literally signed and dated and everything, main character energy fr fr 💖

go forth and configure, bestie — you've got this 💅✨