Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Revision 4 as of 2008-12-24 05:29:36

Clear message

Filtered Views


Introducing Filtered Views

Views provide a mask over the tree so that users can focus on a subset of a tree when doing their work. There are several cases where this masking can be helpful. For example, technical writers and testers on many large projects may prefer to 'see' just the directories/files in the project of interest to them. Developers may also wish to break a large set of changes into 'stages' by using views.

After creating a view, commands that support a list of files - status, diff, commit, etc - effectively have that list of files implicitly given each time. An explicit list of files can still be given to these commands but the nominated files must be within the current view. In contrast, tree-centric commands - pull, merge, update, etc. - continue to operate on the whole tree but only report changes relevant to the current view. In both cases, Bazaar notifies the user each time it uses a view implicitly so that it is clear that the operation or output is being masked accordingly.

The Filtered Views feature is now ready for testing. Please help us get this feature right by:

  • downloading the code
  • reading the User Documentation (below)
  • experimenting with it
  • reporting your findings to the mailing list.

To get started, grab the latest code from

Testing Setup

Until filtered views are merged into, there are a few things to setup before you can use filtered views. Firstly, be sure you're using a branch of Bazaar that implements filtered views. Secondly, this feature isn't production strength yet so play around in a scratch branch, not your master branch of important code! Thirdly, the default format doesn't support views yet so upgrade your (scratch) branch to 1.12-preview format.

Here's an example of how to get setup for testing this feature on Linux:

  ln -s ~/bzr/repo/bzr.views/bzr ~/bin/bzrfv
  bzrfv branch my-project my-test
  cd my-test
  bzrfv upgrade --1.12-preview

Remaining instructions below will simply refer to bzr so be sure to use bzrfv if that's the script/alias you're using to run the appropriate code.

User Documentation

Creating a view

This is done by specifying the files and directories using the view command like this:

  $ bzr view file1 file2 dir1 ...

To see the current view, use the view command without arguments like this:

  $ bzr view

Open Issues

If the view file contains a list of paths, what happens when things are renamed? Can we trap this and either follow the rename or complain?

Old Design Notes


  • aim for general design useful for both:
    • reduced tree (ala cvs) useful for translators, etc.
    • focussed work (ala git index) useful for breaking large changes into smaller commits
  • provide feedback each time view is being used
  • don't introduce features/commands until absolutely necessary
  • do lots of tests as we go


1. Store in a new file: .bzr/checkout/view say - explicitly doesn't propagate

2. If a view is being invoked, then first message displayed is:

  • Ignoring files outside view: (details of view)

3. If specifying explicit files, error if they are not inside the view.

4. Add --view (-V) list option to checkout and branch

5. Suggested order to support views in other commands:

  • status
  • diff
  • commit
  • add
  • remove
  • revert
  • merge
  • update
  • pull

6. Once all relevant existing commands support views, add view command for changing the view. This can be a second patch.

Some further details are given here: