Merge lp:~gagern/bzr/bug560030-include-bash-completion-plugin into lp:bzr

[Martin von Gagern]

Replace the unmaintained bzr completion script with gagern's new one.

According to bug #560030, distro packagers as well as users would like to see the bash completion plugin included in bzr core, instead of simply referred to as an optional plugin.

So this branch joins lp:bzr-bash-completion into lp:bzr and adjusts copyright information so the plugin is officially assigned to Canonical Ltd.

The outdated contrib/bash/bzr script is replaced by what used to be called lazy.sh in bzr-bash-completion: a script that generates the full bzr completion function upon first invocation, keeping bash startup times low and still avoiding the overhead of a bzr invocation for every completion except the first.

[Martin Packman (gz)]

Source is not Python 2.4 compatible:
+ "debug": debug_output if debug else "",

Should the plugin really be unconditionally installed when a number of platforms don't use bash?

[Martin von Gagern (gagern)]

Thanks for spotting the Python 2.4 thing. Testing it with Python 2.4 I also found another problem: the plugin used to depend on testtools for the registry of the --parallel option to the bzr selftest command.

Isn't there a large number of users that don't use launchpad, or that never merge NEWS files, or that don't store their credentials in ~/.netrc? Come to think of it, isn't there a large number of users that don't sign any commits, or never shelve stuff, or don't send merge directives via mail? Or, even more to the point, how many users are using the shell-completion builtin?

I bet you get my point: yes, there are certainly users that won't require the bash_completion plugin. But it's small enough that the extra space requirement shouldn't hurt, designed with the hope that the __init__.py executes pretty fast, and on the whole shouldn't hurt.

Seeing as most major GNU/Linux distros install the outdated completion script along with bzr despite its shortcomings seems to me an indication that there will be a large enough user base to warrant inclusion into core. There are some bzr builtins and core plugins that I assume have a smaller user base.

And if some platform is certain to never have any need for bash completion, and is concerned enough about memory requirements or whatever, they can simply delete the plugin in their installation.

[Vincent Ladeuil (vila)]

I'm ok with merging this into core, but I'd like a few cleanups first.

Mostly, the plugin carries some excessive baggage from its birth as a standalone plugin that doesn't match the policies we have for the core plugins.

Regarding distribution, windows installers need to be told explicitly about new
plugins, so no worries there. For the other OSes, well, bash is at least available
if not already installed by default.

Regarding load time impact, you can go a step further and use CommandRegistry.register_lazy().

We need tests. I don't clearly understand how the completion works and you may need to redesign a bit to be able to test at the python level. Don't hesitate
to ask for help.

I don't ask for a complete coverage here, but making sure we know how to
complete at least some basic commands and their args will be a minimum.
Having a design (with associated tests) ready for further enhancements
(prefix completion for known transport protocols or useful shortcuts like :parent, :push and the like) will be a nice bonus though.

The above are rather generic, here are some more concrete points:
- delete .bzrignore,
- use bzrlib version like the other plugins,
- watch for PEP8 compliance (head, fun, tail, etc in bashcomp.py miss double vertical spaces)

review: Needs Fixing

[Martin von Gagern (gagern)]

Thanks for the review, Vincent! Probably won't have time to deal with it before 27 April or so, so I'm putting this on hold until then.

Testing is a real problem here: the things I'd be most concerned about or interested in is bash syntax and behaviour, and obviously testing these involves executing bash, which can't be done from within python only. Maybe I can write tests that check whether bash is available, and skip if it isn't.

I think this approach is the only thing that could really catch regressions, in particular the one I recently introduced and fixed on trunk. This is the only thing that can actually check the behaviour of the hardcoded template around the simple dynamically generated code.

Another thing I might do is refactor stuff so that data aquisition and code generation are separated. That way, we could ensure that the data aquisition does the correct thing, and hopefully keep the code generation simple enough so it will be easy to check. This might also open the door for other shells, zsh in particular, so it might be a good thing even without tests. But it's a major step, so it will take a bit of time.

[Vincent Ladeuil (vila)]

>>>>> Martin von Gagern <email address hidden> writes:

    > Thanks for the review, Vincent! Probably won't have time to deal
    > with it before 27 April or so, so I'm putting this on hold until
    > then.

    > Testing is a real problem here: the things I'd be most concerned
    > about or interested in is bash syntax and behaviour, and obviously
    > testing these involves executing bash, which can't be done from
    > within python only. Maybe I can write tests that check whether
    > bash is available, and skip if it isn't.

Yup, that's the idea, define a feature in bzrlib.tests.features for
that.

    > I think this approach is the only thing that could really catch
    > regressions, in particular the one I recently introduced and fixed
    > on trunk. This is the only thing that can actually check the
    > behaviour of the hardcoded template around the simple dynamically
    > generated code.

Exactly. You may even want to add more functions in the template to have
smaller tests.

    > Another thing I might do is refactor stuff so that data aquisition
    > and code generation are separated. That way, we could ensure that
    > the data aquisition does the correct thing, and hopefully keep the
    > code generation simple enough so it will be easy to check.

... no comment :)

    > This might also open the door for other shells, zsh in particular,
    > so it might be a good thing even without tests. But it's a major
    > step, so it will take a bit of time.

Yes, I didn't mention that in my first review and our experience is that
it's easier to review and land smaller proposals, so don't try to
address all of that in a single proposal.

But once you get there, have a look at
bzrlib.builtins.cmd_shell_complete which is used by zsh (I think).

Some more nits found while re-reading your mp:

- Don't use relative imports, they tend to break in obscure ways if you
  happend to have a PYTHON_PATH that includes the current dir and you're
  working in the directory of your plugin (or another plugin that use
  the same package name or another python program, etc). Even if *you*
  don't do that, we had bug reports in the past about that.

- try to use:

    from bzrlib import commands
    class cmd_foo(commands.Command)

  instead of

    from bzrlib.command import Command
    class cmd_foo(Command)

  We don't always respect this rule, but we're fixing such usages as we
  encounter them.

[Martin von Gagern (gagern)]

> delete .bzrignore,
Dropped.

> use bzrlib version like the other plugins,
Done, and also dropped meta.py along the way.

> watch for PEP8 compliance
Should be better now.

> check whether bash is available, and skip if it isn't.
> define a feature in bzrlib.tests.features for that.
Have a test for bash, but it's in my own testing code, as I can't imagine other tests requiring bash as well, and as I wanted to include the test suite in the standalone distribution of the plugin as well.

Maybe some general feature class testing for the existence of arbitrary binaries, possibly taking the PATH environment variable and platform conventions into account might be a good idea as well. But that would be a different merge request, I think.

> You may even want to add more functions in the template
> to have smaller tests.
I don't feel like clobbering the bash function namespace with too many functions. I consider the completion tests to be pretty much black box tests: input a list of words, output a list of completions. Otherwise I'd have to write not only a number of smaller functions, but a suitable testing framework for all of these. Or express test input and assertions in bash syntax.

> bzrlib.builtins.cmd_shell_complete which is used by zsh (I think).
At least not by the zsh completion script shipped by either zsh or bzr. There are scripts out there making use of it, but none seem particularly "official". In any case, I'll investigate zsh in more detail once this got landed.

> Don't use relative imports, they tend to break in obscure ways
How so? I thought Python 2 does relative imports by default, and only falls back to absolute imports if the relative import fails. So I would have assumed that a relative import would be on the safe side, whereas an absolute one could break in cases where there was a relative import of the same name available.

Anyway, I simply take your word for it, and changed everything to absolute paths. Don't want to do the same for the standalone distribution, though, as there people might choose a different plugin name.

> try to use [module imports instead of class imports]
Done.

[Vincent Ladeuil (vila)]

