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 deal with just the directories/files in the project of interest to them.
Developers may also wish to break a large set of changes into multiple commits by using views. While shelve and unshelve let developers put some changes aside for a later commit, views let developers specify what to include in (instead of exclude from) the next commit.
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.
Note: Filtered views are only supported in format 2a, the default in Bazaar 2.0, or later.
Creating a view
This is done by specifying the files and directories using the view command like this:
bzr view file1 file2 dir1 ...
The output is:
Using 'my' view: file1, file2, dir1
Listing the current view
To see the current view, use the view command without arguments:
If no view is current, a message will be output saying No current view.. Otherwise the name and content of the current view will be displayed like this:
'my' view is: a, b, c
Switching between views
In most cases, a view has a short life-span: it is created to make a selected change and is deleted once that change is committed. At other times, you may wish to create one or more named views and switch between them.
To define a named view and switch to it:
bzr view --name view-name file1 dir1 ...
bzr view --name doc NEWS doc/ Using doc view: NEWS, doc/
To list a named view:
bzr view --name view-name
To switch to a named view:
bzr view --switch view-name
To list all views defined:
bzr view --all
Temporarily disabling a view
To disable the current view without deleting it, you can switch to the pseudo view called off. This can be useful when you need to see the whole tree for an operation or two (e.g. merge) but want to switch back to your view after that.
To disable the current view without deleting it:
bzr view --switch off
After doing the operations you need to, you can switch back to the view you were using by name. For example, if the previous view used the default name:
bzr view --switch my
To delete the current view:
bzr view --delete
To delete a named view:
bzr view --name view-name --delete
To delete all views:
bzr view --delete --all
Things to be aware of
Defining a view does not delete the other files in the working tree - it merely provides a “lens” over the working tree.
Views are stored as working tree metadata. They are not propagated by branch commands like pull, push and update.
Views are defined in terms of file paths. If you move a file in a view to a location outside of the view, the view will no longer track that path. For example, if a view is defined as doc/ and doc/NEWS gets moved to NEWS, the views stays defined as doc/ and does not get changed to doc/ NEWS. Likewise, deleting a file in a view does not remove the file from that view.
The commands that use the current view are:
Commands that operate on the full tree but only report changes inside the current view are:
Many commands currently ignore the current view. Over time, some of these commands may be added to the lists above as the need arises. By design, some commands will most likely always ignore the current view because showing the whole picture is the better thing to do. Commands in this group include: