BK-LOG(1)

bk log(none) — BitKeeper User's Manual 🦋✨

okay bestie welcome to the bk log page, this one is a whole journey, grab a strawberry drink 🍓 and let's go

---

✨ NAME ✨

bk log — print file revision history and/or metadata 💖

Fine. Pure. Iconic. It prints your file's whole little life story and/or the metadata that goes with it.

🌸 SYNOPSIS 🌸

bk log [-dDfS] [-cd] [-Cr] [-L[url]] [-rr] [file ... | -]

💅 DESCRIPTION 💅

So the bk log command is the one you use to extract revision history and or metadata from a file or a whole set of files 🫶. The default behavior — like, if you just vibe and type it — is to print a summary of each revision to each of the specified files. There are options to restrict the set of revisions it prints, and the one everybody and their bestie uses is -r+, which restricts the set to the most recent revision only. lowkey a classic.

With no options, bk log output defaults to giving you information on all revisions of all files in the present directory that are under BitKeeper control 👑. The output goes like this: the name of the file and the range of revisions, followed by a detailed account of each revision. That account has the revision number, the revision date and time, the user who made that revision, what the relative path from root of repository is to that file, the comments that go with that revision, and documents if the file has been renamed. fr fr it's giving full detective dossier 🔍

---

🌈 OPTIONS 🌈

• -n — a numeric argument that limits the number of deltas printed per file. yes it's -n here and yes it comes back later, this page has layers 💀
• --begin=script — the dspec v2 language (see that section below and the examples) is awk like and has optional begin/end sections. This option lets you specify the body of a begin section (and if the file also has a begin section then both are run; the order is undefined 😭). It's typically used with an on disk dspec in a dspec file that's been written in a way to do one thing by default and another if a variable is set to non-zero. sneaky, love that for you.
• -cdate — cut-off dates 💅. See range specifications (below) or bk help range for details.
• -Crev — makes the range be all revs that are the same cset as rev.
• -dspec — override the default output format (see below).
• --dspecf=file — like -d but read the dspec from a file.
• -D — do not skip files in the BitKeeper/deleted directory. (default is to skip them, so this is your "show me the ghosts" flag 👻)
• -f — print the changes in forward (oldest to newest) order. The default is backward.
• -L[url] — show all deltas unique to this repository relative to the (outgoing) parent, or url if one was specified. May not be combined with -c or -r ⚠️
• --lattice — restrict the deltas to those on the lattice between the two range endpoints. Unlike a range, the lower bound is included in the output 👀
• --longest — restrict the deltas to those on the longest line between the two range endpoints. Unlike a range, the lower bound is included in the output.
• -n — add a newline to each printed record. (yep, second -n of the page, the manpage said "reuse the letter, it ate" 💀)
• -rrev — specify a revision, or part of a range. (Or key or changeset revision. See bk help terms under "rev argument.")
• -S, --standalone — use with -L in a nested component when you want the component to act like a standalone repository.

🎀 RANGE SPECIFICATIONS 🎀

• -r+ — prints the most recent delta ⭐
• -r1.3..1.6 — prints all deltas that are in 1.6's history but are not in 1.3's history.
• -c2006/07..2006 — prints all deltas from July 1 2006 to Dec 31 2006
• -c2006..2006 — prints all deltas from Jan 1 2006 to Dec 31 2006
• -c-1d.. — prints all deltas made in the last 24 hours 🕐; similarly for s, m, h, d, M, and Y for seconds, minutes, hours, days, months, and years.

---

🦋 DEFAULT OUTPUT FORMAT 🦋

The bk changes and bk log commands have a default output format which may be modified on a per user or per repository basis 💖. The default formats are named as follows:

• dspec-changes — specifies the format for bk changes [-v] output (without -vv).
• dspec-changes-vv — specifies the format for bk changes -vv output (verbose with diffs).
• dspec-log — specifies the format for bk log output.

There are other dspec-* files, and if you want some fun look at dspec-*-json 😭 if you understand those you understand that dspecs are a little programming language. The shipped files live in ‘bk bin‘/dspec-*

These files can live in multiple places, and this is the search order for "dspec-changes" — the first one found is used:

1. <repo>/BitKeeper/etc/dspec-changes
2. <product>/BitKeeper/etc/dspec-changes (BitKeeper/Nested only)
3. ‘bk dotbk‘/dspec-changes
4. /etc/BitKeeper/etc/dspec-changes
5. ‘bk bin‘/dspec-changes

