Repository and branch format descriptions - bug 264730
John Arbash Meinel
john at arbash-meinel.com
Wed Dec 10 16:13:54 GMT 2008
-----BEGIN PGP SIGNED MESSAGE-----
> So, would it be appropriate, from Bazaar's POV, to rewrite the
> pack_repo.py strings? Or should I write my own versions of them for
> the Launchpad web UI? I'd rather do the former because I have a
> suspicion that it'd be useful to Bazaar users as well as people using
The strings are not just in pack_repo.py, they are also in knit_repo.py
and a few other places. Certainly pack_repo.py has the more common ones,
There are 2 strings to be aware of.
1) 'get_format_string()' do *NOT* touch these. This is what we write
(and read) from disk to indicate the format.
2) 'get_format_description()' this can be modified as we see fit, as
they are meant for display to the user.
At the moment, they are only displayed to the user when they run "bzr
info -v". And that code expects them to be single-line strings.
I think it would be fine for them to be a little bit more verbose, but
if you find you need more than one line, we need to update the "info"
code to support that.
> Either way, I'd be grateful for any help in making sense of the
> existing strings and looking at how we can make them more useful.
The basic flow of repository formats is:
Flat really-really-really old (0.0.7, IIRC)
Weave pre 0.8.2
Knit From 0.8.2 -> 0.92, stores the history of each file in a
Pack 0.92 => present, clusters the histories of all files together in
a 'pack'. Allows us to request the texts for multiple files at
the same time, etc.
There are some optional features on the repositories. Mostly this is
just a flag to indicate compatibility.
(none) The default
rich-root Support versioning the root directory as an real entity.
subtree (beta) Includes rich-root, and the ability to version a
reference to an external tree. (nested trees, similar to
There are also other features which are incompatible with older clients,
so we have to introduce a new format, just to make sure older clients
don't try to access the data incorrectly.
stacking Added in 1.6, allows a Branch to indicate that there is
another repository that can be used to access more data
that is not present locally.
btree Added in 1.9. an one improvement to our pack index
layer. Changing from a plain "sorted list" file that we
bisect into, into a "btree" index. Uses compressed
fixed-length pages, and a btree, which allows for
smaller indexes, and much better specificity when
searching for a small number of records. (log2(N) versus
log100(N)) Also has better work on when to cache, what
requests to expand, etc.
Things get a little cluttered, because Branches also have a few formats,
and WorkingTrees do as well. And at the moment, our UI tries to present
a single name for various composites of these.
Branch5 Has a revision-history file, which holds all mainline
revisions. (does not scale well with long-lived
Branch6 Changes to use a branch.conf file to collect
meta-information together in one file, rather than
Also only contains a "last-revision" file, which points
at the revno & revision_id of the tip of the branch.
Branch7 Used to enable stacking. Exists so that older clients
that cannot handle stacking, don't try to access the
WorkingTree2 Pre 0.8.2, stores the working-tree state as an XML file
WorkingTree3 0.8.2 => 0.15, pre 'dirstate', stores the state in the
same way, just in a slightly different location.
WorkingTree4 'dirstate'. Stores the state as a custom-serialized
file. Which also combines the previous state "inline".
Makes accessing current + base information for a single
record easier (locality of reference).
> I've been reading through http://bazaar-vcs.org/BazaarFormats and that
> helps to some extent - in particular the Weave and Knit pages - but it
> appears the page is not comprehensive.
> Thanks :)
So getting back to the Repository formats, we should have:
Knit1 Plain knit format repository
Knit2 Doesn't seem to exist... ??
Knit3 Knit format + subtree support (developmental)
Knit4 Knit format + 'rich-root' (--rich-root)
KnitPack1 Plain pack format repository (--pack-0.92)
KnitPack3 Pack + subtree (--pack-0.92-subtree)
KnitPack4 Pack + rich-root (--rich-root-pack)
KnitPack5 Pack + stacking (--1.6)
KnitPack5RRoot Pack + rich-root (--1.6.1-rich-root)
KnitPack5RRootBroken was the rich root format released in 1.6, but
did not use the right serializers, etc. Unlikely
that anyone is actually using it anymore
KnitPack6 Pack + stacking + btree (--1.9)
KnitPack6RRoot Pack + stacking + btree + rich-root (--1.9-rich-root)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
-----END PGP SIGNATURE-----
More information about the bazaar