At file:///home/pqm/archives/thelove/bzr/%2Btrunk/ ------------------------------------------------------------ revno: 4059 revision-id: [email protected] parent: [email protected] parent: [email protected] committer: Canonical.com Patch Queue Manager <[email protected]> branch nick: +trunk timestamp: Fri 2009-02-27 02:05:04 +0000 message: add Filtered Views section to User Guide (Ian Clatworthy) added: doc/en/user-guide/filtered_views.txt filtered_views.txt-20090226100856-a16ba1v97v91ru58-1 modified: NEWS NEWS-20050323055033-4e00b5db738777ff doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2 ------------------------------------------------------------ revno: 4058.1.1 revision-id: [email protected] parent: [email protected] parent: [email protected] committer: Ian Clatworthy <[email protected]> branch nick: ianc-integration timestamp: Fri 2009-02-27 11:11:27 +1000 message: add Filtered Views section to User Guide (Ian Clatworthy) added: doc/en/user-guide/filtered_views.txt filtered_views.txt-20090226100856-a16ba1v97v91ru58-1 modified: NEWS NEWS-20050323055033-4e00b5db738777ff doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2 ------------------------------------------------------------ revno: 4054.2.1 revision-id: [email protected] parent: [email protected] committer: Ian Clatworthy <[email protected]> branch nick: bzr.views-help timestamp: Thu 2009-02-26 20:10:45 +1000 message: add Filtered views section to the User Guide added: doc/en/user-guide/filtered_views.txt filtered_views.txt-20090226100856-a16ba1v97v91ru58-1 modified: NEWS NEWS-20050323055033-4e00b5db738777ff doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2 === modified file 'NEWS' --- a/NEWS 2009-02-26 18:26:03 +0000 +++ b/NEWS 2009-02-27 01:11:27 +0000 @@ -21,6 +21,11 @@ options to change the default tree-creation policy of shared repositories. (Matthew Fuller, Marius Kruger, #145033) + * Filtered views provide a mask over the tree so that users can focus + on a subset of a tree when doing their work. See ``Filtered views`` + in chapter 7 of the User Guide and ``bzr help view`` for details. + (Ian Clatworthy) + * The ``-Dmemory`` flag now gives memory information on Windows. (John Arbash Meinel)
=== added file 'doc/en/user-guide/filtered_views.txt' --- a/doc/en/user-guide/filtered_views.txt 1970-01-01 00:00:00 +0000 +++ b/doc/en/user-guide/filtered_views.txt 2009-02-27 01:11:27 +0000 @@ -0,0 +1,169 @@ +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: Bazaar's default format does not yet support filtered views. That +is likely to change in the near future. To use filtered views in the +meantime, you currently need to upgrade to ``development-wt5`` (or +``development-wt5-rich-root``) format first. + + +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. === modified file 'doc/en/user-guide/index.txt' --- a/doc/en/user-guide/index.txt 2008-07-11 02:33:29 +0000 +++ b/doc/en/user-guide/index.txt 2009-02-26 10:10:45 +0000 @@ -81,6 +81,7 @@ .. include:: part2_intro.txt .. include:: adv_merging.txt +.. include:: filtered_views.txt .. include:: stacked.txt .. include:: server.txt .. include:: hooks.txt -- bazaar-commits mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/bazaar-commits