---

💜 MODIFYING THE OUTPUT FORMAT 💜

There are many different pieces of information in a BitKeeper file and virtually all of them can be extracted using a non-default output format ✨

To extract specific information, a "dspec" (data specification) string is provided, and where there are keywords surrounded by colons the keywords are expanded much like printf(3). This can lead to many useful one liners; want to see which file is the most busy in a repository? 👑

bk -U log -r+ -nd':DS: :GFILE' | sort -nr | head

If you're familiar with awk(1) the processing here is similar 🫶. In awk, each line is a record; here, each delta is a record. For each delta, you can provide a dspec which says what it is you want to print from that delta. Looking at the dspec-* files in the installation directory is recommended — there are $begin/$end sections that mimic awk.

The dspecs can contain the following set of escaped characters which will be replaced with the specified string:

• \b — Backspace
• \f — Form feed
• \n — Newline
• \r — Carriage return
• \t — Tab
• \123 — 3 digit octal value (pad with leading zeros)
• \<c> — c for any other character "c"

In almost all cases, a trailing newline is not provided by any of the keywords and one should be provided as needed 🌸. The newline can be added in line, or you can specify the -n option which will add a newline after each delta is processed.

Multi-line keywords are normally printed as is, but you can format each line separately using a $each() loop (see ITERATIVE OUTPUT below).

🌟 CONDITIONAL OUTPUT 🌟

The dspec can produce output conditionally 👀. The following prints the revisions of foo.c that were made by joe:

bk log -nd'$if(:USER:=joe){:REV:}' foo.c

💫 CONDITIONAL STATEMENTS 💫

• $if(expr){anything} — prints anything if expr is true. If expr is a keyword, i.e., :MERGE:, then the keyword is examined and returns true if it has a value. anything can contain keywords, i.e., :REV:.
• $unless(expr){anything} — prints anything unless expr is true.
• $if(expr){stuff if true}$else{stuff if false} — both $if and $unless can have an optional $else clause that prints if the preceding clause was not printed.

🧚 CONDITIONAL OPERATORS 🧚

strings

• lhs=rhs — true if lhs is identical to rhs.
• lhs!=rhs — true if lhs is different than rhs.
• str=~glob — true if str matches glob.
• str=~/regexp/ — true if str matches the regular expression; /regexp/i does a case-insensitive match and /glob/g does a glob match.

Note: spaces immediately before and after the operator are ignored. To match against such a leading or trailing space, escape it.

numbers

• lhs -eq rhs — equality;
• lhs -ge rhs — equal or greater than;
• lhs -gt rhs — greater than;
• lhs -le rhs — equal or less than;
• lhs -lt rhs — less than.

Note: spaces are required on both sides of the operator.

🌈 COMPOUND EXPRESSIONS 🌈

As of BitKeeper release 4.1, dspecs support logical AND (A && B), logical OR (A || B), and parenthesized subexpressions ((A && B) || (C && D)) 🔥 Note: spaces immediately before and after the operator are ignored. To match against such a leading or trailing space, escape it.

🎀 ITERATIVE OUTPUT 🎀

Some keywords, such as comments or tags, may be multi-line. To print a prefix in front of each of these lines, the dspec is:

bk log -d'$each(:C:){C  (:C:)\n}' foo.c

This iteration works for all keywords, but normally is only used for keywords that can contain multiple lines like ALL_TAGS, C, TAGGED, and TAGS.

The $first() builtin can be used to print only the first line of one of these multi-line keywords 💖. Some development efforts tend to use the first line of commit comments as a summary of the change; the rest are more details. The dspec that ships with BitKeeper for bk changes uses this feature to implement bk changes --short. To print the first line of each comment in a changeset:

bk changes -nd'$first(:C:)'

🍓 VARIABLES 🍓

When the bk log command is run over multiple revisions of one or more files, the data specification ("dspec") is evaluated once for each revision, and it sometimes is useful to use dspec variables, denoted as '$0', '$1', up to '$9', to remember values across revisions or files 💅. A variable is assigned a value with:

${0=<dspec>}

where <dspec> is a recursively evaluated data specification. Once assigned, a variable retains its value for the remainder of the command (or until reassigned) 🫶. Variables start out as empty strings (evaluate to zero in numeric context), and when re-assigned the old value is discarded.

