BK-CHANGES(1)

💅 bk changes — show changeset history ✨

ok so this is from the BitKeeper User's Manual, page bk changes(none), and bestie it's a lot but we're gonna get through it together 🫶

---

🌸 SYNOPSIS

bk changes [options] [-rrevs | -]
bk changes [options] repo [repo ...]
bk changes -L [options] [repo ...]
bk changes -R [options] [repo ...]
bk changes -L -R [options] [repo ...]

---

✨ DESCRIPTION

So the changes command is your lil overview engine — it shows you the changes made to a repository. And there are so many options to slice and dice that: search for particular changesets, view only tagged changesets, limit the search to a particular user, view only local changes, view only remote changes, view changes relative to a set of repositories, etc. etc. etc. 💖

Here's the vibe check on the five forms up top, in order:

• ☞ The first form shows changes in the local repository. If the last argument is a - then the revisions to be listed are specified — as keys, tags, and/or revisions — on stdin.
• ☞ The second form shows changes in the named repository.
• ☞ The third form lists changes found in the local repository but not in the remote repository. If the remote repository isn't specified, the outgoing parent[s] of the local repository is/are used, i.e., the listing is what would be sent on a push (when used with -a). 🚀
• ☞ The fourth form lists changes found in the remote repository but not in the local repository. If the remote repository isn't specified, the incoming parent[s] of the local repository is/are used, i.e., the listing is what would be received on a pull (when used with -a). 🌈
• ☞ The fifth form lists changes unique to either the remote or the local repository. The local changes are listed first, then the remote changes, and both sets of changes have a title line to separate them. 🎀

In all but the second form, the changes command must be run from within a repository, and that repository is the local repository while the named repository is the remote repository. All the other selection options are applied to the list of local-or-remote-only changesets. iykyk 💅

The changesets to be listed may be limited to a revision, a range of revisions, the last (or first) N changesets, or a list of revisions on stdin. The default is all revisions. And heads up: specifying revisions is incompatible with the -R/-L options. ⚠️

---

👑 OPTIONS

