pipeline - Work on large changes as smaller pieces

Version 1.1.0
Branch lp:bzr-pipeline
Home page http://bazaar-vcs.org/BzrPipeline
Owner abentley
GNU/Linux Yes
Windows Yes
Mac OS X Yes

Manage a series of branches as a pipeline.

Here is a summary of the commands added.

Command Description
reconfigure-pipeline Reconfigure a tree with branch into a lightweight checkout of a pipe.
add-pipe Add a pipe to the pipeline
remove-pipe Remove a pipe from the pipeline
switch-pipe Switch from one pipe to another
show-pipeline Show the current pipeline
pump From this pipe onward, merge all pipes into their next pipe and commit
sync-pipeline Synchronise the contents of this pipeline with another copy
pipe-patches Export the pipeline as a collection of patches, one per pipe

It also extends merge –uncommitted to work with pipes.

To get started, create a branch and lightweight checkout:

bzr init pipe1
bzr checkout --lightweight pipe1 tree
cd tree
commit -m "first commit"
bzr add-pipe pipe2
bzr show-pipeline

If you have an existing tree that you wish to start using as a pipeline, use reconfigure-pipeline to convert it.

The switch-pipe command, in addition to the normal switch behavour, stores any uncommitted changes to the source pipe, and restores any uncommitted changes in the target pipe. This supports a common need to switch between several related tasks without committing.

The pump command merges and commits changes along the pipeline, starting with the current pipe. For example:

bzr add-pipe next
echo "hello" > new
bzr add
bzr commit -m "Added file new"
bzr pump

This will commit a revision to the pipe named “next” that adds the file “new”.

Each pipe is identified by its branch nick. The location of each pipe is provided as a location alias, which consists of “:pipe:” followed by its nick. So, to switch to pipe named “my-new” using the standard switch command:

bzr switch :pipe:my-new

The aliases :prev and :next refer to the pipe before and after the current pipe, respectively. So to see the changes added in this pipe:

bzr diff -rancestor::prev

These aliases work virtually everywhere you can specify a branch. Since pipes are branches, you can do anything with them that you could do with a branch.

You might find the following command aliases useful:

# Abbreviate switching to next pipe
next = switch-pipe :next

# Abbreviate switching to previous pipe
prev = switch-pipe :prev

# Show diff of changes originated in this pipe
pdiff = diff -r ancestor::prev

# Show status for changes originated in this pipe
pstatus = status --short -r branch::prev

# Submit the changes originated in this pipe for merging
psend = send -r ancestor::prev..

# Show commits which have not been pumped into the next pipe yet.
unpumped = missing --mine :next

For more information on bzr-pipeline, see the home page: http://bazaar-vcs.org/BzrPipeline.

add-pipe

Purpose

Add a pipe to the pipeline.

Usage

bzr add-pipe PIPE [NEIGHBOUR]

Options

--no-switch Do not switch to new pipe.
-v, --verbose Display more information.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
-d ARG, --directory=ARG
 Directory of the pipe to add to, rather than the one for the working directory.
--usage Show usage message and options.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-i, --interactive
 Interactively decide which changes to place in the new pipe.
position:
--after Insert after the selected pipe.
--before Insert before the selected pipe.

Description

By default, the pipe is added after the current active pipe, at the current revision.

This command can be used to start a new pipeline.

merge

Purpose

Perform a three-way merge.

Usage

bzr merge [LOCATION]

Options

--pull If the destination is already completely merged into the source, pull from the source rather than merging. When this happens, you do not need to commit the result.
--remember Remember the specified location as a default.
-i, --interactive
 Select changes interactively.
--force Merge even if the destination tree has uncommitted changes.
-v, --verbose Display more information.
--reprocess Reprocess to reduce spurious conflicts.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
-d ARG, --directory=ARG
 Branch to merge into, rather than the one containing the working directory.
--uncommitted Apply uncommitted changes from a working copy, instead of branch changes.
--usage Show usage message and options.
--show-base Show base revision text in conflicts.
--preview Instead of merging, show a diff of the merge.
-c ARG, --change=ARG
 Select changes introduced by the specified revision. See also “help revisionspec”.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
Merge algorithm:
--merge-type=ARG
 Select a particular merge algorithm.
--diff3 Merge using external diff3
--lca LCA-newness merge
--merge3 Native diff3-style merge
--weave Weave-based merge

Description

The source of the merge can be specified either in the form of a branch, or in the form of a path to a file containing a merge directive generated with bzr send. If neither is specified, the default is the upstream branch or the branch most recently merged using –remember.

When merging from a branch, by default bzr will try to merge in all new work from the other branch, automatically determining an appropriate base revision. If this fails, you may need to give an explicit base.

To pick a different ending revision, pass “–revision OTHER”. bzr will try to merge in all new work up to and including revision OTHER.

If you specify two values, “–revision BASE..OTHER”, only revisions BASE through OTHER, excluding BASE but including OTHER, will be merged. If this causes some revisions to be skipped, i.e. if the destination branch does not already contain revision BASE, such a merge is commonly referred to as a “cherrypick”.

