loom - Manage a stack of patches over an upstream

Version 2.2.1dev
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 new revision specifiers ‘thread:’ and ‘below:’. You can use these 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. See bzr help revisionspec for the detailed help on these two revision specifiers.

combine-thread

Purpose

Combine the current thread with the thread below it.

Usage

bzr combine-thread

Options

--usage Show usage message and options.
--force Combine even if work in the thread is not integrated up or down the loom.
-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.

The new thread is created immediately after the current thread.

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.

status

Purpose

Show status of a loom.

Usage

bzr status [FILE...]

Options

-S, --short Use short status indicators.
-v, --verbose Display more information.
-V, --versioned
 Only show versioned files.
--no-pending Don’t show pending merges.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
--usage Show usage message and options.
--show-ids Show internal object ids.
-c ARG, --change=ARG
 Select changes introduced by the specified revision. See also “help revisionspec”.
-r ARG, --revision=ARG
 See “help revisionspec” for details.

Aliases

st, stat

See also

diff, revert, status-flags

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.
-d ARG, --directory=ARG
 Branch to operate on, instead of working directory
--usage Show usage message and options.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-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 to the top thread in the loom.

Usage

bzr up-thread [THREAD]

Options

-v, --verbose Display more information.
--auto Deprecated - now the default.
--manual Perform commit manually.
-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. Unless there are conflicts, or –manual is specified, it will then commit and repeat the process.

See also

down-thread, switch