Bazaar

Bazaar

 




Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Differences between revisions 1 and 9 (spanning 8 versions)
Revision 1 as of 2008-03-17 20:32:56
Size: 1221
Comment:
Revision 9 as of 2009-02-10 23:56:14
Size: 8248
Comment: 1.12-preview renamed to development-wt5
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
[[TableOfContents(2)]]

== Goals ==
[[TableOfContents(3)]]

== 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 'see' just the directories/files in the project of interest to them. Developers may also wish to break a large set of changes into 'stages' by using views.

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.

The Filtered Views feature is now ready for testing. Please help us get this feature right by:

 * downloading the code

 * reading the draft User Documentation (below)

 * experimenting with it

 * reporting your findings to the mailing list.

To get started, grab the latest code from https://code.launchpad.net/~ian-clatworthy/bzr/bzr.views.


== Testing setup ==

Until filtered views are merged into bzr.dev, there are a few things to setup before you can use filtered views. Firstly, be sure you're using a branch of Bazaar that implements filtered views. Secondly, this feature isn't production strength yet so play around in a scratch branch, not your master branch of important code! Thirdly, the default format doesn't support views yet so upgrade your (scratch) branch to 1.12-preview format.

Here's an example of how to get setup for testing this feature on Linux:

{{{
  ln -s ~/bzr/repo/bzr.views/bzr ~/bin/bzrfv
  bzrfv branch my-project my-test
  cd my-test
  bzrfv upgrade --development-wt5
}}}

Remaining instructions below will simply refer to `bzr` so be sure to use `bzrfv` if that's the script/alias you're using to run the appropriate code.

== User documentation ==

=== 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
}}}


=== 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
}}}


== Open Issues ==

=== Commit after merge UI ===

