| 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:
Homebzr 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.
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. | |
| --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.
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-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
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.
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-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.
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.
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.
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.
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
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
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.