👑 DSPEC VERSION 2 👑

This little printf like language outgrew itself — having if/then/else and other control flow was too much on just one line 😭. We came up with a version 2 language that allows you to have dspecs that look like a programming language. All of the output from BitKeeper commands is generated via the v2 language in external files (see dspec-* in the bin directory). All of the commands that take dspecs also can take a file containing the dspec; that's how the BitKeeper commands work, they just load those files ✨

To switch into the new language a dspec has to begin like so:

# dspec-v2

The language is awk like, comments start with "#" and go to the end of the line. Whitespace is ignored unless it is inside double quotes, then it is reproduced exactly. Keywords are expanded inside of double quotes as are the escaped characters mentioned above. Control flow and begin/end blocks (all the $something) are unquoted.

Like awk, there are optional begin/end blocks:

           $begin {
                   "[\n"
           }
           $end {
                   $if($0 ‐eq 1) {
                           "\n"
                   }
                   "]\n"
           }

Those come from dspec-changes-json-v, aka the dspec behind bk changes -v --json, which (plot twist) makes json output. If you actually want to learn this little language, that file is a genuinely good read. 📖

Other than variables — which do expand inside double quotes — none of the $word things ($if/$else/$first/$each/etc) expand inside double quotes. This is the kind of thing that jumpscares you. You might think the bk changes --short dspec is:

":MD5SUM: $first(:C:)\n"

...but nope, that does not work. This does:

":MD5SUM: " $first(:C:) "\n"

In lots of cases, all keywords expand inside begin/end blocks, and those run in the context of the first/last delta selected. If you select a range with no matching deltas (think bk changes -L, for example), then none of the keywords expand — the current system expands keywords if and only if there’s a valid delta in play.

A simple dspec-v2 is the bk log output format:

":DPN: :REV:\n"
"  :D_: :T::TZ: :USERHOST: +:LI: ‐:LD:\n"
$each(:C:) {            # comments
        "  (:C:)\n"
}
"\n"
$if (:TAGS:) {
        $each(:TAGS:) {
                "  TAG: (:TAGS:)\n"
        }
        "\n"
}

That says:

• line 1: print the path name and the revision
• line 2: indent the date/time/timezone, user@host, and +lines added / -lines deleted
• lines 3–5: indent each line of the comments
• line 6: blank line
• lines 7–11: if there are tags, print them with another blank line

🦋 KEYWORDS 🦋

Okay so some keywords are per repository and get an R in the T column below. Some are per file and get an F. Other keywords are per delta and get a D. Some only make sense on changesets, and those get a C. Keywords that can be either on a changeset or on a file are marked D too.

Here’s the whole keyword menu, with the T tag up front:

