loom - Manage a stack of patches over an upstream

Version	1.4.0dev
Branch	lp:bzr-loom
Home page	https://launchpad.net/bzr-loom
Owner	lifeless
GNU/Linux	Yes
Windows	Yes
Mac OS X	Yes

Loom is a bzr plugin which adds new commands to manage a loom of patches.

Loom adds the following new commands:

• loomify: This converts a branch into a loom enabled branch. As a result of this, the branch format is converted and you need to have the loom plugin installed to use it after that. The current branch nickname becomes the base thread in the loom.
• create-thread: This adds a new thread to the loom with the supplied name and positions the branch on the new thread.
• record: Perform a commit of the loom - record the current stack of patches into history, allowing it to be pushed, pulled and merged.
• revert-loom: Revert all change in the current stack of patches to the last recorded one.
• show-loom: Shows the threads in the loom. It currently does not show the # of commits in each thread, but it is planned to do that in the future.
• down-thread: Move the branch down a thread. After doing this commits and merges in this branch will affect the newly selected thread.
• up-thread: Move the branch up a thread. This will merge in all the changes from the current thread that are not yet integrated into the new thread into it and leave you ready to commit them.
• combine-thread: Combine the current thread with the thread below it. If It is the last thread, this will currently refuse to operate, but in the future will just turn the loom into a normal branch again. Use this command to remove a thread which has been merged into upstream.

Loom also adds a new revision specifier ‘thread:’. You can use this to diff against threads in the current Loom. For instance, ‘bzr diff -r thread:’ will show you the different between the thread below yours, and your thread.

combine-thread

Purpose

Combine the current thread with the thread below it.

Usage

bzr combine-thread

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 currently refuse to operate on the last thread, but in the future will just turn the loom into a normal branch again.

Use combine-thread to remove a thread which has been merged into upstream.

In precise terms this will:

• Remove the entry from the loom for the current thread.
• Change threads to the thread below.

create-thread

Purpose

Add a thread to this loom.

Usage

bzr create-thread THREAD

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 creates a new thread in this loom and moves the branch onto that thread.

The thread-name must be a valid branch ‘nickname’, and must not be the name of an existing thread in your loom.

down-thread

Purpose

Move the branch down a thread in the loom.

Usage

bzr down-thread [THREAD]

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 removes the changes introduced by the current thread from the branch and sets the branch to be the next thread down.

Down-thread refuses to operate if there are uncommitted changes, since this is typically a mistake. Switch can be used for this purpose, instead.

Aliases

down

See also

switch, up-thread

export-loom

Purpose

Export loom threads as a full-fledged branches.

Usage

bzr export-loom [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

LOCATION specifies the location to export the threads under. If it does not exist, it will be created.

In any of the standard config files, “export_loom_root” may be set to provide a default location that will be used if no location is supplied.

See also

configuration

loomify

Purpose

Add a loom to this branch.

Usage

bzr loomify [LOCATION]

Options

--usage	Show usage message and options.
--base=ARG	The name to use for the base thread.
-v, --verbose	Display more information.
-q, --quiet	Only display errors and warnings.
-h, --help	Show help message.

Description

This creates a loom in your branch, which will alter the behaviour of bzr for a number of commands to manage a group of patches being evolved in parallel.

You must have a branch nickname explicitly set to use this command, as the branch nickname becomes the ‘base thread’ of the loom. You can specify the branch nick with the –base option.

record

Purpose

Record the current last-revision of this tree into the current thread.

Usage

bzr record MESSAGE

Options

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

revert-loom

Purpose

Revert part or all of a loom.

Usage

bzr revert-loom [THREAD]

Options

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

Description

This will update the current loom to be the same as the basis when –all is supplied. If no parameters or options are supplied then nothing will happen. If a thread is named, then only that thread is reverted to its state in the last committed loom.

show-loom

Purpose

Show the threads in this loom.

Usage

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

Output the threads in this loom with the newest thread at the top and the base thread at the bottom. A => marker indicates the thread that ‘commit’ will commit to.

switch

Purpose

Set the branch of a checkout and update.

Usage

bzr switch TO_LOCATION

Options

--force	Switch even if local commits will be lost.
-v, --verbose	Display more information.
-q, --quiet	Only display errors and warnings.
--usage	Show usage message and options.
-b, --create-branch
	Create the target branch from this one before switching to it.
-h, --help	Show help message.

Description

For looms, this is equivalent to ‘down-thread’ when to_location is the name of a thread in the loom. For lightweight checkouts, this changes the branch being referenced. For heavyweight checkouts, this checks that there are no local commits versus the current bound branch, then it makes the local branch a mirror of the new location and binds to it.

In both cases, the working tree is updated and uncommitted changes are merged. The user can commit or revert these as they desire.

Pending merges need to be committed or reverted before using switch.

up-thread

Purpose

Move the branch up a thread in the loom.

Usage

bzr up-thread

Options

-v, --verbose	Display more information.
--auto	Automatically commit and merge repeatedly.
-q, --quiet	Only display errors and warnings.
--usage	Show usage message and options.
-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

This merges the changes done in this thread but not incorporated into the next thread up into the next thread up and switches your tree to be that thread.

See also

down-thread, switch