Re: Reorganizing guix package commands

[myglc2]

address@hidden (Ludovic Courtès) writes:

> Alex Kost <address@hidden> skribis:
>
>> Ludovic Courtès (2016-04-18 20:20 +0300) wrote:
>
> [...]
>
>>> I can see how adding “package” everywhere helps categorize things
>>> mentally, but as a user interface, I think it would be rather bad.
>>
>> As a user, I think it would be rather good.  (This is just my user opinion)
>
> To clarify, what I meant is that forcing users to type an additional
> word for common operations just for the beauty of categorization sounds
> unwise to me.
>
> For instance, I’m happy I can type ‘ls’ rather than ‘gnu core file list’.
> :-)
>
> Similarly, it’s not immediately obvious to me that something like “guix
> package edit” and “guix package install” would help newcomers.
>
> On the contrary, they would likely violate the rule of least surprise:
> most other tools provide sub-commands like “install”, some provide
> “edit” and “build” as well, without further categorization.

For the record, my original beef with guix edit, which seems to have
started all of this, is that, in a vanilla install, it opens an editor
on a file that the user cannot edit. So I suggested that we rename it
'guix view'.  Ironically, since then, I switched to guix git checkout,
so now I like "guix edit" just fine ;-)

>>> Also, it’s not that simple: “guix size” can take a store item instead of
>>> a package name, “guix graph” cannot do it yet but it would be useful if
>>> it could (“guix graph -t references $(readlink -f /run/current-system)”),
>>> etc.
>>
>> Hm, OK, I'm not sure, but let's leave "graph" and "size" alone for now.
>
> But there are many other similar cases.  For instance, ‘guix build’ can
> be passed a .drv; ‘guix archive’ can be passed a package name or a store
> file name, etc.
>
> Passing package names is a mere convenience for many of these commands;
> fundamentally, many operate on store items, derivations, etc.
>
> This requires careful consideration.
>
>>> I still think that having aliases like “guix install” as Andy proposed
>>> long ago would be useful, though I never started working on it.
>>
>> I agree!  Except I think they should be inside "guix package":
>>
>>   guix package install ...
>>   guix package remove ...
>
> As I view it, the sole purpose of “guix install” and similar is to make
> it easier for newcomers to get started (see <http://xkcd.com/1654/>),
> and to allow users in general to type less.
>
> Adding “package” in the middle would probably defeat that goal.
>
>> As for the transactional operations (I mean remove/install in one
>> command), I think we can do it in a separate "guix profile" command:
>>
>>   guix profile --install ... --remove ...
>
> This sounds good to me.
>
>>> There are probably other improvements to do around “guix package” (maybe
>>> turning some of its options into separate sub-commands as was suggested
>>> before.)  All we need is a clear view of where we’re going and patches.  :-)
>>
>> Here is the summary of the changes I think it would be good to have:
>>
>> | Replace this:                     | With this:                        |
>> |-----------------------------------+-----------------------------------|
>> | guix build                        | guix package build                |
>
> I don’t like this one, for the reasons given above.
>
>> | guix edit                         | guix package definition¹          |
>> | guix import                       | guix package import               |
>> | guix lint                         | guix package lint                 |
>> | guix refresh                      | guix package refresh              |
>
> I suppose the benefit would be that users can type ‘guix package help’
> and see all the sub-commands that relate to packages, right?

Also these  commands would no longer clutter up 'guix help'.

>> | guix package --show               | guix package show                 |
>> | guix package --search             | guix package search               |
>> | guix package --list-available     | guix package list                 |
>
> Or just ‘guix show’, ‘guix search’, etc.?

I also like these better, see analysis below.

>> |-----------------------------------+-----------------------------------|
>> | guix package --list-generations   | guix profile --list-generations   |
>> | guix package --list-installed     | guix profile --list-installed     |
>> | guix package --delete-generations | guix profile --delete-generations |
>> | guix package --switch-generations | guix profile --switch-generations |
>> | guix package --roll-back          | guix profile --roll-back          |
>> | guix package --manifest           | guix profile --manifest           |
>
>> ¹ "edit" name is confusing: <http://bugs.gnu.org/22587>
>>
>> Maybe instead of --list-generations and others, these options should
>> transform into subcommands (list-generations) of "guix profile".
>
> I agree.  But what should we do of transactions?
>
> Thoughts?
>
> Ludo’.

After seeing and contributing to the chaos this post generated I felt
guilty because my 'guix edit' complaint started it all.  So I made an
effort to step back and see the big picture. The table below summarizes
the Guix commands as I understand them. Columns 3 and 4 show which
commands modify user and system profiles, respectively. Columns 5, 6, 7
and 8 show commands used by different user types. Column 9 indicates
whether SUDO is required.

Table 1: command summary
========================
| column: 1        | 2                                      | 3   | 4   | 5   | 
6   | 7   | 8   | 9   |
|                  |                                        | +/- | +/- | new | 
typ | sys |     |     |
| command          | usage                                  | usr | sys | usr | 
usr | adm | dev | su? |
|                  |                                        | prf | prf |     | 
    |     |     |     |
