colo - Work with colocated branches using current technology

Version 0.2.1
Branch lp:bzr-colo
Home page https://launchpad.net/bzr-colo
Owner nmb
GNU/Linux Yes
Windows Yes
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
  • qbranches (if the qbzr plugin is installed)
  • colo-fetch
  • colo-pull
  • colo-checkout
  • colo-prune
  • qprune (if the qbzr plugin is installed)
  • colo-mv
  • colo-clean
  • colo-ify
  • colo-fixup
  • colo-sync-from
  • colo-sync-to

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. (If hierarchical branch names such as bugs/1024 are used, then simply doing bzr switch trunk may fail, while bzr switch colo:trunk will always work.)

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-checkout

Purpose

Create a checkout of this branch in a new directory.

Usage

bzr colo-checkout TO_DIRECTORY

Options

-v, --verbose Display more information.
-b, --create Also create a new colocated branch by this name
-q, --quiet Only display errors and warnings.
--from-branch=ARG
 name of the branch to branch from
--usage Show usage message and options.
-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.

Aliases

colo-co

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-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 “origin/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).
--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.
--git GIT repository.
--git-bare Bare GIT repository (no working tree).
--hg Mercurial repository.
–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.

Description

This creates a colocated workspace at the specified location with a single branch named “origin/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. If you don’t specify a TO_LOCATION, then one will be derived from the final component of the FROM_LOCATION (similar to bzr branch.

colo-fixup

Purpose

Fix the checkout reference after moving a colocated workspace.

Usage

bzr colo-fixup

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

Because Bazaar uses absolute pathnames in storing references to branches, when a colocated workspace is moved on disk, the link from the checkout to the current branch gets broken. This command uses a simple heuristic to try to fix that reference. If it doesn’t work, then the command bzr switch --force .bzr/branches/<current branch name> will always work.

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

--trunk-name=ARG
 Name for the trunk branch
-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.
--no-tree Create a workspace without a working tree
-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).
--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.
--git GIT repository.
--git-bare Bare GIT repository (no working tree).
--hg Mercurial repository.
–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.

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.

By default, the initial branch is called “trunk”. A different name can be specified with the –trunk-name option. For creating colocated workspaces remotely, a –no-tree options is available for situations where it isn’t possible or desired to create a working tree.

colo-mv

Purpose

Rename a colocated branch.

Usage

bzr colo-mv OLDNAME NEWNAME

Options

--usage Show usage message and options.
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
-h, --help Show help message.

Aliases

colo-move, colo-rename

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.

Aliases

colo-delete

See also

colo-clean

colo-pull

Purpose

Update all remote branches.

Usage

bzr colo-pull

Options

--usage Show usage message and options.
-d ARG, --directory=ARG
 colocated workspace to use
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
-h, --help Show help message.

Description

A remote branch is one whose name starts with “origin/”. This command updates all such branches by doing a pull from their default pull location. To set this location, do bzr switch colo:origin/branch_name and bzr pull --remember URL.

colo-sync-from

Purpose

Synchronize this colocated workspace from the state of another one.

Usage

bzr colo-sync-from [LOCATION]

Options

--remember Remember the specified location as a default.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
--usage Show usage message and options.
--overwrite Ignore differences between branches and overwrite unconditionally
-v, --verbose Display more information.

Description

LOCATION should be a path or URL to a colocated workspace such that the branches it holds are accessible as colo:LOCATION:branch_name. For every branch in that remote workspace, if there is a local branch with the same name, the remote branch is pulled into the corresponding local branch. If there is not a local branch with a name, then a new branch is created in the local colocated workspace.

The first time colo-sync-from is used, it records a default location so that future synchronizations can just use “bzr colo-sync-from”. To change the saved synchronization location, use the “–remember” option.

colo-sync-to

Purpose

Synchronize this colocated workspace to another one.

Usage

bzr colo-sync-to [LOCATION]

Options

--remember Remember the specified location as a default.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
--usage Show usage message and options.
--overwrite Ignore differences between branches and overwrite unconditionally.
-v, --verbose Display more information.

Description

LOCATION should be a path or URL for a colocated workspace. The branches in the current workspace are pushed to the specified remote workspace. If that path does not already contain matching branches, they will be created.

The first time colo-sync-to is used, it records a default location so that future synchronizations can just use “bzr colo-sync-to”. To change the saved synchronization location, use the “–remember” option.

qbranches

Purpose

List colocated branches.

Usage

bzr qbranches

Options

--usage Show usage message and options.
-d ARG, --directory=ARG
 location of colocated workspace
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
-h, --help Show help message.

Description

The current branch is marked in bold.

qprune

Purpose

Remove colocated branches.

Usage

bzr qprune

Options

--usage Show usage message and options.
-d ARG, --directory=ARG
 location of colocated workspace
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
-h, --help Show help message.