Proper bash completion for Qubes OS commands (mostly qvm-)

[jma...@tutanota.com]

Hi all,

I would like to contribute to the Qubes OS project by making proper bash-completion of Qubes OS commands (primary for qvm-* commands).
The related issue: https://github.com/QubesOS/qubes-issues/issues/7887

Before doing something I analyzed the existing solutions - mostly this two:
https://github.com/jgriffiths/qubes-completion/blob/master/qvm_completion.sh
https://github.com/Qubes-Community/Contents/blob/master/code/productivity/qvm-cmds-bash-completion.bash

And while both of these solutions are interesting, have different features and ideas, they still have major drawbacks and do not fit my high expectations.
I would like to make a better one, taking ideas from these two and best practices from bash completion of other GNU/Linux tools.
I would want the new completion to be as clever, advanced and comfortable to use as possible.

To achieve it I hope some of devs could answer some technical questions I have.
Starting with these:

1) I see some inconsistencies in `man qvm-clone` maybe because it was generated automatically. So, which one is the proper syntax:
`--pool POOL_NAME:VOLUME_NAME` or
`--pool=POOL_NAME:VOLUME_NAME`?
Or both are allowed?
The same for `--property` - must it follow with = sign or not?

2) Are names of qubes allowed to start from "-" (I really hope not).

3) What do *-chars in `--property NAME*=*VALUE` mean?

4) Are options really allowed only before VMs's names in commands like `qvm-clone` (the `man qvm-clone` says so)?
I would like to respect this strictness in completion to provide the best completion experience possible.

5) Is `man qvm-create` broken in the first paragraph of Synopsis? It has `qvm-create` the second time on the same line (last one) of the first paragraph.
The `qvm-create --help` does not provide information about the second way of calling:
$ qvm-create --help-classes
Bash completion for sure should take all valid options into account.

6) What name would be recommended for this completion in case it goes to qubes packages?
I think something like generic `qubes-bash-completion`or `qubes-completion` is fine, but different people make different names for it. So, maybe you have opinion on that too.

7) Will it be possible and is it desired to add these completions to the default Qubes OS packaging system to give them to users out of the box?

--
Best regards,
jamke

[Demi Marie Obenour]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On Sat, Dec 17, 2022 at 08:30:31AM +0100, Qubes OS Development Mailing List wrote:
> Hi all,
>
> I would like to contribute to the Qubes OS project by making proper bash-completion of Qubes OS commands (primary for qvm-* commands).
> The related issue: https://github.com/QubesOS/qubes-issues/issues/7887
>
> Before doing something I analyzed the existing solutions - mostly this two:
> https://github.com/jgriffiths/qubes-completion/blob/master/qvm_completion.sh
> https://github.com/Qubes-Community/Contents/blob/master/code/productivity/qvm-cmds-bash-completion.bash
>
> And while both of these solutions are interesting, have different features and ideas, they still have major drawbacks and do not fit my high expectations.
> I would like to make a better one, taking ideas from these two and best practices from bash completion of other GNU/Linux tools.
> I would want the new completion to be as clever, advanced and comfortable to use as possible.
>
> To achieve it I hope some of devs could answer some technical questions I have.
> Starting with these:
>
> 1) I see some inconsistencies in `man qvm-clone` maybe because it was generated automatically. So, which one is the proper syntax:
> `--pool POOL_NAME:VOLUME_NAME` or
> `--pool=POOL_NAME:VOLUME_NAME`?
> Or both are allowed?
> The same for `--property` - must it follow with = sign or not?

Both are allowed in both cases.

> 2) Are names of qubes allowed to start from "-" (I really hope not).

Qube names must match the POSIX Extended Regular Expression
^[A-Za-z][A-Za-z0-9_-]{0,30}$. Therefore, qube names must not start
with ‘-’. However, your code should be robust against ‘qvm-ls --raw’
and friends returning names that do start with a ‘-’.

> 3) What do *-chars in `--property NAME*=*VALUE` mean?

That the man page has a bug. Please report it.

> 4) Are options really allowed only before VMs's names in commands like `qvm-clone` (the `man qvm-clone` says so)?
> I would like to respect this strictness in completion to provide the best completion experience possible.

I recommend assuming that they are.

