~bzr-pqm/bzr/bzr.dev

BzrTools

========

Overview

--------

BzrTools is a collection of useful enhancements to Bazaar.

For installation instructions, see the BzrTools home page:

http://bazaar-vcs.org/BzrTools.

Here is a sample of the frequently used commands it provides.

shelve, shelf, unshelve

-----------------------

These commands provide a fine-grained (patch-hunk level) undo facility.

This allows you to put aside some of your changes, commit,

and get back to where you were before.

For example, consider a working tree with one or more changes made ... ::

  $ bzr diff

  === modified file 'description.txt'

  --- description.txt

  +++ description.txt

  @@ -2,7 +2,7 @@

   ===============

   These plugins

  -by Michael Ellerman

  +written by Michael Ellerman

   provide a very

   fine-grained 'undo'

   facility

  @@ -11,6 +11,6 @@

   This allows you to 

   undo some of

   your changes,

  -commit, and get

  +perform a commit, and get

   back to where you

   were before.

The ``shelve`` command interactively asks which changes

you want to retain in the working tree::

  $ bzr shelve

  --- description.txt

  +++ description.txt

  @@ -2,7 +2,7 @@

   ===============

   These plugins

  -by Michael Ellerman

  +written by Michael Ellerman

   provide a very

   fine-grained 'undo'

   facility

  Keep this change? (1 of 2) [nydisq?] (n): y

  --- description.txt

  +++ description.txt

  @@ -11,6 +11,6 @@

   This allows you to 

   undo some of

   your changes,

  -commit, and get

  +perform a commit, and get

   back to where you

   were before.

  Keep this change? (2 of 2) [nydisq?] (n): n

  Status:

    description.txt

      1 hunks to be shelved

      1 hunks to be kept

  Shelve these changes, or restart? [yrsiq?] (y): y

  Saving shelved patches to /tmp/proj/.bzr-shelf

  Reverting shelved patches

  Diff status is now:

   description.txt | 2 +-

   1 files changes, 1 insertions(+), 1 deletions(-)

If there are lots of changes in the working tree, you

can provide the ``shelve`` command with a list of files

and you will only be asked about changes in those files.

After shelving changes, it's a good idea to use ``diff``

to confirm the tree has just the changes you expect::

  $ bzr diff

  === modified file 'description.txt'

  --- description.txt

  +++ description.txt

  @@ -2,7 +2,7 @@

   ===============

   These plugins

  -by Michael Ellerman

  +written by Michael Ellerman

   provide a very

   fine-grained 'undo'

   facility

Great - you're ready to commit::

  $ bzr commit -m "improve first sentence"

At some later time, you can bring the shelved changes back into the

working tree using ``unshelve``::

  $ bzr unshelve

  Reapplying shelved patches 

  Diff status is now:

   description.txt | 4 ++--

   1 files changes, 2 insertions(+), 2 deletions(-)

If you want to, you can put multiple items on the shelf.

Normally each time you run ``unshelve`` the most recently

shelved changes will be reinstated. However, you can also

unshelve changes in a different order by explicitly

specifying which changes to unshelve. (This works best

when the changes don't depend on each other.)

While you have patches on the shelf you can view and manipulate them

with the ``shelf`` command. Run ``bzr shelf -h`` for more information

about how to do this.

shell

-----

``bzr shell`` starts up a command interpreter than understands

Bazaar commands natively. This has several advantages:

 * There's no need to type ``bzr`` at the front of every command.

 * Intelligent auto-completion is provided.

 * Commands run slightly faster as there's no need to load Bazaar's

   libraries each time.

cdiff

-----

``bzr cdiff`` provides a colored version of ``bzr diff`` output.

On GNU/Linux, UNIX and OS X, this is often used like this::

  bzr cdiff | less -R