• :AGE: — D — how old D is, i.e. seven hours, two weeks, etc.
• :ALL_TAGS: — C — the tag[s] if this changeset has them or ever had them
• :ATTACHED_ID: — F — package id to be used for new deltas
• :BAM: — F — true if the file is managed as a BAM file
• :C: — D — D’s comments
• :CHANGESET: — F — true if ChangeSet file, false for user files
• :COMMENTS: — D — comments portion of :PRS:
• :COMPRESSION: — D — D’s compression (gzip|none)
• :CSETKEY: — D — delta key if D is at a changeset boundary
• :CSETREV: — D — revision of first cset boundary after D
• :D: — D — D’s date as YYYY/MM/DD
• :D_: — D — D’s date as YYYY-MM-DD
• :DANGLING: — D — D’s rev if and only if D is a dangling delta
• :DI: — D — D’s includes/excludes as +I,I/‐X,X (serials)
• :DIFFS: — D — D’s changes in the form of traditional diffs
• :DIFFS_U: — D — D’s changes in the form of unified diffs
• :DIFFS_UP: — D — D’s changes in the form of unified/procedural diffs
• :DL: — D — lines inserted/deleted/unchanged in D
• :DM: — D — month part of D’s date (Jan..Dec)
• :DOMAIN: — D — the domain part of the hostname of D
• :DP: — D — the serial number of the parent of D
• :DPN: — D — the pathname of g.file as of D
• :DS: — D — the serial number of D
• :DSUM: — D — D’s 16 bit unsigned checksum (%05u)
• :DSUMMARY: — D — first line of :PRS:
• :DT: — D — D’s type: (D|R|T) meaning (Data|Removed|Tag)
• :Dd: — D — day part of D’s date as DD
• :Dm: — D — month part of D’s date as MM
• :Dn: — D — serial numbers of D’s includes, if any
• :Dt: — D — D’s data as :DT::REV::D::T::USER::DS::DP:
• :Dx: — D — serial numbers of D’s excludes, if any
• :Dy: — D — year part of D’s date as YY or YYYY
• :ENC: — F — current encoding scheme (ascii|uuencode|BAM)
• :EVEN: — D — True on every other delta processed
• :F: — F — basename of the BitKeeper file
• :FLAGS: — D — file flags as of D in words (HASH, YEAR4...)
• :FSUM: — F — 16 bit unsigned checksum of the s.file
• :FUDGE: — D — time stamp fudge used make time monotonic
• :FULLHOST: — D — same as :HOST: or :HOST:/:REALHOST:
• :FULLUSER: — D — same as :USER: or :USER:/:REALUSER:
• :G: — F — basename of the gfile
• :GB: — D — file as of version D
• :GCA: — D — find the graph GCA for D’s parents
• :GCA2: — D — find the set GCA for D’s parents
• :GFILE: — F — pathname of the gfile
• :GREV: — F — for a file with conflicts, the GCA of the unmerged tips
• :HASHCOUNT: — D — count of key/value pairs in D if and only if hash file
• :HOST: — D — hostname where D was made; could be BK_HOST
• :HTML_AGE: — D — age in a form suitable for web pages
• :HTML_C: — D — comments in a form suitable for web pages
• :ID: — D — the package id in effect when the delta was made
• :IMPORTER: — D — name of the importer of D, if D was an emailed patch
• :KEY: — D — BitKeeper key of D
• :KID: — D — D’s direct kid in D’s branch
• :KIDS: — D — all of D’s direct kids in the graph
• :L: — D — the second field in D’s rev (R.L.B.S)
• :LD: — D — lines deleted in D (%u)
• :LI: — D — lines inserted in D (%u)
• :LREV: — F — for a file with conflicts, the LOCAL unmerged tip
• :LU: — D — lines unchanged in D (%u)
• :Ld: — D — lines deleted in D (%05u)
• :Li: — D — lines inserted in D (%05u)
• :Lu: — D — lines unchanged in D (%05u)
• :MD5KEY: — D — crypto based BitKeeper key of D
• :MERGE: — D — D’s rev if and only if D has a merge parent
• :MGP: — D — D’s merge parent’s serial number
• :MODE: — D — D’s file modes as an octal (777)
• :MPARENT: — D — D’s merge parent’s revision
• :N: — D — Number of deltas, use instead of DS, DS may have gaps
• :NEXT: — D — next entry after D in delta table
• :ODD: — D — True on every other delta processed
• :PACKAGE_ID: — R — per repository unique id (like bk id)
• :PARENT: — D — D’s parent’s revision
• :PREV: — D — previous entry before D in delta table
• :PRODUCT_ID: — R — per repository unique id (like bk -P id)
• :PRS: — D — old-style bk prs default output
• :R: — D — the first field in D’s rev (R.L.B.S)
• :RANDOM: — F — random bits part of ROOTKEY
• :REALHOST: — D — real host where D was made, regardless of BK_HOST
• :REALUSER: — D — real programmer who made D, not assumed identity
• :RENAME: — D — D’s path if different from parent’s path
• :REPO_ID: — R — per repository unique id (like bk id -r)
• :REPOTYPE: — R — repotype: product|component|standalone
• :REV: — D — D’s revision number
• :RI: — D — revision numbers of D’s includes/excludes
• :ROOTKEY: — F — key of the 1.0 delta, file’s internal name
• :RREV: — F — for a file with conflicts, the REMOTE unmerged tip
• :RWXMODE: — D — D’s file modes as ascii (-rwxrwxrwx)
• :Rn: — D — revision numbers of D’s includes
• :Rx: — D — revision numbers of D’s excludes
• :S: — D — last field in D’s rev (R.L.B.S)
• :SFILE: — F — pathname of s.file
• :SIBLINGS: — D — rev sibling’s pointer in D
• :SPN: — D — pathname of s.file as of D
• :SYMLINK: — D — value of D’s symlink target
• :T: — D — time of D as HH:MM:SS
• :TAGGED: — C — The tag[s] iff currently on this changeset
• :TAGS: — C — Tag[s] if on, or were on, this changeset (with notes)
• :TIME_T: — D — D’s date as GMT time_t, TZ and Fudge adjusted
• :TIP: — D — D’s rev if D is at the tip (TOT)
• :TZ: — D — offset from GMT as +/‐HH:MM
• :Th: — D — hour part of D’s date as HH
• :Tm: — D — minute part of D’s date as MM
• :Ts: — D — seconds part of D’s date as SS
• :USER: — D — programmer who made D; could be assumed identity
• :UTC: — D — D’s time stamp as YYYYMMDDHHMMSS in GMT
• :UTC‐FUDGE: — D — like UTC but without the date fudge
• :VERSION: — F — file format version

