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 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::

  bzr view

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 ...

For example::

  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


Deleting views
--------------

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:

* status
* diff
* commit
* add
* remove
* revert
* mv
* ls.

Commands that operate on the full tree but only report changes
inside the current view are:

* pull
* update
* merge.

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:

* log
* info.