Merge lp:~nmb/bzr-alldocs/add-colo into lp:bzr-alldocs

[Neil Martinsen-Burrell]

[Neil Martinsen-Burrell (nmb)]

This adds the colo plugin to the registry and to the Plugin Guide. The initial release of this plugin will happen shortly.

[Ian Clatworthy (ian-clatworthy)]

This looks good. Please merge.

review: Approve

=== modified file 'plugins-registry.ini'
--- plugins-registry.ini	2009-12-11 13:19:26 +0000
+++ plugins-registry.ini	2010-01-11 02:55:21 +0000
@@ -126,6 +126,12 @@
 platform.mac-osx = True
 wiki.description = Submit commits to [[http://cia.vc/|CIA]]
 
+[plugin colo]
+purpose = Work with colocated branches using current technology
+link.branch = lp:bzr-colo
+owner = nmb
+platform.mac-osx = True
+
 [plugin colocated]
 purpose = Colocated branches support (aka git-style branches)
 link.branch = http://people.samba.org/bzr/jelmer/bzr-colocated/trunk
 
=== added file 'plugins/en/colo-plugin.txt'
--- plugins/en/colo-plugin.txt	1970-01-01 00:00:00 +0000
+++ plugins/en/colo-plugin.txt	2010-01-11 02:55:21 +0000
@@ -0,0 +1,419 @@
+``colo`` - Work with colocated branches using current technology
+================================================================
+
+================ ============================================================
+Version          0.0.1                                                       
+Branch           `lp:bzr-colo <https://code.launchpad.net/bzr-colo>`_        
+Home page        `<https://launchpad.net/bzr-colo>`_                         
+Owner            `nmb <https://launchpad.net/~nmb>`_                         
+GNU/Linux        Maybe (please test)                                         
+Windows          Maybe (please test)                                         
+Mac OS X         Yes                                                         
+================ ============================================================
+
+Work with colocated branches using current technology.
+
+In order to provide a faster and simpler working model, this plugin tries
+to support a configuration similar to git and Mercurial's colocated branches,
+where there is a single working tree that can be switched between multiple
+branches that all co-exist in the same directory.  This working model is
+entirely possible using Bazaar's existing technology, and this plugin aims to
+make it as simple as possible to use that model.  
+
+This plugin does not add any new formats or objects to Bazaar, it simply
+provides convenience commands for working with a certain *convention* for
+branch storage.  This plugin provides the following commands
+
+    * colo-init
+    * colo-branch
+    * colo-branches
+    * colo-fetch
+    * colo-clone
+    * colo-prune
+    * colo-clean
+    * colo-ify
+
+For more information on working with this plugin, see ``bzr help
+colo-tutorial`` and the help for the individual commands.
+
+Referring to Colocated Branches
+-------------------------------
+
+This plugin adds a directory service of "colo:" that can be used to
+refer to branches inside of the ``.bzr/branches`` directory.  So, for example
+we could ``bzr switch colo:fix-eol-bug`` to do work in the colocated
+``fix-eol-bug`` branch.  Note that in some cases, the "colo:" prefix is
+unnecessary because Bazaar automatically looks for branches in the directory
+where the current branch is located.  So the previous command would also work
+with ``bzr switch fix-eol-bug`` because switch searches sibling directories 
+automatically.
+
+From within a colocated workspace, the specifier ``colo:branch_name`` refers
+to the branch with that name in the current colocated workspace.  It is
+possible to refer to colocated branches in *other* workspaces using the syntax
+``colo:workspace_location:branch_name``.  The ``workspace_location`` in this
+form can be either a path (e.g. ``colo:../other_project:trunk``) or a URL
+(e.g. ``colo:bzr+ssh://hostname/path/to/workspace:trunk``).
+
+
+
+colo-branch
+-----------
+
+**Purpose**
+
+Make a new branch from the currently active branch.
+
+**Usage**
+
+bzr colo-branch NEW_BRANCH
+
+**Options**
+
+
+--no-switch           Don't switch the workspace to the new branch
+-v, --verbose         Display more information.
+-h, --help            Show help message.
+-q, --quiet           Only display errors and warnings.
+--from-branch=ARG     name of the branch to branch from
+--usage               Show usage message and options.
+-r ARG, --revision=ARG
+                      See "help revisionspec" for details.
+
+
+**Description**
+
+In a colocated workspace, there is always one branch active at a time,
+so to create a new branch, we need to only specify the name of the new
+branch.  If the ``-r`` option is given, then the branch is made from
+the specified revision of the current branch.  By default, the branch
+is made from the current branch, but a different branch name to branch
+from can be specified with the ``--from-branch`` option.
+
+colo-branches
+-------------
+
+**Purpose**
+
+List all of the branches in a colocated workspace.
+
+**Usage**
+
+bzr colo-branches [LOCATION]
+
+**Options**
+
+
+--usage        Show usage message and options.
+-v, --verbose  Display more information.
+-q, --quiet    Only display errors and warnings.
+-h, --help     Show help message.
+
+
+**Description**
+
+If the current directory is a working tree pointing to one of the branches,
+that branch is marked with a "*".
+
+colo-clean
+----------
+
+**Purpose**
+
+Clean unused revisions from the repository.
+
+**Usage**
+
+bzr colo-clean
+
+**Options**
+
+
+--usage        Show usage message and options.
+-v, --verbose  Display more information.
+-q, --quiet    Only display errors and warnings.
+-h, --help     Show help message.
+
+
+**Description**
+
+An unused revision is one that is not in the ancestry of any of the 
+active branches in the workspace.  This command can be used after the
+``colo-prune`` command to remove revisions that were only present in
+the branch that was pruned.
+
+colo-clone
+----------
+
+**Purpose**
+
+Create a checkout of this branch in a new directory.
+
+**Usage**
+
+bzr colo-clone TO_DIRECTORY
+
+**Options**
+
+
+--usage        Show usage message and options.
+--create       Also create a new colocated branch by this name
+-v, --verbose  Display more information.
+-q, --quiet    Only display errors and warnings.
+-h, --help     Show help message.
+
+
+**Description**
+
+By default this command makes a new checkout of the current branch in
+the specified directory.  Using the ``--create`` option, a new branch
+named after the last component of the new directory is created, and
+the new checkout is switched to that new branch.
+
+colo-fetch
+----------
+
+**Purpose**
+
+Fetch an external project into a new colocated workspace.
+
+**Usage**
+
+bzr colo-fetch FROM_LOCATION [TO_LOCATION]
+
+**Options**
+
+
+--trunk-name=ARG      Name of the branch to create; default is "trunk"
+-v, --verbose         Display more information.
+--create-prefix       Create the path leading up to the location if it does
+                      not already exist.
+-q, --quiet           Only display errors and warnings.
+--usage               Show usage message and options.
+-h, --help            Show help message.
+
+Storage Format:
+  --format=ARG        Specify a format for the repository, etc. See "help
+                      formats".
+  --1.14              A working-tree format that supports content filtering.
+  --1.14-rich-root    A variant of 1.14 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --1.6               A format that allows a branch to indicate that there
+                      is another (stacked) repository that should be used to
+                      access data that is not present locally.
+  --1.6.1-rich-root   A variant of 1.6 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --1.9               A repository format using B+tree indexes. These
+                      indexes are smaller in size, have smarter caching and
+                      provide faster performance for most operations.
+  --1.9-rich-root     A variant of 1.9 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --2a                First format for bzr 2.0 series. Uses group-compress
+                      storage. Provides rich roots which are a one-way
+                      transition.
+  --default           First format for bzr 2.0 series. Uses group-compress
+                      storage. Provides rich roots which are a one-way
+                      transition.
+  --default-rich-root
+                      Same as 2a.
+  --development-rich-root
+                      Current development format. Supports rich roots. Can
+                      convert data to and from rich-root-pack (and anything
+                      compatible with rich-root-pack) format repositories.
+                      Repositories and branches in this format can only be
+                      read by bzr.dev. Please read http://doc.bazaar-
+                      vcs.org/latest/developers/development-repo.html before
+                      use.
+  --development-subtree
+                      Current development format, subtree variant. Can
+                      convert data to and from pack-0.92-subtree (and
+                      anything compatible with pack-0.92-subtree) format
+                      repositories. Repositories and branches in this format
+                      can only be read by bzr.dev. Please read http://doc
+                      .bazaar-vcs.org/latest/developers/development-
+                      repo.html before use.
+  --dirstate          New in 0.15: Fast local operations. Compatible with
+                      bzr 0.8 and above when accessed over the network.
+  --dirstate-tags     New in 0.15: Fast local operations and improved
+                      scaling for network operations. Additionally adds
+                      support for tags. Incompatible with bzr < 0.15.
+  --knit              Format using knits.  Recommended for interoperation
+                      with bzr <= 0.14.
+  --metaweave         Transitional format in 0.8.  Slower than knit.
+  --pack-0.92         New in 0.92: Pack-based format with data compatible
+                      with dirstate-tags format repositories. Interoperates
+                      with bzr repositories before 0.92 but cannot be read
+                      by bzr < 0.92. Previously called knitpack-
+                      experimental.  For more information, see http://doc
+                      .bazaar-vcs.org/latest/developers/packrepo.html.
+  --rich-root         New in 1.0.  Better handling of tree roots.
+                      Incompatible with bzr < 1.0.
+  --rich-root-pack    New in 1.0: A variant of pack-0.92 that supports rich-
+                      root data (needed for bzr-svn and bzr-git).
+  --weave             Pre-0.8 format.  Slower than knit and does not support
+                      checkouts or shared repositories.
+
+
+**Description**
+
+This creates a colocated workspace at the specified location (the default
+is the current directory) with a single branch named "trunk" that has
+the contents of the external project.  If you would like to specify a
+different name for the new branch, use the ``--trunk-name`` option.
+
+colo-ify
+--------
+
+**Purpose**
+
+Convert an existing branch into a colocated workspace.
+
+**Usage**
+
+bzr colo-ify [OTHER_LOCATION...]
+
+**Options**
+
+
+--usage           Show usage message and options.
+--trunk-name=ARG  The name to use for this branch in the colocated workspace
+-v, --verbose     Display more information.
+-q, --quiet       Only display errors and warnings.
+-h, --help        Show help message.
+
+
+**Description**
+
+This converts an existing branch into a colocated workspace.  Other
+branches can be added to the workspace by giving them as arguments.  The
+names of the other branches will be determined from their nicknames.  To
+use a different name for the current branch in the colocated workspace,
+use the ``--trunk-name`` option.
+
+**See also**
+
+nick
+
+colo-init
+---------
+
+**Purpose**
+
+Create a working tree with colocated branches.
+
+**Usage**
+
+bzr colo-init [LOCATION]
+
+**Options**
+
+
+-v, --verbose         Display more information.
+--create-prefix       Create the path leading up to the location if it does
+                      not already exist.
+-q, --quiet           Only display errors and warnings.
+--usage               Show usage message and options.
+-h, --help            Show help message.
+
+Storage Format:
+  --format=ARG        Specify a format for the repository, etc. See "help
+                      formats".
+  --1.14              A working-tree format that supports content filtering.
+  --1.14-rich-root    A variant of 1.14 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --1.6               A format that allows a branch to indicate that there
+                      is another (stacked) repository that should be used to
+                      access data that is not present locally.
+  --1.6.1-rich-root   A variant of 1.6 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --1.9               A repository format using B+tree indexes. These
+                      indexes are smaller in size, have smarter caching and
+                      provide faster performance for most operations.
+  --1.9-rich-root     A variant of 1.9 that supports rich-root data (needed
+                      for bzr-svn and bzr-git).
+  --2a                First format for bzr 2.0 series. Uses group-compress
+                      storage. Provides rich roots which are a one-way
+                      transition.
+  --default           First format for bzr 2.0 series. Uses group-compress
+                      storage. Provides rich roots which are a one-way
+                      transition.
+  --default-rich-root
+                      Same as 2a.
+  --development-rich-root
+                      Current development format. Supports rich roots. Can
+                      convert data to and from rich-root-pack (and anything
+                      compatible with rich-root-pack) format repositories.
+                      Repositories and branches in this format can only be
+                      read by bzr.dev. Please read http://doc.bazaar-
+                      vcs.org/latest/developers/development-repo.html before
+                      use.
+  --development-subtree
+                      Current development format, subtree variant. Can
+                      convert data to and from pack-0.92-subtree (and
+                      anything compatible with pack-0.92-subtree) format
+                      repositories. Repositories and branches in this format
+                      can only be read by bzr.dev. Please read http://doc
+                      .bazaar-vcs.org/latest/developers/development-
+                      repo.html before use.
+  --dirstate          New in 0.15: Fast local operations. Compatible with
+                      bzr 0.8 and above when accessed over the network.
+  --dirstate-tags     New in 0.15: Fast local operations and improved
+                      scaling for network operations. Additionally adds
+                      support for tags. Incompatible with bzr < 0.15.
+  --knit              Format using knits.  Recommended for interoperation
+                      with bzr <= 0.14.
+  --metaweave         Transitional format in 0.8.  Slower than knit.
+  --pack-0.92         New in 0.92: Pack-based format with data compatible
+                      with dirstate-tags format repositories. Interoperates
+                      with bzr repositories before 0.92 but cannot be read
+                      by bzr < 0.92. Previously called knitpack-
+                      experimental.  For more information, see http://doc
+                      .bazaar-vcs.org/latest/developers/packrepo.html.
+  --rich-root         New in 1.0.  Better handling of tree roots.
+                      Incompatible with bzr < 1.0.
+  --rich-root-pack    New in 1.0: A variant of pack-0.92 that supports rich-
+                      root data (needed for bzr-svn and bzr-git).
+  --weave             Pre-0.8 format.  Slower than knit and does not support
+                      checkouts or shared repositories.
+
+
+**Description**
+
+A colocated workspace is a working tree that also contains all of its
+branches within the same directory.  The branches are stored in the
+.bzr/branches subdirectory.  They may be easily referred to using the 
+colo: specifier.
+
+colo-prune
+----------
+
+**Purpose**
+
+Remove a branch from the colocated workspace.
+
+**Usage**
+
+bzr colo-prune [BRANCH...]
+
+**Options**
+
+
+--usage        Show usage message and options.
+-v, --verbose  Display more information.
+-q, --quiet    Only display errors and warnings.
+--clean        Clean the repository after pruning.
+-h, --help     Show help message.
+
+
+**Description**
+
+This commands removes the specified branches from the colocated workspace
+by removing them from the filesystem.  By default, it does not remove the
+revisions from the shared repository.  If it is desired to remove the
+revisions that are only present in the removed branches, then the
+``--clean`` option may be given.
+
+**See also**
+
+colo-clean
+
 
=== modified file 'plugins/en/index.txt'
--- plugins/en/index.txt	2009-12-11 13:19:26 +0000
+++ plugins/en/index.txt	2010-01-11 02:55:21 +0000
@@ -121,6 +121,7 @@
    automv-plugin
    bookmarks-plugin
    bzrtools-plugin
+   colo-plugin
 
 
 Foreign branches