---

📝 NOTES 📝

Keywords marked with type C or D above can optionally be restricted to a given revision, like this:

:KW|1.0:      # as of a literal revision
:KW|PARENT:   # as of the current rev’s parent
:KW|MPARENT:  # as of the current rev’s merge parent (if any)

For example:

bk log ‐hnd’$if(:DPN|PARENT: != :DPN:){rename :DPN|PARENT: => :DPN:}’

Things that can go in the second part include a specific revision (eg 1.0), PARENT, and MPARENT.

🌸 EXAMPLES 🌸

okay bestie, this is the part where it gets good 💅 these are real recipes you can steal, no cap.

To extract a key, which is a stable name for a changeset:

bk changes ‐r1.234 ‐nd:MD5KEY:

To count up all the deltas in all user files:

bk ‐U log ‐nd:REV: | wc ‐l

List users who have made changes in a subdirectory in the last month:

bk ‐rSubDir log ‐c‐1M.. ‐nd:USER: | sort ‐u

To see the number of merge changesets:

bk changes ‐nd’$if(:MERGE:){merge}’ | wc ‐l

To see the number of merges in user files:

bk ‐U log ‐nd’$if(:MERGE:){merge}’ | wc ‐l

Count up lines inserted by a particular user in all non‐merge deltas:

bk ‐U log ‐nd’$if(:USER: = joe && !:MERGE:){:LI:}’ |
awk ’{ lines += $1 } END { print lines }’

---

🦋 the default dspec, served fresh 🦋

The default dspec for the bk changes command is below. This is an example of a dspec‐v2 style of writing dspecs — and honestly? much more pleasant for complex reports. it's giving structured-data-girlboss energy ✨

# dspec‐v2

# The default dspec used by ’bk changes’ and ’bk changes ‐v’

":INDENT:"              # 2 spaces + 2 in component
":DPN:@:REV:"
${1=:USERHOST:}         # 1 == user || user@host
$if (:CHANGESET: && !:COMPONENT_V:) {
    ", :Dy:‐:Dm:‐:Dd: :T::TZ:, $1"
    ${0=$1}                          # 0 == user of last cset
} $else {
    $if($0 != $1){                   # print user if different
              ", $1"
    }
}
$unless (:CHANGESET:) {
    " +:LI: ‐:LD:"                   # lines added/deleted
}
"\n"

# bk changes ‐‐short is an alias for
# bk changes ‐‐begin=’${9=1}’
# so $9 is the switch that decides between short/long form
$if ($9 ‐eq 0) {                     # comments (long form)
    $each(:C:) {
        ":INDENT:  (:C:)\n"
    }
} $else {                            # comments (short form)
    ":INDENT:  "
    $first(:C:)
    "\n"
}
$each(:TAGS:) {
    "  TAG: (:TAGS:)\n"
}
$if ($9 ‐eq 0) {                     # skip merge info for ‐‐short
    $if (:MERGE:) {                  # merge shows both parents
        ":INDENT:  MERGE: :MPARENT:\n"
    }
}
"\n"

---

👑 SEE ALSO 👑

• bk‐range — go read this one next, bestie, it's the whole vibe 🫶

---

🗂 CATEGORY 🗂

File

---

okay that's the whole page, you made it to the end, icon behavior fr fr 🌈🎀 this edition came to you from BitKeeper Inc, version 1E1, dated none in the footer — yeah, the date literally says none, and honestly? relatable. slay 💅✨