> 5) Is `man qvm-create` broken in the first paragraph of Synopsis? It has `qvm-create` the second time on the same line (last one) of the first paragraph.
> The `qvm-create --help` does not provide information about the second way of calling:
> $ qvm-create --help-classes

I believe the man page is correct here.

> Bash completion for sure should take all valid options into account.
>
> 6) What name would be recommended for this completion in case it goes to qubes packages?
> I think something like generic `qubes-bash-completion`or `qubes-completion` is fine, but different people make different names for it. So, maybe you have opinion on that too.

I prefer ‘qubes-completion’, as this may be extended to support other
shells in the future.

> 7) Will it be possible and is it desired to add these completions to the default Qubes OS packaging system to give them to users out of the box?

That is up to Marek, but I would support it.
- --
Sincerely,
Demi Marie Obenour (she/her/hers)
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEdodNnxM2uiJZBxxxsoi1X/+cIsEFAmOk3sQACgkQsoi1X/+c
IsGlNBAAsYc7HmhG+lS/DP0Z1Jk+3Lbwa9qb6+5Jfr7rx3ADaZyAH76VaaOSGGSS
xinDx3gJyT0D15SQuQxZInL0A0uauYI5huxbkuS9VAw5437Gq2wMp6mdd2KeilQL
5GyE508SzI+50v/brt8s9TUG8CQLpyZg9TUwhOPcUZVLXIWuS37ymRUd4Hpklu27
5hId5wfRtmw+lcj09RS0SuLUyCkLPhCFxLjB+1V8LU01Oiq1m21etCmtNbwdkXa2
O1J1qx/ALVYNK4J3A+wmA15nwD8v7wuiDcQS/XtH3EJgx1yBkAHbx53QKHJjW7oQ
wnor5QmsuS2xT2ec76Oi8E6AyfqKFCW6j2gW/Yr/KJeyxRINAQrkZHEyzxap3ll4
XxsycSt1H0nWVDuSjL6Y6Z9g+4Y8WufQKQJEvhi9KO/LsAZ9l/qIzyehRl0KScPL
j6AtNkSlKTadNkGYy4bJJAG0MlGxYaxD9TQ2s71gFKLKnZ5cCEqFon+Ic35uDpbJ
rj8aKmA3jRGo2wa4EikPIFQIJcVHfkHt57FaLHBOFs9eb0R9NG6KZABbaRH4gS4i
N94/mNmtRr5Y0wvXZ0uR5lLe6BTqRQuveE43hWgGucefk/ypIUSwRaSPZhhtuRxS
FmGtvLgHyMjLoufNoXKNuJqO9KMLvBnrglthT4ZJwXnLtenvO3I=
=f0EN
-----END PGP SIGNATURE-----

[jma...@tutanota.com]

The project of proper bash completion for Qubes OS is ready for testing.

It currently is available here:
https://github.com/jamke/qubes-completion

It includes documentation about the project and installation instructions.The project also has tests (using BATS framework) that require further improvements.

Currently I would like somebody from the Team to make some kind of code review or to provide some feedback on code quality and information how well it works for you.
Feedback from average users will also be appreciated.
So, feel free to try.


--
Best regards,
jamke



Dec 17, 2022, 17:18 by qubes...@googlegroups.com:

> --
> You received this message because you are subscribed to the Google Groups "qubes-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/NJTqEiG--3-9%40tutanota.com.
>

[jma...@tutanota.com]

# New release **1.0.2** of `qubes-completion` was published today.

To try it: https://github.com/jamke/qubes-completion/releases/tag/v1.0.2

### Change log:
* Add support for `qvm-backup` and `qvm-backup-restore`
* Update all basic tests
* Remove third-party code
* Avoid qube completion with `dom0` for some unsuitable cases
* Add submodules of BATS
* Improve README
* Minor typo fixes and improvements

### Installation:

1. install `bash-completion` package in `dom0`:
`sudo qubes-dom0-update bash-completion`
2. put bash script-file attached to the release `qubes-completion.sh`  to `/etc/bash_completion.d/` in `dom0`.

More details can be found in the README file.

### Note:

This the release was made with a help of Qubes OS community!

Thanks to all contributors, here is a list of them on github:
https://github.com/jamke/qubes-completion/graphs/contributors