Shell completion scripts outdated

[Martin von Gagern]

The shell completion scripts shipped with bzr are seriously outdated.

* contrib/bash/bzr.simple from r2514, 2007-06-06 (bzr-0.91)
+ Completes command names.
+ Generates list of commands from bzr help invocation.
- No completion for built-in or user-configured aliases.
- No completion for options.
- Confused by global options preceding the bzr command name.
- Slow due to bzr invocation for list of commands.
OK, this isn't really outdated, it is only a bit too simple imho.

* contrib/bash/bzr from r620, 2005-06-02 (bzr-0.0.5)
+ Completes command names and options.
- Fixed list of commands and their options.
- A lot of recent commands and options are missing.
- All plugin commands are missing.
I guess this is installed by many distros, but it seems insufficient for practical use.

* contrib/zsh/_bzr from r331, 2005-05-03 (bzr-0.0.5)
+ Very verbose, including help texts for many completions.
+ Detailed handling of expected parameters in many cases.
- Fixed list of commands and their options.
- A lot of recent commands and options are missing.
- Some plugins are hardcoded into the list, whether they are installed or not.
- Slow due to bzr invocations for several types, e.g. versioned files.
It seems that zsh itself ships a slightly more recent version of this script.

Notice that none of these completions scripts uses the "bzr shell-complete" command.
Notice also that there is a bash_completion mode of tools/generate_docs.py, but that fails according to bug #250071.

I know these completion scripts are contributed, and therefore probably not maintained officially. Nevertheless, I sometimes wonder whether dropping them might be better.

For bash, the bzr-bash-completion plugin I wrote (originally based on the contrib/bash/bzr script) gives reasonable flexibility and performance, in particular if using the lazy initialization of the completion function as employed by the lazy.sh script. So dropping the outdated scripts and replacing them with some reference to the completion plugin might be better. Users have requested my completion plugin to be included in bzr core. So I'm also offering the code for inclusion if you want it.

For zsh, even using the script shipped with recent versions of zsh is probably better than this outdated script in the bzr tree, so dropping it would seem prudent as well. I think there are also some scripts out there actually making use of the bzr shell-complete command, although this has a considerable impact on performance unless used with bzrc. I'm not using zsh, so I don't know if any of these might be a good candidate for inclusion.

[Martin Pool (mbp)]

> I know these completion scripts are contributed, and therefore probably not maintained officially. Nevertheless, I sometimes wonder whether dropping them might be better.

I don't think we have (or should have) a category of in-the-tree but not maintained code for contrib. Probably much of what's currently in there should be reclassified as "examples" or "integration" or just deleted.

If you have looked into this and don't think there is value in shipping them, let's delete them. Would you like to put up a merge proposal?

[Robert Collins (lifeless)]

Do distros ship and use the scripts we include? If so, we should make sure replacements are clearly identified and coordinate that.

[Martin von Gagern (gagern)]

> Do distros ship and use the scripts we include?

Debian, Ubuntu: yes, /etc/bash_completion.d/bzr and bzr.simple
Fedora Core: yes, /etc/bash_completion.d/bzr
Gentoo: configurable, /usr/share/bash-completion/bzr

> If so, we should make sure replacements are clearly identified

That's why I added README files to the attached branch.

> and coordinate that.

Coordinate it in what way? Contact maintainers of the amjor distros?

[Martin von Gagern (gagern)]

As far as I can tell, no major distro ships the zsh completion script.

If you want to avoid dropping the bzr bash script, there are two alternatives that come to my mind. Both involve the bzr-bash-completion plugin. Let' call the drop "Option 1" for now.

Option 2 would be adding the plugin to the tree of bzr itself. In that case the bzr completion script could be replaced by the lazy initialization script shipped with the plugin. That installs a tiny shell script which generates the full completion function upon first invocation, keeping bash init times low and still avoiding the overhead of a bzr invocation for every command completion except the first.

Option 3 would be shipping a script generated by that plugin. If that is desired, it should be in some way rigged into the release process, to make sure that the script matches the set of commands and options available in the released version, and that it uses a well-defined list of plugins for which it outputs completions as well.

As a quick hack, I could of course provide a branch replacing the outdated script with a version generated from current bzr.dev, but I assume that such a file would become obsolete pretty soon, so in the long run this is not much of an improvement over the current state of affairs.

[Robert Collins (lifeless)]

I'm happy for us to drop them, but we don't want the major distros to have
unexpected work when they do the next major version update; it would be best
I think to get them to ship the alternatives (if they are infact better :P)
before removing them in a bzr release.

[Martin von Gagern (gagern)]

Jelmer is aware of the planned removal of the old scripts for Debian, and abadger1999 aka. Toshio for Fedora.
Toshio suggested I include links to bzr-bash-completion here: https://launchpad.net/bzr-bash-completion (branches, bugs, ...) and http://pypi.python.org/pypi/bzr-bash-completion (documentation)

Toshio isn't happy about yet another bzr plugin package, though, and would much prefer seeing it in core:
http://irclogs.ubuntu.com/2010/04/20/%23bzr.html#t14:36
Jelmer stated a while ago that in his opinion, a completion script should be shipped with either bzr or bash:
http://irclogs.ubuntu.com/2010/04/10/%23bzr.html#t16:51
And Mark Lee, the maintainer of the Gentoo overlay for bzr-related stuff, would like to see it in core as well:
https://code.launchpad.net/~gagern/bzr-gentoo-overlay/bzr-bash-completion/+merge/21372

So it seems that packagers in general would like to see the plugin included in the bzr source tree, i.e. option 2. Toshio argues that this would also make bzr look better in a direct core feature comparison with various other VCSs. If core developers decide they want the plugin, I'd be happy to provide a merge request for option 2 as well.

[Henrik Nordström (henriknordstrom)]

If the plugin works well then I would prefer Option 2. I also assume would automatically extend bzr completion to cover the commands of currently installed plugins?

But no strong feelings either way. All options including the quick hack works for me.

Regards
Henrik Nordström
Fedora packager

[Marius Kruger (amanica)]

On 20 April 2010 09:34, Martin von Gagern <email address hidden> wrote:
> Option 2 would be adding the plugin to the tree of bzr itself. In that
> case the bzr completion script could be replaced by the lazy
> initialization script shipped with the plugin. That installs a tiny
> shell script which generates the full completion function upon first
> invocation, keeping bash init times low and still avoiding the overhead
> of a bzr invocation for every command completion except the first.

Would this option also auto-complete commands (and aliases) provided by plugins?

If a user installs new plugins, can it be forced to refresh the
commandlist? (automatically refreshing would be best but I can't think
of an easy way to trigger that)

+1 for shipping with it in core

[Martin von Gagern (gagern)]

Yes, the bzr-bash-completion plugin handles plugins, hardwired option aliases and custom aliases configured by the user.
Refreshing the list can be done by starting a new shell session, or by executing this line:
$ eval "`bzr bash-completion`"
The plugin documentation does give you this information as well, so you don't have to memorize this command.

Auto-detection of plugin additions and in particular plugin manipulations would indeed be hard, as it would most likely involve a performance hit comparable to the generation of the completeion function dynamically for every completion. I consider the "once per session" approach to be a good compromise between longer file-based caches on the one hand and no caches at all on the other hand. Most users tend to change their bzr rather infrequently.

After wrestling with bug #370710 for a while, I'll try to migrate the bzr-bash-completion plugin to a rich-root format suitable for joining with bzr.dev, and provide a joined tree and probably a merge request for it as well.