Rev 2944: initial cut of userdoc for knitpack repositories (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Oct 26 00:28:37 BST 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 2944
revision-id: pqm at pqm.ubuntu.com-20071025232834-wcuoh6azwgez5b80
parent: pqm at pqm.ubuntu.com-20071025211612-mmsxejad9v1cu5c3
parent: ian.clatworthy at internode.on.net-20071025224428-035yah62rln0fhz5
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2007-10-26 00:28:34 +0100
message:
initial cut of userdoc for knitpack repositories (Ian Clatworthy)
modified:
doc/developers/knitpack.txt knitpack.txt-20071023074744-q0g5u8me8gk5zbtb-1
------------------------------------------------------------
revno: 2943.1.1
merged: ian.clatworthy at internode.on.net-20071025224428-035yah62rln0fhz5
parent: pqm at pqm.ubuntu.com-20071025211612-mmsxejad9v1cu5c3
parent: ian.clatworthy at internode.on.net-20071025224202-fdcohsk9sw2qfvnn
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: ianc-integration
timestamp: Fri 2007-10-26 08:44:28 +1000
message:
initial cut of userdoc for knitpack repositories (Ian Clatworthy)
------------------------------------------------------------
revno: 2940.2.3
merged: ian.clatworthy at internode.on.net-20071025224202-fdcohsk9sw2qfvnn
parent: ian.clatworthy at internode.on.net-20071025112358-7mn6oazh0bv5fqqi
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.pack-doc
timestamp: Fri 2007-10-26 08:42:02 +1000
message:
more feedback from lifeless
------------------------------------------------------------
revno: 2940.2.2
merged: ian.clatworthy at internode.on.net-20071025112358-7mn6oazh0bv5fqqi
parent: ian.clatworthy at internode.on.net-20071025104927-1vr2io7wlg1m8qxq
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.pack-doc
timestamp: Thu 2007-10-25 21:23:58 +1000
message:
review feedback from lifeless
------------------------------------------------------------
revno: 2940.2.1
merged: ian.clatworthy at internode.on.net-20071025104927-1vr2io7wlg1m8qxq
parent: pqm at pqm.ubuntu.com-20071025022746-ftudwmzir8v2lccc
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.pack-doc
timestamp: Thu 2007-10-25 20:49:27 +1000
message:
initial user doc for KnitPack repositories
=== modified file 'doc/developers/knitpack.txt'
--- a/doc/developers/knitpack.txt 2007-10-24 02:14:11 +0000
+++ b/doc/developers/knitpack.txt 2007-10-25 22:42:02 +0000
@@ -1,6 +1,147 @@
+==========================
KnitPack repository format
==========================
+.. contents::
+
+Using KnitPack repositories
+===========================
+
+Motivation
+----------
+
+KnitPack is a new repository format for Bazaar, which is expected to be
+faster both locally and over the network, is usually more compact, and
+will work with more FTP servers.
+
+Our benchmarking results to date have been very promising. We fully expect
+to make a pack-based format the default in the near future. We would
+therefore like as many people as possible using KnitPack repositories,
+benchmarking the results and telling us where improvements are still needed.
+
+Preparation
+-----------
+
+A small percentage of existing repositories may have some inconsistent
+data within them. It's is a good idea to check the integrity of your
+repositories before migrating them to knitpack format. To do this, run::
+
+ bzr check
+
+If that reports a problem, run this command::
+
+ bzr reconcile
+
+Note that this can take many hours for repositories with deep history
+so be sure to set aside some time for this if it is required.
+
+Creating a new knitpack branch
+------------------------------
+
+If you're starting a project from scratch, it's easy to make it a
+``knitpack`` one. Here's how::
+
+ cd my-stuff
+ bzr init --knitpack-experimental
+ bzr add
+ bzr commit -m "initial import"
+
+In other words, use the normal sequence of commands but add the
+``--knitpack-experimental`` option to the ``init`` command.
+
+Creating a new knitpack repository
+----------------------------------
+
+If you're starting a project from scratch and wish to use a shared repository
+for branches, you can make it a ``knitpack`` repository like this::
+
+ cd my-repo
+ bzr init-repo --knitpack-experimental .
+ cd my-stuff
+ bzr init
+ bzr add
+ bzr commit -m "initial import"
+
+In other words, use the normal sequence of commands but add the
+``--knitpack-experimental`` option to the ``init-repo`` command.
+
+Upgrading an existing branch or repository to knitpack format
+-------------------------------------------------------------
+
+If you have an existing branch and wish to migrate it to
+a ``knitpack`` format, use the ``upgrade`` command like this::
+
+ bzr upgrade --knitpack-experimental path-to-my-branch
+
+If you are using a shared repository, run::
+
+ bzr upgrade --knitpack-experimental ROOT_OF_REPOSITORY
+
+to upgrade the history database. Note that this will not
+alter the branch format of each branch, so
+you will need to also upgrade each branch individually
+if you are upgrading from an old (e.g. < 0.17) bzr.
+More modern bzr's will already have the branch format at
+our latest branch format which adds support for tags.
+
+Starting a new knitpack branch from one in an older format
+----------------------------------------------------------
+
+This can be done in one of several ways:
+
+1. Create a new branch and pull into it
+2. Create a standalone branch and upgrade its format
+3. Create a knitpack shared repository and branch into it
+
+Here are the commands for using the ``pull`` approach::
+
+ bzr init --knitpack-experimental my-new-branch
+ cd my-new-branch
+ bzr pull my-source-branch
+
+Here are the commands for using the ``upgrade`` approach::
+
+ bzr branch my-source-branch my-new-branch
+ cd my-new-branch
+ bzr upgrade --knitpack-experimental .
+
+Here are the commands for the shared repository approach::
+
+ cd my-repo
+ bzr init-repo --knitpack-experimental .
+ bzr branch my-source-branch my-new-branch
+ cd my-new-branch
+
+As a reminder, any of the above approaches can fail if the source branch
+has inconsistent data within it and hasn't been reconciled yet. Please
+be sure to check that before reporting problems.
+
+Testing packs for bzr-svn users
+-------------------------------
+
+If you are using ``bzr-svn`` or are testing the prototype subtree support,
+you can still use and assist in testing KnitPacks. The commands to use
+are identical to the ones given above except that the name of the format
+to use is ``knitpack-subtree-experimental``.
+
+WARNING: Note that the subtree formats, ``distate-subtree`` and
+``knitpack-subtree-experimental``, are **not** production strength yet and
+may cause unexpected problems. They are required for the bzr-svn
+plug-in but should otherwise ony be used by people happy to live on the
+bleeding edge. If you are using bzr-svn, you're on the bleeding edge anyway.
+:-)
+
+Reporting problems
+------------------
+
+If you need any help or encounter any problems, please contact the developers
+via the usual ways, i.e. chat to us on IRC or send a message to our mailing
+list. See http://bazaar-vcs.org/BzrSupport for contact details.
+
+
+Technical notes
+===============
+
Bazaar 0.92 adds a new format (experimental at first) implemented in
``bzrlib.repofmt.pack_repo.py``.
More information about the bazaar-commits
mailing list