|------------------+----------------------------------------+-----+-----+-----+-----+-----+-----+-----+
| guix archive     | [OPTION]... PACKAGE...                 |     |     |     | 
    |     | x   |     |
| guix build       | [OPTION]... PACKAGE-OR-DERIVATION...   |     |     |     | 
    |     | x   |     |
| guix challenge   | [PACKAGE...]                           |     |     |     | 
x   |     | x   |     |
| guix container   | exec ARGS...                           |     |     |     | 
    | x   | x   |     |
| guix download    | [OPTION] URL                           |     |     |     | 
x   |     | x   |     |
| guix edit        | PACKAGE...                             |     |     |     | 
x   |     | x   |     |
| guix environment | [OPTION]... PACKAGE... [-- COMMAND...] |     |     |     | 
x   |     | x   |     |
| guix gc          | [OPTION]... PATHS...                   |     |     |     | 
x   | x   | x   |     |
| guix graph       | PACKAGE...                             |     |     |     | 
    |     | x   |     |
| guix hash        | [OPTION] FILE                          |     |     |     | 
    |     | x   |     |
| guix import      | IMPORTER ARGS ...                      |     |     |     | 
    |     | x   |     |
| guix lint        | [OPTION]... [PACKAGE]...               |     |     |     | 
    |     | x   |     |
| guix package     | --list-available[=REGEXP]              |     |     | x   | 
x   | x   | x   |     |
| guix package     | --install PACKAGE                      | x   |     | x   | 
x   |     | x   |     |
| guix package     | --upgrade PACKAGE                      | x   |     |     | 
x   |     | x   |     |
| guix package     | --remove PACKAGE                       | x   |     | x   | 
x   |     | x   |     |
| guix package     | --manifest MANIFEST                    | x   |     |     | 
x   |     | x   |     |
| guix package     | --list-installed[=REGEXP]              |     |     | x   | 
x   |     | x   |     |
| guix package     | --list-generations[=PATTERN]           |     |     |     | 
x   |     | x   |     |
| guix package     | --roll-back                            | x   |     | x   | 
x   |     | x   |     |
| guix package     | --delete-generations                   | x   |     |     | 
x   |     | x   |     |
| guix package     | --switch-generations                   | x   |     |     | 
x   |     | x   |     |
| guix package     | --search=REGEXP                        | x   |     |     | 
x   |     | x   |     |
| guix package     | --list-available[=REGEXP]              |     |     |     | 
    |     | x   |     |
| guix package     | --show=PACKAGE                         |     |     |     | 
    |     | X   |     |
| guix package     | [OPTION]...                            |     |     |     | 
    |     | x   |     |
| guix publish     | [OPTION]...                            |     |     |     | 
    | x   | x   | Y   |
| guix pull        | [OPTION]...                            |     |     | x   | 
x   | x   | x   |     |
| guix refresh     | [OPTION]... PACKAGE...                 |     |     |     | 
    |     | x   |     |
| guix size        | [OPTION]... PACKAGE...                 |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] reconfigure [FILE]            |     | x   | x   | 
x   | x   | x   | Y   |
| guix system      | [OPTION] list-generations [FILE]       |     |     |     | 
x   | x   | x   |     |
| guix system      | [OPTION] build [FILE]                  |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] container [FILE]              |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] vm [FILE]                     |     |     |     | 
    | x   | x   |     |
| guix system      | [OPTION] vm-image [FILE]               |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] disk-image [FILE]             |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] init [FILE]                   |     |     |     | 
    | x   | x   | Y   |
| guix system      | [OPTION] extension-graph [FILE]        |     |     |     | 
    |     | x   |     |
| guix system      | [OPTION] shepherd-graph [FILE]         |     |     |     | 
    |     | x   |     |


Looking at the table, my major puzzles are:

- 'guix package' specifies actions with _OPTION_ but guix system uses
  _ACTION_.

- The small set of commands (column 3) that a new user needs are
  buried. That is, 'guix help' does not show them because they are
  implemented as OPTIONs and ACTIONs. Instead it shows mostly developer
  utilities.

- guix package modifies and reports on the per-user-profile but doesn't
  actually do anything "to" packages other than show what is available.

- Several other guix commands do things "to" packages.

We could debate how to resolve these puzzles, but as you know, what I
care most about is to make Guix easier for new users.  Here are the
minimum changes that I suggest for that:

Table 2: Novice-friendly Commands
=================================
| existing command                       | new command           |
|----------------------------------------+-----------------------|
| guix package --list-available[=REGEXP] | guix available REGEXP |
| guix package --search=REGEXP           | guix find REGEXP      |
| guix package --show=PACKAGE            | guix show PACKAGE     |
| guix package --install PACKAGE         | guix install PACKAGE  |
| guix package --remove PACKAGE          | guix remove PACKAGE   |
| guix package --list-installed[=REGEXP] | guix list             |
| guix package --roll-back               | guix roll-back        |

This makes the most important new user commands simpler and it makes
them appear in "guix help". IMO, this will go a long way to improving
the novice user's experience.

- George