• -n — a numeric argument that limits the number of changesets printed.
• -/str/[igt] — list only those changesets whose comments contain the string str. str may be a regular expression, or if the g option is specified, a glob. If there's a trailing i then ignore case in the search. If there's a trailing t then search only in tag names. And yes, it would be nice if this worked on (meta)data other than the comments but as of now it does not 😭.
• -a — list all deltas, including tag deltas. The default is to list the tag name on the changeset implied by the tag. Implies -e. An additional -e after this option will turn off the listing of the empty merge deltas (the -e option is inverted from its previous value each time the option is seen) 🙈.
• --begin=script — the dspec v2 language (see bk help dspec, in particular the examples) is awk like and has begin/end sections. This option allows you to specify the body of a begin section (if the file also has a begin section then both are run; order is undefined 💀). A begin script is typically used with an on disk dspec file that has been written in a way to do one thing by default and another if a variable is set to non-zero.
• -cdates — specifies the changesets to be listed as a date range, i.e., -c-6W.. lists the last 6 weeks worth of changes. 🗓️
• -D — when showing local or remote only changes and there are multiple local or remote repositories specified (or implied via the parent pointer[s]), there may be duplicate changesets which are present in more than one repository. If this option is specified, then the duplicates are filtered out such that the changesets listed are a unique set. This option combined with -aL or -aR is used to answer the questions: "What is only in this repository relative to all of the specified repositories?" or "What is only in one or more of the remote repositories but not in this local repository?" respectively. 🔍
• -ddspec — override the default dspec, allows for arbitrary output formats.
• --dspecf=file — like -d but read the dspec from a file.
• -e — show empty merge changesets. By default, these are not shown.
• -f — print the changes in forward (oldest to newest) order. The default is backwards in time, i.e., most recent to least recent order. ⏪
• --html — produce html as output. May not be combined with -d. 🚫
• -ipat — include information only from changesets involving files matching pat pattern (see below).
• -k — produce a list of matching changeset keys, usually for scripts. Equivalent to -Dnd:KEY:.
• -L — list only those changesets which are unique to the local repository. Requires either a BK url or a valid repository parent. Will not report tags, or empty merges. Use with -a to see tags and empty merges, i.e., everything which would be sent back with a bk push 👀.
• --lattice — restrict the changesets to those on the lattice between the two range endpoints. Unlike a range, the lower bound is included in the output. Empty merge nodes are included (unlike the default output). 🕸️
• --longest — restrict the changesets to those on the longest line between the two range endpoints. Unlike a range, the lower bound is included in the output. Empty merge nodes are included (unlike the default output). 📏
• -m — do not show any merge changesets, empty or not.
• -n — add a newline to each printed record (sometimes useful with -d). (yes bestie, -n shows up twice in this list with two totally different jobs — that's just how it is, no cap)
• -q — when listing local/remote changes from multiple parents (or remote repositories) do not print the location of the remote repositories. This option is implied by -D. 🤫
• -rrevs — specifies the changesets to be listed, i.e., 1.100...
• -R — list only those changesets which are unique to the remote repository. Requires either a BK url or a valid repository parent. Will not report tags, or empty merges. Use with -a to see tags and empty merges, i.e., everything which would be brought over with a bk pull 🫳.
• --oneline — print a summary of every cset in a single line. It is an alias for: bk changes -nd'$if(:CHANGESET: && !:COMPONENT_V:){:MD5KEY: $first(:C:)}$else{ :DPN:}'
• --short — with the system supplied dspecs, this will limit the file/commit comments to only the first line (it does so by setting the $9 dspec variable to 1, the system supplied dspecs use that to change their output). ✂️
• --sparse-ok — when using include/exclude patterns (-i/-x) and the patterns could match in a component that is not populated, BitKeeper will refuse to perform the search and print an error. This option allows searching in sparse products (with some components not populated) without erroring. 🧚
• -t, --tags — only list changesets which are currently tagged. Use -tt (or --all-tags) to list all changesets which have ever been tagged, annotated with the tag's current state. 🏷️
• -T — sort the deltas in a changeset in time order. The default is to sort by current file name. This option only affects verbose (-v) output.
• -uuser — only list changesets created by user. This option may appear multiple times, in which case the changeset is listed if it matches any of the specified users. 💜
• -Uuser — only list changesets created by someone other than user. This option may appear multiple times, in which case the changeset is not listed if it matches any of the specified users.
• -v — shows individual file change history as well as changeset history. 🔥
• -vv — same as -v except that each file's change history is followed by unified diffs for that change (using the :DIFFS_UP: keyword).
• -xpat — exclude information from changesets involving files matching pat pattern (see below).

---

ok that's the whole options list, we ate that 💅 more coming in part 2, don't touch that dial 🦋

🎀 INCLUDE/EXCLUDE PROCESSING 🎀

okay bestie, so this part is all about controlling which changesets get printed, and honestly it's giving bouncer-at-the-club energy 💅

• You can have multiple include and/or exclude patterns. Not just one. Go off.
• The patterns are a file glob as used by bk ignore — same glob rules, no cap.
• They're matched against the partial pathname from the root of the repository.
• If that partial pathname matches any of the exclude patterns, the changeset is skipped. Bye 👋
• If there are one or more include patterns but the partial pathname doesn't match any of them, the changeset is also skipped.
• Exclude processing takes precedence over include processing. Periodt. Exclude wins, every time.

Now here's the messy little plot twist 😭 when reporting info there can be ambiguity about which name gets used for include/exclude processing, because some files may have been moved since the changeset in question. The include/exclude processing always applies to the file name as it was as of the changeset in question — not what it's called now.

Like, imagine a file that's currently deleted, but at the time of the changeset it was in src/foo.c. If you told the system to report src/*, then the file will be in the set ✨ iykyk.

---

💖 EXAMPLES 💖

Sample output, look at this iconic little log:

ChangeSet@1.607, 2000‐02‐21 14:05:25‐08:00, awc@bitkeeper.com
  update citool to use the "bk unedit" interface.

ChangeSet@1.606, 2000‐02‐21 13:35:21‐08:00, awc@bitkeeper.com
  Allow BitKeeper to be installed in an alternate directory.
  The install directory is computed from the $PATH variable and
  the bk symlink.

ChangeSet@1.605, 2000‐02‐20 01:32:19‐08:00, lm@bitkeeper.com
  Fix a diagnostic in pull.
  An aborted attempt at key compression.

---

🌈 SEE ALSO 🌈

go read these next, bestie — they're all linked and lowkey essential:

• bk‐commit
• bk‐glob
• bk‐pending
• bk‐log
• bk‐pcre
• bk‐pull
• bk‐push
• bk‐range
• bk‐revtool
• bk‐sccslog
• bk‐set

---

👑 CATEGORY 👑

• Common
• Repository

---

okay that's the whole page, and I'm obsessed with how much detail we just covered 🫶 this masterpiece was brought to you by BitKeeper Inc, version 1E1, and the footer's date slot literally says bk changes(none) — iconic, honestly 💅✨