Revision numbers are always relative to the source branch.

Merge will do its best to combine the changes in two branches, but there are some kinds of problems only a human can fix. When it encounters those, it will mark a conflict. A conflict means that you need to fix something, before you should commit.

Use bzr resolve when you have fixed a problem. See also bzr conflicts.

If there is no default branch set, the first merge will set it. After that, you can omit the branch to use the default. To change the default, use –remember. The value will only be saved if the remote location can be accessed.

The results of the merge are placed into the destination working directory, where they can be reviewed (with bzr diff), tested, and then committed to record the result of the merge.

merge refuses to run if there are any uncommitted changes, unless –force is given. The –force option can also be used to create a merge revision which has more than two parents.

If one would like to merge changes from the working tree of the other branch without merging any committed revisions, the –uncommitted option can be given.

To select only some changes to merge, use “merge -i”, which will prompt you to apply each diff hunk and file change, similar to “shelve”.

Examples

To merge all new revisions from bzr.dev:

bzr merge ../bzr.dev

To merge changes up to and including revision 82 from bzr.dev:

bzr merge -r 82 ../bzr.dev

To merge the changes introduced by 82, without previous changes:

bzr merge -r 81..82 ../bzr.dev

To apply a merge directive contained in /tmp/merge:

bzr merge /tmp/merge

To create a merge revision with three parents from two branches feature1a and feature1b:

bzr merge ../feature1a bzr merge ../feature1b –force bzr commit -m ‘revision with three parents’

See also

remerge, send, status-flags, update

pipe-patches

Purpose

Export the pipeline as a collection of patches, one per pipe.

Usage

bzr pipe-patches [PATCH_LOCATION]

Options

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

Description

The patch name begins with a sequence number, and ends with the pipe name.

pump

Purpose

From this pipe onward, merge all pipes into their next pipe and commit.

Usage

bzr pump

Options

--from=ARG Pump start. May be a pipe or a non-pipe.
-v, --verbose Display more information.
--reprocess Reprocess to reduce spurious conflicts.
-q, --quiet Only display errors and warnings.
--from-submit Start from the first pipe’s submit branch.
-d ARG, --directory=ARG
 Directory in the pipeline to pump from.
--usage Show usage message and options.
--show-base Show base revision text in conflicts.
-h, --help Show help message.
Merge algorithm:
--merge-type=ARG
 Select a particular merge algorithm.
--diff3 Merge using external diff3
--lca LCA-newness merge
--merge3 Native diff3-style merge
--weave Weave-based merge

Description

If the merge is successful, the changes are automatically committed, and the process repeats for the next pipe. Eventually, the last pipe will have all the changes from all of the affected pipes. On success, the checkout’s initial state is restored.

If the merge produces conflicts, the process aborts and no commit is performed. You should resolve the conflicts, commit, and re-run pump.

–from may be a pipe, in which case the pumping starts at the specified pipe, or it may be a branch, in which case the branch will be pumped into the first pipe.

reconfigure-pipeline

Purpose

Reconfigure a tree with branch into a lightweight checkout of a pipe.

Usage

bzr reconfigure-pipeline

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

The pipeline will be stored in a new “pipes” subdirectory of .bzr.

This is suitable if you have a standalone tree, but if you have a shared repository with its own organization scheme already, it’s probably better to just create a lightweight checkout.

remove-pipe

Purpose

Remove a pipe from the pipeline.

Usage

bzr remove-pipe [PIPE]

Options

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

Description

By default, the current pipe is removed, but a pipe may be specified as the first parameter. By default, only the association of the pipe with its pipeline is removed, but if –branch is specified, the branch is also deleted.

rename-pipe

Purpose

Rename a pipe to a different name.

Usage

bzr rename-pipe NEW_NAME

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

This will rename the branch directory and update the pipeline metadata. It is not connected to the branch nick.

show-pipeline

Purpose

Show the current pipeline.

Usage

bzr show-pipeline [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

All pipes are listed with the beginning of the pipeline at the top and the end of the pipeline at the bottom. These indicators are used:

* - The current pipe.
U - A pipe holding uncommitted changes.

Uncommitted changes are automatically restored by the ‘switch-pipe’ command.

Aliases

pipes

switch-pipe

Purpose

Switch from one pipe to another.

Usage

bzr switch-pipe PIPE

Options

--usage Show usage message and options.
-d ARG, --directory=ARG
 Directory of the checkout to switch, rather than the current directory.
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
-h, --help Show help message.

Description

Any uncommitted changes are stored. Any stored changes in the target pipe are restored.

Aliases

swp

sync-pipeline

Purpose

Synchronise the contents of this pipeline with another copy.

Usage

bzr sync-pipeline [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

The first argument is the location of one of the pipes in the remote pipeline. It defaults to the push location. If it does not exist, the whole remote pipeline will be created. If any remote pipes are missing, they will be created.

The pipelines are then synchronized by pulling and pushing between pipes, depending on which is newer.

If pipes have diverged, the process will abort. You should then merge the remote pipe into the local pipe and re-run sync-pipeline.