>>>>> Martin von Gagern <email address hidden> writes:

    >> check whether bash is available, and skip if it isn't.
    >> define a feature in bzrlib.tests.features for that.

    > Have a test for bash, but it's in my own testing code, as I can't
    > imagine other tests requiring bash as well, and as I wanted to
    > include the test suite in the standalone distribution of the
    > plugin as well.

Perfect.

    > Maybe some general feature class testing for the existence of
    > arbitrary binaries, possibly taking the PATH environment variable
    > and platform conventions into account might be a good idea as
    > well. But that would be a different merge request, I think.

Very good idea, many plugins could certainly benefit from it.

    >> You may even want to add more functions in the template
    >> to have smaller tests.

    > I don't feel like clobbering the bash function namespace with too
    > many functions. I consider the completion tests to be pretty much
    > black box tests: input a list of words, output a list of
    > completions.

Hehe, yes, you got it right, I'm not a big fan of blackbox tests :)

For the sake of the discussion, imagine that we encounter a bug about an
option with a weird character like ' or `, whatever.

I'd like the ability to write a test for just the option related part
without having to rely on a command that will use this option.

But except for the remarks bwlow, I'm fine with the tests you've added.

    > Otherwise I'd have to write not only a number of smaller
    > functions, but a suitable testing framework for all of these. Or
    > express test input and assertions in bash syntax.

Yeah, well, that's the point, I don't have strong opinions there as I
don't know the code well enough to decide whether or not you can write
the test in pythin or if bash is really required.

    >> bzrlib.builtins.cmd_shell_complete which is used by zsh (I think).

    > At least not by the zsh completion script shipped by either zsh or
    > bzr.

Yes it is, look for shell-complete (not shell_complete) in contrib/zsh/_bzr.

    > There are scripts out there making use of it, but none seem
    > particularly "official". In any case, I'll investigate zsh in more
    > detail once this got landed.

Yeah, no problem.

    >> Don't use relative imports, they tend to break in obscure ways

    > How so?

I don't remember the bug number off-hand, but having '.' in your
PYTHONPATH and '.' containing an unrelated python module with the same
name may wrongly trigger an import while using
'bzrlib.plugins.<plugin_name>' ensures we get the right one.

<snip/>

   > Don't want to do the same for the standalone distribution, though,
   > as there people might choose a different plugin name.

Wow, interesting... There are so many cases where you *need* the plugin
name to be the same as its containing directory (BZR_PLUGINS_AT works
hard to remove this limitation) that I didn't think about this case... I
won't explore it myself :)

Now for some specifics:

19 --- bzrlib/plugins/bash_completion/README.txt 1970-01-01 00:00:00 +0000

This still includes material related to the use of the plugin in its
non-core version...

review: Needs Fixing

[Martin von Gagern (gagern)]

On 04.05.2010 12:32, Vincent Ladeuil wrote:
> For the sake of the discussion, imagine that we encounter a bug about an
> option with a weird character like ' or `, whatever.

The black-box tests are mostly about testing the fixed functionality
part of the template, not individual commands. But I've just adjusted
the get_script method to make it easier for future tests to provide
cooked completion data without actually having to provide commands for
these.

> Yeah, well, that's the point, I don't have strong opinions there as I
> don't know the code well enough to decide whether or not you can write
> the test in pythin or if bash is really required.

The bash completion stuff is advanced enough that a simplistic python
interpreter wouldn't suffice. And an afvanced one would be a project in
its own right, and require a full test suite to boot...

> Yes it is, look for shell-complete (not shell_complete) in contrib/zsh/_bzr.

OK, it does command name completion using that callback. But not option
completion, although that would be provided by the shell-completion
builtin as well, at least to some degree.

> 19 --- bzrlib/plugins/bash_completion/README.txt 1970-01-01 00:00:00 +0000
>
> This still includes material related to the use of the plugin in its
> non-core version.

Once the plugin got merged, I'd adjust the README to state the fact, and
point out that there are distinct lines of development. That much I'd
write for the standalone plugin and merge into core in a separate merge
request. So I'd like the README to stay a while, but get updated.

> Depending on how long this plugin will continue to live outside of the
> bzr tree, we may want to clean this stuff. I wonder how it will will
> behave (maintaining it in both trees and merging from the plugin may
> trigger some spurious conflicts whatever choise we make)...

I guess I'll keep the plugin around for about a year or so, so people
can use it even without updating their bzr setup. Once most distros ship
bzr with the plugin in place, I'll probably phase out the standalone
distribution. And in any case I'll probably not keep the standalone
branch up to date in case third parties provide branches against the bzr
tree affecting the plugin. Dunno how likely this is.

> Splitting the above into three assertCompletionXXXX will make the tests
> more explicit about what they are checking. Keeping the checks about the
> format returned may be left here though IMHO.

Done, and it does look better. Thanks!

> but 'Approved' with the tweaks mentioned above.

Why the plural? I'd consider the assertion stuff a single tweak, and the
rest of your comments I felt were suggestions, perhaps for a future
merge proposal, but in any case not requirements for this merge here.

[Vincent Ladeuil (vila)]

> On 04.05.2010 12:32, Vincent Ladeuil wrote:
> > For the sake of the discussion, imagine that we encounter a bug about an
> > option with a weird character like ' or `, whatever.
>
> The black-box tests are mostly about testing the fixed functionality
> part of the template, not individual commands. But I've just adjusted
> the get_script method to make it easier for future tests to provide
> cooked completion data without actually having to provide commands for
> these.

Ok, good enough for now.
<snip/>

> Once the plugin got merged, I'd adjust the README to state the fact, and
> point out that there are distinct lines of development. That much I'd
> write for the standalone plugin and merge into core in a separate merge
> request. So I'd like the README to stay a while, but get updated.

Fine for me, thanks for sharing your thoughts on the subject.

> I guess I'll keep the plugin around for about a year or so,

Sounds reasonable.

> Done, and it does look better. Thanks!

Excellent.

>
> > but 'Approved' with the tweaks mentioned above.
>
> Why the plural?

Because my English is not precise enough I suspect :)

> I'd consider the assertion stuff a single tweak,

Yup, that's what I was referring to.

 and the
> rest of your comments I felt were suggestions, perhaps for a future
> merge proposal, but in any case not requirements for this merge here.

Correct.

review: Approve

[lp:~gagern/bzr/bug560030-include-bash-completion-plugin]

5164. By Martin von Gagern on 2010-05-05

merge from trunk.

5165. By Martin von Gagern on 2010-05-05

Include all plugins if --plugins isn't specified (fixes regression).

[John A Meinel (jameinel)]

I'm going to assume that someone else has done a more thorough review of the bash side of things, as I don't really know how things integrate together.

The test infrastructure looks decent.

I do wonder about using "os.access('/bin/bash', X_OK)" rather than just:

subprocess.Popen(['bash', '-c', 'echo hello'], shell=True)

Partially because I just tested it, and under Windows if you have a bash.exe in your path, this succeeds. And in theory, that means that you could run the tests on all platforms, rather than requiring a specific path to be available.

That can be updated/added later, though.

Note that if I hack in that 'bash' is the path that can be accessed, most of the tests pass on Windows except for a couple. However, they're really quite slow:

...lugins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_commit_dashm OK 2163ms
...plugins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_global_opts OK 3039ms
...ugins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_init_format_2 OK 1719ms
...ins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_init_format_any OK 1786ms
...b.plugins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_init_opts OK 1808ms
...lugins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_simple_scipt OK 65ms
...gins.bash_completion.tests.test_bashcomp.TestBashCompletion.test_status_negated OK 1822ms
..._completion.tests.test_bashcomp.TestBashCompletionInvoking.test_revspec_tag_all FAIL 3407ms
    Text attachment: log
------------
15.616 creating repository in file:///C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp/.bzr/.
15.632 creating branch <bzrlib.branch.BzrBranchFormat7 object at 0x01FA9110> in file:///C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp/
15.725 opening working tree 'C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp'
15.999 creating repository in file:///C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp/nInvoking.test_revspec_tag_all/work/.bzr/.
16.180 creating branch <bzrlib.branch.BzrBranchFormat6 object at 0x033F5E50> in file:///C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp/nInvoking.test_revspec_tag_all/work/
16.292 opening working tree 'C:/users/jameinel/appdata/local/temp/testbzr-06_rhc.tmp/nInvoking.test_revspec_tag_all/work'
------------
Text attachment: traceback
------------
Traceback (most recent call last):
  File "c:\Python26\lib\site-packages\testtools-0.9.2-py2.6.egg\testtools\runtest.py", line 128, in _run_user
    return fn(*args)
  File "c:\Python26\lib\site-packages\testtools-0.9.2-py2.6.egg\testtools\testcase.py", line 368, in _run_test_method
    testMethod()
  File "C:\Users\jameinel\dev\bzr\jam-integration\bzrlib\plugins\bash_completion\tests\test_bashcomp.py", line 197, in test_revspec_tag_all
    self.assertCompletionEquals('tag1', 'tag2', '3tag')
  File "C:\Users\jameinel\dev\bzr\jam-integration\bzrlib\plugins\bash_completion\tests\test_bashcomp.py", line 97, in assertCompletionEquals
    self.assertEqual(set(words), self.completion_result)
AssertionError: not equal:
a = set(['3tag', 'tag1', 'tag2'])
b = set()

I'm cer...

review: Needs Information

[John A Meinel (jameinel)]

In a VirtualBox guest on the same hardware, I can confirm that they run better, even if they are still a bit slow:
...letion.tests.test_bashcomp.TestBashCodeGen.test_bzr_version OK 32ms
...etion.tests.test_bashcomp.TestBashCodeGen.test_command_case OK 8ms
...tion.tests.test_bashcomp.TestBashCodeGen.test_command_cases OK 1ms
...tion.tests.test_bashcomp.TestBashCodeGen.test_command_names OK 2ms
...etion.tests.test_bashcomp.TestBashCodeGen.test_debug_output OK 1ms
...ion.tests.test_bashcomp.TestBashCodeGen.test_global_options OK 3ms
...pletion.tests.test_bashcomp.TestBashCompletion.test_cmd_ini OK 685ms
...on.tests.test_bashcomp.TestBashCompletion.test_commit_dashm OK 680ms
...ion.tests.test_bashcomp.TestBashCompletion.test_global_opts OK 682ms
...n.tests.test_bashcomp.TestBashCompletion.test_init_format_2 OK 649ms
...tests.test_bashcomp.TestBashCompletion.test_init_format_any OK 676ms
...etion.tests.test_bashcomp.TestBashCompletion.test_init_opts OK 664ms
...on.tests.test_bashcomp.TestBashCompletion.test_simple_scipt OK 38ms
....tests.test_bashcomp.TestBashCompletion.test_status_negated OK 649ms
...st_bashcomp.TestBashCompletionInvoking.test_revspec_tag_all OK 985ms
...bashcomp.TestBashCompletionInvoking.test_revspec_tag_prefix OK 894ms
...pletion.tests.test_bashcomp.TestDataCollector.test_commands OK 623ms
...ion.tests.test_bashcomp.TestDataCollector.test_commit_dashm OK 8ms
...n.tests.test_bashcomp.TestDataCollector.test_global_options OK 1ms
...tion.tests.test_bashcomp.TestDataCollector.test_init_format OK 9ms
...n.tests.test_bashcomp.TestDataCollector.test_status_negated OK 6ms

----------------------------------------------------------------------
Ran 21 tests in 7.347s

However they:
 a) pass
 b) run in a reasonable speed

So I'm probably okay with this.

I'll mark this as ready, but give it a day or two in case people want to comment. (Especially on whether we want to try to run the tests on more platforms. Somebody should also probably try to test it on Mac...)

review: Approve

[John Szakmeister (jszakmeister)]

Just for the record, I ran this on my MacBook. All the test passed, and it took about 11 seconds for all the tests to run.

[Martin von Gagern (gagern)]

On 18.05.2010 22:48, John A Meinel wrote:
> I do wonder about using "os.access('/bin/bash', X_OK)" rather than just:
> subprocess.Popen(['bash', '-c', 'echo hello'], shell=True)
> And in theory, that means that you could run the tests on all platforms, rather than requiring a specific path to be available.
> That can be updated/added later, though.

lp:~gagern/bzr/bash_completion-ExecutableFeature has the change from
hardcoded paths to generic PATH environment variable.
I'm avoiding Popen(shell=True) to avoid executing yet another shell
process just to do the path resolution.

> most of the tests pass on Windows except for a couple. However, they're really quite slow:

Ouch! Wouldn't have expected this.

One bad solution would be skipping these tests on windows, or depending
on some environment setting, or some such hack. Feels bad, as it reduces
test coverage for performance reasons only.

In the short run, keeping the number of test cases actually executing
bash is probably the best solution. In the long run, it might be
feasible to execute all of these tests from a single bash instance, but
ensuring proper isolation under these circumstances could be tricky.

> ..._completion.tests.test_bashcomp.TestBashCompletionInvoking.test_revspec_tag_all FAIL 3407ms

That one deserves a closer look. Filed bug #582538 for this.

> I'm certainly hesitant to be adding tests that take multiple seconds to run. Though it may just be a win32 bash thing. Can someone else run "bzr selftest -s bp.bash" and let me know?

What alternatives do you have in mind? Not testing the handwritten bash
code seems like a poor alternative.

> The README clearly doesn't apply as-is anymore.

Will adjust that for both the in-tree and the standalone version at a
later point in time. Will submit a new merge proposal for that.

Thanks for the review, looking forward for the merge.

[Robert Collins (lifeless)]

submitted to PQM by hand.

=== modified file 'NEWS'
--- NEWS	2010-05-04 22:02:05 +0000
+++ NEWS	2010-05-05 08:10:48 +0000
@@ -36,6 +36,11 @@
   re-sign, unbind, unknowns.
   (Martin von Gagern, #527878)
 
+* The bash_completion plugin from the bzr-bash-completion project has
+  been merged into the tree. It provides a bash-completion command and
+  replaces the outdated ``contrib/bash/bzr`` script with a version
+  using the plugin. (Martin von Gagern, #560030)
+
 Bug Fixes
 *********
 

=== added directory 'bzrlib/plugins/bash_completion'
=== added file 'bzrlib/plugins/bash_completion/README.txt'
--- bzrlib/plugins/bash_completion/README.txt	1970-01-01 00:00:00 +0000
+++ bzrlib/plugins/bash_completion/README.txt	2010-05-05 08:10:48 +0000
@@ -0,0 +1,201 @@
+.. comment
+
+  Copyright (C) 2010 Canonical Ltd
+
+  This file is part of bzr-bash-completion
+
+  bzr-bash-completion free software: you can redistribute it and/or
+  modify it under the terms of the GNU General Public License as
+  published by the Free Software Foundation, either version 2 of the
+  License, or (at your option) any later version.
+
+  bzr-bash-completion is distributed in the hope that it will be
+  useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+=====================================
+bzr bash-completion script and plugin
+=====================================
+
+This script generates a shell function which can be used by bash to
+automatically complete the currently typed command when the user
+presses the completion key (usually tab).
+
+It is intended as a bzr plugin, but can be used to some extend as a
+standalone python script as well.
+
+| Copyright (C) 2009, 2010 Canonical Ltd
+
+.. contents::
+
+----------
+Installing
+----------
+
+You only need to do this if you want to use the script as a bzr
+plugin.  Otherwise simply grab the bashcomp.py and place it wherever
+you want.
+
+Installing from bzr repository
+------------------------------
+
+To check out the current code from launchpad, use the following commands::
+
+  mkdir -p ~/.bazaar/plugins
+  cd ~/.bazaar/plugins
+  bzr checkout lp:bzr-bash-completion bash_completion
+
+To update such an installation, execute this command::
+
+  bzr update ~/.bazaar/plugins/bash_completion
+
+Installing using easy_install
+-----------------------------
+
+The following command should install the latest release of the plugin
+on your system::
+
+  easy_install bzr-bash-completion
+
+To use this method, you need to have `Easy Install`_ installed and
+also have write access to the required directories. So maybe you
+should execute this command as root or through sudo_. Or you want to
+`install to a different location`_.
+
+.. _Easy Install: http://peak.telecommunity.com/DevCenter/EasyInstall
+.. _sudo: http://linux.die.net/man/8/sudo
+.. _install to a different location:
+   http://peak.telecommunity.com/DevCenter/EasyInstall#non-root-installation
+
+Installing from tarball
+-----------------------
+
+If you have grabbed a source code tarball, or want to install from a
+bzr checkout in a different place than your bazaar plugins directory,
+then you should use the ``setup.py`` script shipped with the code::
+
+  ./setup.py install
+
+If you want to install the plugin only for your own user account, you
+might wish to pass the option ``--user`` or ``--home=$HOME`` to that
+command. For further information please read the manuals of distutils_
+as well as setuptools_ or distribute_, whatever is available on your
+system, or have a look at the command line help::
+
+  ./setup.py install --help
+
+.. _distutils: http://docs.python.org/install/index.html
+.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools#what-your-users-should-know
+.. _distribute: http://packages.python.org/distribute/setuptools.html#what-your-users-should-know
+
+-----
+Using
+-----
+
+Using as a plugin
+-----------------
+
+This is the preferred method of generating the completion function, as
+it will ensure proper bzr initialization.
+
+::
+
+  eval "`bzr bash-completion`"
+
+Lazy initialization
+-------------------
+
+Running the above command automatically from your ``~/.bashrc`` file
+or similar can cause annoying delays in the startup of your shell.
+To avoid this problem, you can delay the generation of the completion
+function until you actually need it.
+
+To do so, source the file ``lazy.sh`` shipped with this package from
+your ``~/.bashrc`` file or add it to your ``~/.bash_completion`` if
+your setup uses such a file. On a system-wide installation, the
+directory ``/usr/share/bash-completion/`` might contain such bash
+completion scripts.
+
+If you installed bzr-bash-completion from the repository or a source
+tarball, you find the ``lazy.sh`` script in the root of the source
+tree. If you installed the plugin using easy_install, you should grab
+the script manually from the bzr repository, e.g. through the bazaar
+web interface on launchpad.
+
+Note that the full completion function is generated only once per
+shell session. If you update your bzr installation or change the set
+of installed plugins, then you might wish to regenerate the completion
+function manually as described above in order for completion to take
+these changes into account.
+
+Using as a script
+-----------------
+
+As an alternative, if bzrlib is available to python scripts, the
+following invocation should yield the same results without requiring
+you to add a plugin::
+
+  eval "`./bashcomp.py`"
+
+This approach might have some issues, though, and provides less
+options than the bzr plugin. Therefore if you have the choice, go for
+the plugin setup.
+
+--------------
+Design concept
+--------------
+
+The plugin (or script) is designed to generate a completion function
+containing all the required information about the possible
+completions. This is usually only done once when bash
+initializes. After that, no more invocations of bzr are required. This
+makes the function much faster than a possible implementation talking
+to bzr for each and every completion. On the other hand, this has the
+effect that updates to bzr or its plugins won't show up in the
+completions immediately, but only after the completion function has
+been regenerated.
+
+-------
+License
+-------
+
+As this is built upon a bash completion script originally included in
+the bzr source tree, and as the bzr sources are covered by the GPL 2,
+this script here is licensed under these same terms.
+
+If you require a more liberal license, you'll have to contact all
+those who contributed code to this plugin, be it for bash or for
+python.
+
+.. cut long_description here
+
+-------
+History
+-------
+
+The plugin was created by Martin von Gagern in 2009, building on a
+static completion function of very limited scope distributed together
+with bzr.
+
+----------
+References
+----------
+
+Plugin homepages
+  | https://launchpad.net/bzr-bash-completion
+  | http://pypi.python.org/pypi/bzr-bash-completion
+Bazaar homepage
+  | http://bazaar.canonical.com/
+
+
+
+.. vim: ft=rst
+
+.. emacs
+   Local Variables:
+   mode: rst
+   End:

=== added file 'bzrlib/plugins/bash_completion/__init__.py'
--- bzrlib/plugins/bash_completion/__init__.py	1970-01-01 00:00:00 +0000
+++ bzrlib/plugins/bash_completion/__init__.py	2010-05-05 08:10:48 +0000
@@ -0,0 +1,39 @@
+# Copyright (C) 2009, 2010 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+__doc__ = """Generate a shell function for bash command line completion.
+
+This plugin provides a command called bash-completion that generates a
+bash completion function for bzr. See its documentation for details.
+"""
+
+from bzrlib import commands, version_info
+
+
+bzr_plugin_name = 'bash_completion'
+bzr_commands = [ 'bash-completion' ]
+
+commands.plugin_cmds.register_lazy('cmd_bash_completion', [],
+                                   'bzrlib.plugins.bash_completion.bashcomp')
+
+
+def load_tests(basic_tests, module, loader):
+    testmod_names = [
+        'tests',
+        ]
+    basic_tests.addTest(loader.loadTestsFromModuleNames(
+            ["%s.%s" % (__name__, tmn) for tmn in testmod_names]))
+    return basic_tests

=== added file 'bzrlib/plugins/bash_completion/bashcomp.py'
--- bzrlib/plugins/bash_completion/bashcomp.py	1970-01-01 00:00:00 +0000
+++ bzrlib/plugins/bash_completion/bashcomp.py	2010-05-05 08:10:48 +0000
@@ -0,0 +1,463 @@
+#!/usr/bin/env python
+
+# Copyright (C) 2009, 2010 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+from bzrlib import (
+    commands,
+    config,
+    help_topics,
+    option,
+    plugin,
+)
+import bzrlib
+import re
+
+
+class BashCodeGen(object):
+    """Generate a bash script for given completion data."""
+
+    def __init__(self, data, function_name='_bzr', debug=False):
+        self.data = data
+        self.function_name = function_name
+        self.debug = debug
+
+    def script(self):
+        return ("""\
+# Programmable completion for the Bazaar-NG bzr command under bash.
+# Known to work with bash 2.05a as well as bash 4.1.2, and probably
+# all versions in between as well.
+
+# Based originally on the svn bash completition script.
+# Customized by Sven Wilhelm/Icecrash.com
+# Adjusted for automatic generation by Martin von Gagern
+
+# Generated using the bash_completion plugin.
+# See https://launchpad.net/bzr-bash-completion for details.
+
+# Commands and options of bzr %(bzr_version)s
+
+shopt -s progcomp
+%(function)s
+complete -F %(function_name)s -o default bzr
+"""     % {
+            "function_name": self.function_name,
+            "function": self.function(),
+            "bzr_version": self.bzr_version(),
+        })
+
+    def function(self):
+        return ("""\
+%(function_name)s ()
+{
+	local cur cmds cmdIdx cmd cmdOpts fixedWords i globalOpts
+	local curOpt optEnums
+
+	COMPREPLY=()
+	cur=${COMP_WORDS[COMP_CWORD]}
+
+	cmds='%(cmds)s'
+	globalOpts='%(global_options)s'
+
+	# do ordinary expansion if we are anywhere after a -- argument
+	for ((i = 1; i < COMP_CWORD; ++i)); do
+		[[ ${COMP_WORDS[i]} == "--" ]] && return 0
+	done
+
+	# find the command; it's the first word not starting in -
+	cmd=
+	for ((cmdIdx = 1; cmdIdx < ${#COMP_WORDS[@]}; ++cmdIdx)); do
+		if [[ ${COMP_WORDS[cmdIdx]} != -* ]]; then
+			cmd=${COMP_WORDS[cmdIdx]}
+			break
+		fi
+	done
+
+	# complete command name if we are not already past the command
+	if [[ $COMP_CWORD -le cmdIdx ]]; then
+		COMPREPLY=( $( compgen -W "$cmds $globalOpts" -- $cur ) )
+		return 0
+	fi
+
+	# find the option for which we want to complete a value
+	curOpt=
+	if [[ $cur != -* ]] && [[ $COMP_CWORD -gt 1 ]]; then
+		curOpt=${COMP_WORDS[COMP_CWORD - 1]}
+		if [[ $curOpt == = ]]; then
+			curOpt=${COMP_WORDS[COMP_CWORD - 2]}
+		elif [[ $cur == : ]]; then
+			cur=
+			curOpt="$curOpt:"
+		elif [[ $curOpt == : ]]; then
+			curOpt=${COMP_WORDS[COMP_CWORD - 2]}:
+		fi
+	fi
+%(debug)s
+	cmdOpts=
+	optEnums=
+	fixedWords=
+	case $cmd in
+%(cases)s\
+	*)
+		cmdOpts='--help -h'
+		;;
+	esac
+
+	if [[ -z $fixedWords ]] && [[ -z $optEnums ]] && [[ $cur != -* ]]; then
+		case $curOpt in
+			tag:*)
+				fixedWords="$(bzr tags 2>/dev/null | sed 's/  *[^ ]*$//')"
+				;;
+		esac
+	elif [[ $cur == = ]] && [[ -n $optEnums ]]; then
+		# complete directly after "--option=", list all enum values
+		COMPREPLY=( $optEnums )
+		return 0
+	else
+		fixedWords="$cmdOpts $globalOpts $optEnums $fixedWords"
+	fi
+
+	if [[ -n $fixedWords ]]; then
+		COMPREPLY=( $( compgen -W "$fixedWords" -- $cur ) )
+	fi
+
+	return 0
+}
+"""     % {
+            "cmds": self.command_names(),
+            "function_name": self.function_name,
+            "cases": self.command_cases(),
+            "global_options": self.global_options(),
+            "debug": self.debug_output(),
+        })
+
+    def command_names(self):
+        return " ".join(self.data.all_command_aliases())
+
+    def debug_output(self):
+        if not self.debug:
+            return ''
+        else:
+            return (r"""
+	# Debugging code enabled using the --debug command line switch.
+	# Will dump some variables to the top portion of the terminal.
+	echo -ne '\e[s\e[H'
+	for (( i=0; i < ${#COMP_WORDS[@]}; ++i)); do
+		echo "\$COMP_WORDS[$i]='${COMP_WORDS[i]}'"$'\e[K'
+	done
+	for i in COMP_CWORD COMP_LINE COMP_POINT COMP_TYPE COMP_KEY cur curOpt; do
+		echo "\$${i}=\"${!i}\""$'\e[K'
+	done
+	echo -ne '---\e[K\e[u'
+""")
+
+    def bzr_version(self):
+        bzr_version = bzrlib.version_string
+        if not self.data.plugins:
+            bzr_version += "."
+        else:
+            bzr_version += " and the following plugins:"
+            for name, plugin in sorted(self.data.plugins.iteritems()):
+                bzr_version += "\n# %s" % plugin
+        return bzr_version
+
+    def global_options(self):
+        return " ".join(sorted(self.data.global_options))
+
+    def command_cases(self):
+        cases = ""
+        for command in self.data.commands:
+            cases += self.command_case(command)
+        return cases
+
+    def command_case(self, command):
+        case = "\t%s)\n" % "|".join(command.aliases)
+        if command.plugin:
+            case += "\t\t# plugin \"%s\"\n" % command.plugin
+        options = []
+        enums = []
+        for option in command.options:
+            for message in option.error_messages:
+                case += "\t\t# %s\n" % message
+            if option.registry_keys:
+                for key in option.registry_keys:
+                    options.append("%s=%s" % (option, key))
+                enums.append("%s) optEnums='%s' ;;" %
+                             (option, ' '.join(option.registry_keys)))
+            else:
+                options.append(str(option))
+        case += "\t\tcmdOpts='%s'\n" % " ".join(options)
+        if command.fixed_words:
+            fixed_words = command.fixed_words
+            if isinstance(fixed_words, list):
+                fixed_words = "'%s'" + ' '.join(fixed_words)
+            case += "\t\tfixedWords=%s\n" % fixed_words
+        if enums:
+            case += "\t\tcase $curOpt in\n\t\t\t"
+            case += "\n\t\t\t".join(enums)
+            case += "\n\t\tesac\n"
+        case += "\t\t;;\n"
+        return case
+
+
+class CompletionData(object):
+
+    def __init__(self):
+        self.plugins = {}
+        self.global_options = set()
+        self.commands = []
+
+    def all_command_aliases(self):
+        for c in self.commands:
+            for a in c.aliases:
+                yield a
+
+
+class CommandData(object):
+
+    def __init__(self, name):
+        self.name = name
+        self.aliases = [name]
+        self.plugin = None
+        self.options = []
+        self.fixed_words = None
+
+
+class PluginData(object):
+
+    def __init__(self, name, version=None):
+        if version is None:
+            version = bzrlib.plugin.plugins()[name].__version__
+        self.name = name
+        self.version = version
+
+    def __str__(self):
+        if self.version == 'unknown':
+            return self.name
+        return '%s %s' % (self.name, self.version)
+
+
+class OptionData(object):
+
+    def __init__(self, name):
+        self.name = name
+        self.registry_keys = None
+        self.error_messages = []
+
+    def __str__(self):
+        return self.name
+
+    def __cmp__(self, other):
+        return cmp(self.name, other.name)
+
+
+class DataCollector(object):
+
+    def __init__(self, no_plugins=False, selected_plugins=None):
+        self.data = CompletionData()
+        self.user_aliases = {}
+        if no_plugins:
+            self.selected_plugins = set()
+        elif selected_plugins is None:
+            self.selected_plugins = None
+        else:
+            self.selected_plugins = set([x.replace('-', '_')
+                                         for x in selected_plugins])
+
+    def collect(self):
+        self.global_options()
+        self.aliases()
+        self.commands()
+        return self.data
+
+    def global_options(self):
+        re_switch = re.compile(r'\n(--[A-Za-z0-9-_]+)(?:, (-\S))?\s')
+        help_text = help_topics.topic_registry.get_detail('global-options')
+        for long, short in re_switch.findall(help_text):
+            self.data.global_options.add(long)
+            if short:
+                self.data.global_options.add(short)
+
+    def aliases(self):
+        for alias, expansion in config.GlobalConfig().get_aliases().iteritems():
+            for token in commands.shlex_split_unicode(expansion):
+                if not token.startswith("-"):
+                    self.user_aliases.setdefault(token, set()).add(alias)
+                    break
+
+    def commands(self):
+        for name in sorted(commands.all_command_names()):
+            self.command(name)
+
+    def command(self, name):
+        cmd = commands.get_cmd_object(name)
+        cmd_data = CommandData(name)
+
+        plugin_name = cmd.plugin_name()
+        if plugin_name is not None:
+            if (self.selected_plugins is not None and
+                plugin not in self.selected_plugins):
+                return None
+            plugin_data = self.data.plugins.get(plugin_name)
+            if plugin_data is None:
+                plugin_data = PluginData(plugin_name)
+                self.data.plugins[plugin_name] = plugin_data
+            cmd_data.plugin = plugin_data
+        self.data.commands.append(cmd_data)
+
+        # Find all aliases to the command; both cmd-defined and user-defined.
+        # We assume a user won't override one command with a different one,
+        # but will choose completely new names or add options to existing
+        # ones while maintaining the actual command name unchanged.
+        cmd_data.aliases.extend(cmd.aliases)
+        cmd_data.aliases.extend(sorted([useralias
+            for cmdalias in cmd_data.aliases
+            if cmdalias in self.user_aliases
+            for useralias in self.user_aliases[cmdalias]
+            if useralias not in cmd_data.aliases]))
+
+        opts = cmd.options()
+        for optname, opt in sorted(opts.iteritems()):
+            cmd_data.options.extend(self.option(opt))
+
+        if 'help' == name or 'help' in cmd.aliases:
+            cmd_data.fixed_words = ('"$cmds %s"' %
+                " ".join(sorted(help_topics.topic_registry.keys())))
+
+        return cmd_data
+
+    def option(self, opt):
+        optswitches = {}
+        parser = option.get_optparser({opt.name: opt})
+        parser = self.wrap_parser(optswitches, parser)
+        optswitches.clear()
+        opt.add_option(parser, opt.short_name())
+        if isinstance(opt, option.RegistryOption) and opt.enum_switch:
+            enum_switch = '--%s' % opt.name
+            enum_data = optswitches.get(enum_switch)
+            if enum_data:
+                try:
+                    enum_data.registry_keys = opt.registry.keys()
+                except ImportError, e:
+                    enum_data.error_messages.append(
+                        "ERROR getting registry keys for '--%s': %s"
+                        % (opt.name, str(e).split('\n')[0]))
+        return sorted(optswitches.values())
+
+    def wrap_container(self, optswitches, parser):
+        def tweaked_add_option(*opts, **attrs):
+            for name in opts:
+                optswitches[name] = OptionData(name)
+        parser.add_option = tweaked_add_option
+        return parser
+
+    def wrap_parser(self, optswitches, parser):
+        orig_add_option_group = parser.add_option_group
+        def tweaked_add_option_group(*opts, **attrs):
+            return self.wrap_container(optswitches,
+                orig_add_option_group(*opts, **attrs))
+        parser.add_option_group = tweaked_add_option_group
+        return self.wrap_container(optswitches, parser)
+
+
+def bash_completion_function(out, function_name="_bzr", function_only=False,
+                             debug=False,
+                             no_plugins=False, selected_plugins=None):
+    dc = DataCollector(no_plugins=no_plugins, selected_plugins=selected_plugins)
+    data = dc.collect()
+    cg = BashCodeGen(data, function_name=function_name, debug=debug)
+    if function_only:
+        res = cg.function()
+    else:
+        res = cg.script()
+    out.write(res)
+
+
+class cmd_bash_completion(commands.Command):
+    __doc__ = """Generate a shell function for bash command line completion.
+
+    This command generates a shell function which can be used by bash to
+    automatically complete the currently typed command when the user presses
+    the completion key (usually tab).
+    
+    Commonly used like this:
+        eval "`bzr bash-completion`"
+    """
+
+    takes_options = [
+        option.Option("function-name", short_name="f", type=str, argname="name",
+               help="Name of the generated function (default: _bzr)"),
+        option.Option("function-only", short_name="o", type=None,
+               help="Generate only the shell function, don't enable it"),
+        option.Option("debug", type=None, hidden=True,
+               help="Enable shell code useful for debugging"),
+        option.ListOption("plugin", type=str, argname="name",
+                # param_name="selected_plugins", # doesn't work, bug #387117
+                help="Enable completions for the selected plugin"
+                + " (default: all plugins)"),
+        ]
+
+    def run(self, **kwargs):
+        import sys
+        from bashcomp import bash_completion_function
+        if 'plugin' in kwargs:
+            # work around bug #387117 which prevents us from using param_name
+            if len(kwargs['plugin']) > 0:
+                kwargs['selected_plugins'] = kwargs['plugin']
+            del kwargs['plugin']
+        bash_completion_function(sys.stdout, **kwargs)
+
+
+if __name__ == '__main__':
+
+    import sys
+    import locale
+    import optparse
+
+    def plugin_callback(option, opt, value, parser):
+        values = parser.values.selected_plugins
+        if value == '-':
+            del values[:]
+        else:
+            values.append(value)
+
+    parser = optparse.OptionParser(usage="%prog [-f NAME] [-o]")
+    parser.add_option("--function-name", "-f", metavar="NAME",
+                      help="Name of the generated function (default: _bzr)")
+    parser.add_option("--function-only", "-o", action="store_true",
+                      help="Generate only the shell function, don't enable it")
+    parser.add_option("--debug", action="store_true",
+                      help=optparse.SUPPRESS_HELP)
+    parser.add_option("--no-plugins", action="store_true",
+                      help="Don't load any bzr plugins")
+    parser.add_option("--plugin", metavar="NAME", type="string",
+                      dest="selected_plugins", default=[],
+                      action="callback", callback=plugin_callback,
+                      help="Enable completions for the selected plugin"
+                      + " (default: all plugins)")
+    (opts, args) = parser.parse_args()
+    if args:
+        parser.error("script does not take positional arguments")
+    kwargs = dict()
+    for name, value in opts.__dict__.iteritems():
+        if value is not None:
+            kwargs[name] = value
+
+    locale.setlocale(locale.LC_ALL, '')
+    if not kwargs.get('no_plugins', False):
+        plugin.load_plugins()
+    commands.install_bzr_command_hooks()
+    bash_completion_function(sys.stdout, **kwargs)

=== added directory 'bzrlib/plugins/bash_completion/tests'
=== added file 'bzrlib/plugins/bash_completion/tests/__init__.py'
--- bzrlib/plugins/bash_completion/tests/__init__.py	1970-01-01 00:00:00 +0000
+++ bzrlib/plugins/bash_completion/tests/__init__.py	2010-05-05 08:10:48 +0000
@@ -0,0 +1,23 @@
+# Copyright (C) 2010 by Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+def load_tests(basic_tests, module, loader):
+    testmod_names = [
+        'test_bashcomp',
+        ]
+    basic_tests.addTest(loader.loadTestsFromModuleNames(
+            ["%s.%s" % (__name__, tmn) for tmn in testmod_names]))
+    return basic_tests

=== added file 'bzrlib/plugins/bash_completion/tests/test_bashcomp.py'
--- bzrlib/plugins/bash_completion/tests/test_bashcomp.py	1970-01-01 00:00:00 +0000
+++ bzrlib/plugins/bash_completion/tests/test_bashcomp.py	2010-05-05 08:10:48 +0000
@@ -0,0 +1,318 @@
+# Copyright (C) 2010 by Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+import bzrlib
+from bzrlib import commands, tests
+from bzrlib.plugins.bash_completion.bashcomp import *
+
+import os
+import subprocess
+
+
+class _BashFeature(tests.Feature):
+    """Feature testing whether a bash executable is available."""
+
+    bash_paths = ['/bin/bash', '/usr/bin/bash']
+
+    def __init__(self):
+        super(_BashFeature, self).__init__()
+        self.bash_path = None
+
+    def available(self):
+        if self.bash_path is not None:
+            return self.bash_path is not False
+        for path in self.bash_paths:
+            if os.access(path, os.X_OK):
+                self.bash_path = path
+                return True
+        self.bash_path = False
+        return False
+
+    def feature_name(self):
+        return 'bash'
+
+BashFeature = _BashFeature()
+
+
+class BashCompletionMixin(object):
+    """Component for testing execution of a bash completion script."""
+
+    _test_needs_features = [BashFeature]
+
+    def complete(self, words, cword=-1):
+        """Perform a bash completion.
+
+        :param words: a list of words representing the current command.
+        :param cword: the current word to complete, defaults to the last one.
+        """
+        if self.script is None:
+            self.script = self.get_script()
+        proc = subprocess.Popen([BashFeature.bash_path, '--noprofile'],
+                                stdin=subprocess.PIPE,
+                                stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE)
+        if cword < 0:
+            cword = len(words) + cword
+        input = '%s\n' % self.script
+        input += ('COMP_WORDS=( %s )\n' %
+                  ' '.join(["'"+w.replace("'", "'\\''")+"'" for w in words]))
+        input += 'COMP_CWORD=%d\n' % cword
+        input += '%s\n' % getattr(self, 'script_name', '_bzr')
+        input += 'echo ${#COMPREPLY[*]}\n'
+        input += "IFS=$'\\n'\n"
+        input += 'echo "${COMPREPLY[*]}"\n'
+        (out, err) = proc.communicate(input)
+        if '' != err:
+            raise AssertionError('Unexpected error message:\n%s' % err)
+        self.assertEqual('', err, 'No messages to standard error')
+        #import sys
+        #print >>sys.stdout, '---\n%s\n---\n%s\n---\n' % (input, out)
+        lines = out.split('\n')
+        nlines = int(lines[0])
+        del lines[0]
+        self.assertEqual('', lines[-1], 'Newline at end')
+        del lines[-1]
+        if nlines == 0 and len(lines) == 1 and lines[0] == '':
+            del lines[0]
+        self.assertEqual(nlines, len(lines), 'No newlines in generated words')
+        self.completion_result = set(lines)
+        return self.completion_result
+
+    def assertCompletionEquals(self, *words):
+        self.assertEqual(set(words), self.completion_result)
+
+    def assertCompletionContains(self, *words):
+        missing = set(words) - self.completion_result
+        if missing:
+            raise AssertionError('Completion should contain %r but it has %r'
+                                 % (missing, self.completion_result))
+
+    def assertCompletionOmits(self, *words):
+        surplus = set(words) & self.completion_result
+        if surplus:
+            raise AssertionError('Completion should omit %r but it has %r'
+                                 % (surplus, res, self.completion_result))
+
+    def get_script(self):
+        commands.install_bzr_command_hooks()
+        dc = DataCollector()
+        data = dc.collect()
+        cg = BashCodeGen(data)
+        res = cg.function()
+        return res
+
+
+class TestBashCompletion(tests.TestCase, BashCompletionMixin):
+    """Test bash completions that don't execute bzr."""
+
+    def __init__(self, methodName='testMethod'):
+        super(TestBashCompletion, self).__init__(methodName)
+        self.script = None
+
+    def test_simple_scipt(self):
+        """Ensure that the test harness works as expected"""
+        self.script = """
+_bzr() {
+    COMPREPLY=()
+    # add all words in reverse order, with some markup around them
+    for ((i = ${#COMP_WORDS[@]}; i > 0; --i)); do
+        COMPREPLY+=( "-${COMP_WORDS[i-1]}+" )
+    done
+    # and append the current word
+    COMPREPLY+=( "+${COMP_WORDS[COMP_CWORD]}-" )
+}
+"""
+        self.complete(['foo', '"bar', "'baz"], cword=1)
+        self.assertCompletionEquals("-'baz+", '-"bar+', '-foo+', '+"bar-')
+
+    def test_cmd_ini(self):
+        self.complete(['bzr', 'ini'])
+        self.assertCompletionContains('init', 'init-repo', 'init-repository')
+        self.assertCompletionOmits('commit')
+
+    def test_init_opts(self):
+        self.complete(['bzr', 'init', '-'])
+        self.assertCompletionContains('-h', '--2a', '--format=2a')
+
+    def test_global_opts(self):
+        self.complete(['bzr', '-', 'init'], cword=1)
+        self.assertCompletionContains('--no-plugins', '--builtin')
+
+    def test_commit_dashm(self):
+        self.complete(['bzr', 'commit', '-m'])
+        self.assertCompletionEquals('-m')
+
+    def test_status_negated(self):
+        self.complete(['bzr', 'status', '--n'])
+        self.assertCompletionContains('--no-versioned', '--no-verbose')
+
+    def test_init_format_any(self):
+        self.complete(['bzr', 'init', '--format', '=', 'directory'], cword=3)
+        self.assertCompletionContains('1.9', '2a')
+
+    def test_init_format_2(self):
+        self.complete(['bzr', 'init', '--format', '=', '2', 'directory'],
+                      cword=4)
+        self.assertCompletionContains('2a')
+        self.assertCompletionOmits('1.9')
+
+
+class TestBashCompletionInvoking(tests.TestCaseWithTransport,
+                                 BashCompletionMixin):
+    """Test bash completions that might execute bzr.
+
+    Only the syntax ``$(bzr ...`` is supported so far. The bzr command
+    will be replaced by the bzr instance running this selftest.
+    """
+
+    def __init__(self, methodName='testMethod'):
+        super(TestBashCompletionInvoking, self).__init__(methodName)
+        self.script = None
+
+    def get_script(self):
+        s = super(TestBashCompletionInvoking, self).get_script()
+        return s.replace("$(bzr ", "$('%s' " % self.get_bzr_path())
+
+    def test_revspec_tag_all(self):
+        wt = self.make_branch_and_tree('.', format='dirstate-tags')
+        wt.branch.tags.set_tag('tag1', 'null:')
+        wt.branch.tags.set_tag('tag2', 'null:')
+        wt.branch.tags.set_tag('3tag', 'null:')
+        self.complete(['bzr', 'log', '-r', 'tag', ':'])
+        self.assertCompletionEquals('tag1', 'tag2', '3tag')
+
+    def test_revspec_tag_prefix(self):
+        wt = self.make_branch_and_tree('.', format='dirstate-tags')
+        wt.branch.tags.set_tag('tag1', 'null:')
+        wt.branch.tags.set_tag('tag2', 'null:')
+        wt.branch.tags.set_tag('3tag', 'null:')
+        self.complete(['bzr', 'log', '-r', 'tag', ':', 't'])
+        self.assertCompletionEquals('tag1', 'tag2')
+
+
+class TestBashCodeGen(tests.TestCase):
+
+    def test_command_names(self):
+        data = CompletionData()
+        bar = CommandData('bar')
+        bar.aliases.append('baz')
+        data.commands.append(bar)
+        data.commands.append(CommandData('foo'))
+        cg = BashCodeGen(data)
+        self.assertEqual('bar baz foo', cg.command_names())
+
+    def test_debug_output(self):
+        data = CompletionData()
+        self.assertEqual('', BashCodeGen(data, debug=False).debug_output())
+        self.assertTrue(BashCodeGen(data, debug=True).debug_output())
+
+    def test_bzr_version(self):
+        data = CompletionData()
+        cg = BashCodeGen(data)
+        self.assertEqual('%s.' % bzrlib.version_string, cg.bzr_version())
+        data.plugins['foo'] = PluginData('foo', '1.0')
+        data.plugins['bar'] = PluginData('bar', '2.0')
+        cg = BashCodeGen(data)
+        self.assertEqual('''\
+%s and the following plugins:
+# bar 2.0
+# foo 1.0''' % bzrlib.version_string, cg.bzr_version())
+
+    def test_global_options(self):
+        data = CompletionData()
+        data.global_options.add('--foo')
+        data.global_options.add('--bar')
+        cg = BashCodeGen(data)
+        self.assertEqual('--bar --foo', cg.global_options())
+
+    def test_command_cases(self):
+        data = CompletionData()
+        bar = CommandData('bar')
+        bar.aliases.append('baz')
+        bar.options.append(OptionData('--opt'))
+        data.commands.append(bar)
+        data.commands.append(CommandData('foo'))
+        cg = BashCodeGen(data)
+        self.assertEqualDiff('''\
+\tbar|baz)
+\t\tcmdOpts='--opt'
+\t\t;;
+\tfoo)
+\t\tcmdOpts=''
+\t\t;;
+''', cg.command_cases())
+
+    def test_command_case(self):
+        cmd = CommandData('cmd')
+        cmd.plugin = PluginData('plugger', '1.0')
+        bar = OptionData('--bar')
+        bar.registry_keys = ['that', 'this']
+        bar.error_messages.append('Some error message')
+        cmd.options.append(bar)
+        cmd.options.append(OptionData('--foo'))
+        data = CompletionData()
+        data.commands.append(cmd)
+        cg = BashCodeGen(data)
+        self.assertEqualDiff('''\
+\tcmd)
+\t\t# plugin "plugger 1.0"
+\t\t# Some error message
+\t\tcmdOpts='--bar=that --bar=this --foo'
+\t\tcase $curOpt in
+\t\t\t--bar) optEnums='that this' ;;
+\t\tesac
+\t\t;;
+''', cg.command_case(cmd))
+
+
+class TestDataCollector(tests.TestCase):
+
+    def setUp(self):
+        super(TestDataCollector, self).setUp()
+        commands.install_bzr_command_hooks()
+
+    def test_global_options(self):
+        dc = DataCollector()
+        dc.global_options()
+        self.assertSubset(['--no-plugins', '--builtin'],
+                           dc.data.global_options)
+
+    def test_commands(self):
+        dc = DataCollector()
+        dc.commands()
+        self.assertSubset(['init', 'init-repo', 'init-repository'],
+                           dc.data.all_command_aliases())
+
+    def test_commit_dashm(self):
+        dc = DataCollector()
+        cmd = dc.command('commit')
+        self.assertSubset(['-m'],
+                           [str(o) for o in cmd.options])
+
+    def test_status_negated(self):
+        dc = DataCollector()
+        cmd = dc.command('status')
+        self.assertSubset(['--no-versioned', '--no-verbose'],
+                           [str(o) for o in cmd.options])
+
+    def test_init_format(self):
+        dc = DataCollector()
+        cmd = dc.command('init')
+        for opt in cmd.options:
+            if opt.name == '--format':
+                self.assertSubset(['2a'], opt.registry_keys)
+                return
+        raise AssertionError('Option --format not found')

=== added file 'contrib/bash/bzr'
--- contrib/bash/bzr	1970-01-01 00:00:00 +0000
+++ contrib/bash/bzr	2010-05-05 08:10:48 +0000
@@ -0,0 +1,40 @@
+# Copyright (C) 2010 Canonical Ltd
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+# Programmable completion for the Bazaar-NG bzr command under bash.
+# Source this file (or add it to your ~/.bash_completion or ~/.bashrc
+# file, depending on your system configuration, and start a new shell)
+# and bash's completion mechanism will know all about bzr's options!
+#
+# This completion function assumes you have the bzr-bash-completion
+# plugin installed as a bzr plugin. It will generate the full
+# completion function at first invocation, thus avoiding long delays
+# for every shell you start.
+
+shopt -s progcomp
+_bzr_lazy ()
+{
+	unset _bzr
+	eval "$(bzr bash-completion)"
+	if [[ $(type -t _bzr) == function ]]; then
+		unset _bzr_lazy
+		_bzr
+		return $?
+	else
+		return 1
+	fi
+}
+complete -F _bzr_lazy -o default bzr

=== removed file 'contrib/bash/bzr'
--- contrib/bash/bzr	2005-09-19 06:05:19 +0000
+++ contrib/bash/bzr	1970-01-01 00:00:00 +0000
@@ -1,104 +0,0 @@
-# Programmable completion for the Bazaar-NG bzr command under bash. Source
-# this file (or on some systems add it to ~/.bash_completion and start a new
-# shell) and bash's completion mechanism will know all about bzr's options!
-
-# Known to work with bash 2.05a with programmable completion and extended
-# pattern matching enabled (use 'shopt -s extglob progcomp' to enable
-# these if they are not already enabled).
-
-# Based originally on the svn bash completition script.
-# Customized by Sven Wilhelm/Icecrash.com
-
-_bzr ()
-{
-	local cur cmds cmdOpts opt helpCmds optBase i
-
-	COMPREPLY=()
-	cur=${COMP_WORDS[COMP_CWORD]}
-
-	cmds='status diff commit ci checkin move remove log info check ignored'
-
-	if [[ $COMP_CWORD -eq 1 ]] ; then
-		COMPREPLY=( $( compgen -W "$cmds" -- $cur ) )
-		return 0
-	fi
-
-	# if not typing an option, or if the previous option required a
-	# parameter, then fallback on ordinary filename expansion
-	helpCmds='help|--help|h|\?'
-	if [[ ${COMP_WORDS[1]} != @($helpCmds) ]] && \
-	   [[ "$cur" != -* ]] ; then
-		return 0
-	fi
-
-	cmdOpts=
-	case ${COMP_WORDS[1]} in
-	status)
-		cmdOpts="--all --show-ids"
-		;;
-	diff)
-		cmdOpts="-r --revision --diff-options"
-		;;
-	commit|ci|checkin)
-		cmdOpts="-r --message -F --file -v --verbose"
-		;;
-	move)
-		cmdOpts=""
-		;;
-	remove)
-		cmdOpts="-v --verbose"
-		;;
-	log)
-		cmdOpts="--forward --timezone -v --verbose --show-ids -r --revision"
-		;;
-	info)
-		cmdOpts=""
-		;;
-	ignored)
-		cmdOpts=""
-		;;
-	check)
-		cmdOpts=""
-		;;
-	help|h|\?)
-		cmdOpts="$cmds $qOpts"
-		;;
-	*)
-		;;
-	esac
-
-	cmdOpts="$cmdOpts --help -h"
-
-	# take out options already given
-	for (( i=2; i<=$COMP_CWORD-1; ++i )) ; do
-		opt=${COMP_WORDS[$i]}
-
-		case $opt in
-		--*)    optBase=${opt/=*/} ;;
-		-*)     optBase=${opt:0:2} ;;
-		esac
-
-		cmdOpts=" $cmdOpts "
-		cmdOpts=${cmdOpts/ ${optBase} / }
-
-		# take out alternatives
-		case $optBase in
-		-v)              cmdOpts=${cmdOpts/ --verbose / } ;;
-		--verbose)       cmdOpts=${cmdOpts/ -v / } ;;
-		-h)              cmdOpts=${cmdOpts/ --help / } ;;
-		--help)          cmdOpts=${cmdOpts/ -h / } ;;
-		-r)              cmdOpts=${cmdOpts/ --revision / } ;;
-		--revision)      cmdOpts=${cmdOpts/ -r / } ;;
-		esac
-
-		# skip next option if this one requires a parameter
-		if [[ $opt == @($optsParam) ]] ; then
-			((++i))
-		fi
-	done
-
-	COMPREPLY=( $( compgen -W "$cmdOpts" -- $cur ) )
-
-	return 0
-}
-complete -F _bzr -o default bzr

=== removed file 'contrib/bash/bzr.simple'
--- contrib/bash/bzr.simple	2007-06-06 19:44:39 +0000
+++ contrib/bash/bzr.simple	1970-01-01 00:00:00 +0000
@@ -1,28 +0,0 @@
-# -*- shell-script -*-
-
-# experimental bzr bash completion
-
-# author: Martin Pool
-
-_bzr_commands() 
-{
-     bzr help commands | sed -r 's/^([-[:alnum:]]*).*/\1/' | grep '^[[:alnum:]]' 
-}
-
-_bzr() 
-{
-    cur=${COMP_WORDS[COMP_CWORD]}
-    prev=${COMP_WORDS[COMP_CWORD-1]}
-    if [ $COMP_CWORD -eq 1 ]; then
-        COMPREPLY=( $( compgen -W "$(_bzr_commands)" $cur ) )
-    elif [ $COMP_CWORD -eq 2 ]; then
-        case "$prev" in 
-        help)
-            COMPREPLY=( $( compgen -W "$(_bzr_commands) commands" $cur ) )
-            ;;
-        esac
-    fi 
-}
-
-complete -F _bzr -o default bzr
-