Re: Guix CLI, thoughts and suggestions

[Efraim Flashner <efraim@flashner.co.il>]

[-- Attachment #1: Type: text/plain, Size: 6933 bytes --]

On Mon, Jan 15, 2024 at 11:24:29AM -0800, Ian Eure wrote:
> Greetings,
> 
> As I’ve been learning Guix, one of the things I’ve found somewhat unpleasant
> is the lack of consistency within the guix CLI tool. It feels a bit
> Git-like, with not much consistency, commands that non-obvioulsy perform
> more than operation, related commands in different places in the tree, etc.
> 
> Just so you know where I’m coming from: I’ve found that compliex CLI tooling
> benefits from organization and consistency.  The Linux ip(8) command is a
> good example of this kind of organization: to add an IP address, you use `ip
> address add'.  To show address, `ip address show', and to remove one `ip
> address del'.  When options are needed, they get added after the verb or
> branch in the verb tree; the final verb may take positional arguments as
> well as --long or -s (short)-form options.
> 
> Some examples of where I think Guix could do better.  This is an
> illustrative list, not an exhaustive one.
> 
> Inconsistent organization
> =========================
> 
> Most package-related commands are under `guix package', but many are sibling
> commands.  Examples are `guix size', `guix lint', `guix hash', etc.
> 
> 
> Inconsistency between verbs and options
> =======================================
> 
> Some verbs are bare-word positional arguments, and others are flags to
> related verbs.  IMO, this is the biggest problem, and makes it very
> difficult to find all the things the CLI can do. `guix package' is a major
> offender in this area, as it mixes verbs and verb-specific options into the
> same level.  For example, installing a package is `guix package -i foo'
> rather than `guix package install foo', removing is `guix package -r foo'
> rather than `guix package remove foo', and listing installed packages is
> `guix package -I' rather than `guix package installed' (or similar).
> 
> This means that users can express commands which *seem* like they should
> work, but do not.  For example `guix package -i emacs -r emacs-pgtk -I'
> represents a command to 1) install emacs 2) remove emacs-pgtk 3) list
> installed packages (which would verify the previous two operations
> occurred).  This is a valid command within the accepted organization of
> `guix package', and doesn’t cause an error, but doesn’t work: the install
> and remove steps are ignored.

I found this part surprising. I know you can chain together -i and -r,
but I had never tried adding -I to the list also, and it makes sense to
me that it should be able to be chained in also.

>                               A thing I’ve found throughout my career is
> that designing systems so it’s *impossible* to represent unsupported,
> nonsensical, or undefined things is an extremely valuable technique to avoid
> errors and pitfalls.  I think Guix could get a lot of mileage out of
> adopting something similar.
> 
> This causes a related problem of making it impossible to know what options
> are valid for what verbs.  Will `guix package --cores=8 -r emacs' remove the
> package while using eight cores of my system? Will `guix system -s i686
> switch-generation 5' switch me to a 32-bit version of generation 5?  If
> verbs are organized better, and have their own options, this ambiguity
> vanishes.
> 
> 
> More inconsistency
> ==================
> 
> Other parts of guix have the opposite problem: `guix system docker-image'
> probably ought to be an option to `guix system image' rather than a separate
> verb.
> 
> 
> Inconsistency between similar commands
> ======================================
> 
> There are generations of both the system (for GuixSD) and the user profile,
> however, they work differently.  For the system, there’s `guix system
> list-generations' and `guix system switch-generation', but for the user
> profile, you need `guix package --list-generations' and `guix package
> --switch-generation=PATTERN'.  Additionally, no help is available for either
> of the system commands: `guix system switch-generations --help' gives the
> same output as `guix system --help' -- no description of the supported ways
> of expressing a generation are available.
> 
> 
> Flattened verbs
> ===============
> 
> Related, the generation-related commands under `guix system' ought to be one
> level deeper: `guix system generation list', `guix system generation switch'
> etc.
> 
> 
> Repeated options
> ================
> 
> Many commands (`guix package', `guix system', `guix build', `guix shell')
> take -L options, to add Guile source to their load-path. This probably ought
> to be an option to guix itself, so you can do `guix -L~/src/my-channel build
> ...'.
> 
> 
> Suggestions
> ===========
> 
> All commands should be organized into a tree of verbs.
> 
> Verbs should have common aliases (`rm' for `remove', etc).
> 
> Verbs should be selected by specifying the minimum unambiguous substring.
> For example `guix sys gen sw' could refer to `guix system generation
> switch'.
> 
> Options should be applicable to each level of the tree, ex `guix
> -L~/src/my-channel' would add that load-path, which would be visible to any
> command.
> 
> Requesting help is a verb.  Appending "help" to any level of the verb tree
> should show both options applicable to that verb, and its child verbs.
> `guix help' would show global options and all top-level verbs (package,
> system, generation, etc); `guix package help' would show package-specific
> options and package-specific verbs; and so on.
> 
> 
> Conclusion
> ==========
> 
> I have no idea if anyone feels similarly about this, or whether there’s
> appetite to change the CLI, but I think it’d be time well-spent.  Having
> some kind of agreed-upon standard for how the CLI stuff is organized seems
> like a good thing to me, even if it just stops or slows the addition of more
> commands with unique expressions.
> 
> It seems like a lot of work to change, and backwards compatibility also is
> an issue.  One option I could see working is shoving the entire existing
> structure under a command in the new tool, so you could do `guix old package
> -I' or similar.  An alternate approach would be using an environment
> variable to change behaviors.
> 
> What do you all think?

This is probably the most well written critique I've seen on the layout
of the CLI for Guix.

I think it would be worthwhile to mock-up a 'guix profile' command to
see how it would look. I'm going to add it as a possible topic for Guix
Days just before FOSDEM and see if we can create something that makes
more sense.

-- 
Efraim Flashner   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]