Selective file commits after a merge aren't (currently) supported by Bazaar, so users need to switch off the view before committing a merge. Perhaps we should explicitly detect that a merge has happened and make `bzr commit` '''not''' implicitly use a view in this case? Or perhaps it still should but only w.r.t. reporting of what gets committed?

=== File existence checking ===

Should we be allowed to create a view containing non-existent files? Right now, no checking is done. Perhaps we should at least produce a warning if a file doesn't exist.

=== Rename and delete tracking ===

If the view file contains a list of paths, what happens when things are renamed? Can we trap this and either follow the rename or complain?
For example, if a view contains `README` and `doc/` and `README` gets renamed to `README.txt`, should the view be implicitly updated?

Likewise, if a file listed in a view is deleted, should the view be implicitly updated?

One option is for the view command to take a ``--refresh`` parameter that updates a view definition so that it only contains existing files. It would then be up to the user as to when to do the refreshing.

=== Sharing views ===

It should be possible for users/projects to share useful views. It is proposed that the view command take a ``--from`` option that accepts the location of a text file holding the view definition, one item per line. Within the file, blank lines and comment lines (beginning with #) would be ignored. For example, the Bazaar project might define a view in a file called user-doc-view.txt for technical writers:
{{{
  NEWS
  doc/
  bzrlib/help_topics/
}}}

That file may be placed on a public web site and used like this:
{{{
  bzr view --from http://bazaar-vcs.org/views/user-doc-view.txt
  Using 'my' view: NEWS, doc/, bzrlib/help_topics/
}}}

It is proposed that the text file be encoded in utf8. An --output option could to added to the view command to generate a file in the right format and encoding from an existing view. For example:
{{{
  $ bzr view NEWS doc/ bzrlib/help_topics
  Using 'my' view: NEWS, doc/, bzrlib/help_topics/
  $ bzr view --output user-doc-view.txt
  Saved 'my' view to user-doc-view.txt
}}}

=== Partial trees ===

This feature is sometimes called "partial checkouts" in other tools. I think calling it "partial checkouts" in our case will be confusing as the whole branch will be transferred but only some files and directories in the working tree will be populated. (Obviously care is required to record this fact so that subsequent tree-wide commits don't implicitly delete all the missing files.)

Once view sharing is supported, the ``branch`` and ``checkout`` commands could be extended with a ``view-from`` option. For example:
{{{
  bzr branch http://bazaar-vcs.org/bzr/bzr.dev --view-from http://bazaar-vcs.org/views/user-doc-view.txt
}}}

The full branch would be downloaded but the working-tree would only contain files in the view, potentially saving a large percentage of disk space. When the view was disabled or deleted, the tree would need to be refreshed. Initially, this would be done explicitly using the ``update`` command.


== Design Notes ==

=== Goals ===
Line 14: Line 193:
 * don't introduce features/commands until absolutely necessary
Line 18: Line 195:
== Plan ==

1. Store in a new file: .bzr/checkout/view say - explicitly doesn't propagate
=== Plan ===

1. Store metadata in a new file: .bzr/checkout/view - explicitly doesn't propagate
Line 28: Line 205:
4. Add --view (-V) list option to checkout and branch

5. Suggested order to support views in other commands:
4. Commands that need to support views include:
Line 37: Line 212:
    * mv
Line 41: Line 217:
6. Once all relevant existing commands support views, add ''view'' command for changing the view. This can be a second patch.
   
== Issues ==

If the view file contains a list of paths, what happens when things are renamed? Can we trap this and either follow the rename or complain?
Some further details are given here: https://lists.ubuntu.com/archives/bazaar/2008q3/044656.html.

Filtered Views

TableOfContents(3)

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 'see' just the directories/files in the project of interest to them. Developers may also wish to break a large set of changes into 'stages' by using views.

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.

The Filtered Views feature is now ready for testing. Please help us get this feature right by:

  • downloading the code
  • reading the draft User Documentation (below)
  • experimenting with it
  • reporting your findings to the mailing list.

To get started, grab the latest code from https://code.launchpad.net/~ian-clatworthy/bzr/bzr.views.

Testing setup

Until filtered views are merged into bzr.dev, there are a few things to setup before you can use filtered views. Firstly, be sure you're using a branch of Bazaar that implements filtered views. Secondly, this feature isn't production strength yet so play around in a scratch branch, not your master branch of important code! Thirdly, the default format doesn't support views yet so upgrade your (scratch) branch to 1.12-preview format.

Here's an example of how to get setup for testing this feature on Linux:

  ln -s ~/bzr/repo/bzr.views/bzr ~/bin/bzrfv
  bzrfv branch my-project my-test
  cd my-test
  bzrfv upgrade --development-wt5

Remaining instructions below will simply refer to bzr so be sure to use bzrfv if that's the script/alias you're using to run the appropriate code.

User documentation

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

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

Open Issues

Commit after merge UI

Selective file commits after a merge aren't (currently) supported by Bazaar, so users need to switch off the view before committing a merge. Perhaps we should explicitly detect that a merge has happened and make bzr commit not implicitly use a view in this case? Or perhaps it still should but only w.r.t. reporting of what gets committed?

File existence checking

Should we be allowed to create a view containing non-existent files? Right now, no checking is done. Perhaps we should at least produce a warning if a file doesn't exist.

Rename and delete tracking

If the view file contains a list of paths, what happens when things are renamed? Can we trap this and either follow the rename or complain? For example, if a view contains README and doc/ and README gets renamed to README.txt, should the view be implicitly updated?

Likewise, if a file listed in a view is deleted, should the view be implicitly updated?

One option is for the view command to take a --refresh parameter that updates a view definition so that it only contains existing files. It would then be up to the user as to when to do the refreshing.

Sharing views

It should be possible for users/projects to share useful views. It is proposed that the view command take a --from option that accepts the location of a text file holding the view definition, one item per line. Within the file, blank lines and comment lines (beginning with #) would be ignored. For example, the Bazaar project might define a view in a file called user-doc-view.txt for technical writers:

  NEWS
  doc/
  bzrlib/help_topics/

That file may be placed on a public web site and used like this:

  bzr view --from http://bazaar-vcs.org/views/user-doc-view.txt
  Using 'my' view: NEWS, doc/, bzrlib/help_topics/

It is proposed that the text file be encoded in utf8. An --output option could to added to the view command to generate a file in the right format and encoding from an existing view. For example:

  $ bzr view NEWS doc/ bzrlib/help_topics
  Using 'my' view: NEWS, doc/, bzrlib/help_topics/
  $ bzr view --output user-doc-view.txt
  Saved 'my' view to user-doc-view.txt

Partial trees

This feature is sometimes called "partial checkouts" in other tools. I think calling it "partial checkouts" in our case will be confusing as the whole branch will be transferred but only some files and directories in the working tree will be populated. (Obviously care is required to record this fact so that subsequent tree-wide commits don't implicitly delete all the missing files.)

Once view sharing is supported, the branch and checkout commands could be extended with a view-from option. For example:

  bzr branch http://bazaar-vcs.org/bzr/bzr.dev --view-from http://bazaar-vcs.org/views/user-doc-view.txt

The full branch would be downloaded but the working-tree would only contain files in the view, potentially saving a large percentage of disk space. When the view was disabled or deleted, the tree would need to be refreshed. Initially, this would be done explicitly using the update command.

Design Notes

Goals

  • aim for general design useful for both:
    • reduced tree (ala cvs) useful for translators, etc.
    • focussed work (ala git index) useful for breaking large changes into smaller commits
  • provide feedback each time view is being used
  • do lots of tests as we go

Plan

1. Store metadata in a new file: .bzr/checkout/view - explicitly doesn't propagate

2. If a view is being invoked, then first message displayed is:

  • Ignoring files outside view: (details of view)

3. If specifying explicit files, error if they are not inside the view.

4. Commands that need to support views include:

  • status
  • diff
  • commit
  • add
  • remove
  • revert
  • mv
  • merge
  • update
  • pull

Some further details are given here: https://lists.ubuntu.com/archives/bazaar/2008q3/044656.html.