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
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, Breezy 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 Breezy 2.0, or later.
Creating a view¶
This is done by specifying the files and directories using the
command like this:
brz 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
'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:
brz view --name view-name file1 dir1 ...
brz view --name doc NEWS doc/ Using doc view: NEWS, doc/
To list a named view:
brz view --name view-name
To switch to a named view:
brz view --switch view-name
To list all views defined:
brz 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:
brz 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:
brz view --switch my
To delete the current view:
brz view --delete
To delete a named view:
brz view --name view-name --delete
To delete all views:
brz 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
doc/NEWS gets moved to
the views stays defined as
doc/ and does not get changed
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: