New BAM notes (such as convert); old notes in BINPOOL

[Thu May 26 15:43:09 PDT 2011]

bam convert notes

Invariants - bam conversions are shrink only - after a bam conversion of size X ChangeSet rootkey is B:$X:randombits All uuencoded files that had a size of $X or less are now BAM files - bam convert does not care about, or modify, the BAM: setting in the config file. In fact, it could be BAM:off and bam convert will still do what it said it would.

That last one points out that the BAM:on or BAM:<size> setting is for new file creates. bam convert is for existing files. So the size in the rootkey is there only so that all other repos can run bam convert $size and get a result that will interoperate.

How the url to the current BAM server is maintained:

- The URL to the BAM server is stored in BitKeeper/log/BAM_SERVER
  the repo_id of that server is also stored here.
  This file is static and not changed by normal bk operations.

- A URL of "." indicates that this repo is a BAM server and when this
  repository is cloned it becomes the default URL for the new clone.

- If the BAM_SERVER file is missing or empty then the repository is
  assumed to have no BAM server and is expected to have all BAM data
  stored locally.

clone

- After a clone the BAM_SERVER file is initialized with the BAM server
  URL and repo_id from the source repository.  If the URL was ".",
  then the URL from the clone command line is used instead.

- Since clone doesn't change the server URL, only a repository with
  no BAM server will transfer any BAM data as part of the clone.
  (but see -B below)

- After a clone completes we verify that the new server URL works and
  that we get the expected repo_id.  If not the URL is cleared and a
  message is printed telling the user to use 'bk bam server URL' to
  set a valid URL.  (XXX checkout:get can be a problem here)

- An option '-B URL' option is added to clone to override the new
  server URL.  This is verified before the clone begins.  In this case
  a clone may transfer some BAM data files that exist on the source's
  BAM server, but not at the new URL.

rclone

- The rclone command works much like clone, but we can verify the new
  server URL at the destination before starting to transfer data.
  Also, unlike clone, in the case of cloning a BAM server the
  destination side cannot know the proper URL to use to contact the
  server.

- In bkd_rclone_part1 we validate the new URL and return an error
  message if the destination side can't contact the same BAM server.
  If the new server URL is invalid then an error is returned and the
  user is instructed to use the new -B option to pass the desired
  server URL.  Use '-B none' to create a standalone repo, or '-B .' to
  create a new BAM server.

bk bam server URL

- The new bam server comment sets the URL for the current repository.
  Currently the only validation is that the new URL is reachable.  The
  user will have to deal with switching URLs to a new server that is
  missing some data.  ('bk bam server -r' will delete the current URL)

(older stale data in src/Notes/binpool)