Rev 4059: add Filtered Views section to User Guide (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Feb 27 02:05:07 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4059
revision-id: pqm at pqm.ubuntu.com-20090227020504-tdhdwfbj4xvptjww
parent: pqm at pqm.ubuntu.com-20090226191409-iowt3d9s53c7mqs2
parent: ian.clatworthy at canonical.com-20090227011127-bhz450zx8nqxxbnv
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
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: ian.clatworthy at canonical.com-20090227011127-bhz450zx8nqxxbnv
parent: pqm at pqm.ubuntu.com-20090226191409-iowt3d9s53c7mqs2
parent: ian.clatworthy at canonical.com-20090226101045-t08jl6bnff7s4a11
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
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: ian.clatworthy at canonical.com-20090226101045-t08jl6bnff7s4a11
parent: pqm at pqm.ubuntu.com-20090226031558-1ubr618vdn4r5f07
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
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
More information about the bazaar-commits
mailing list