Improve `--list` output with modules

[casey]

Collecting feedback from #929.

To sum up:

1. --list output with modules is too verbose and nested
2. It should be possible to do --list SUBMODULE and only see --list output for that submodule, and iteratively descend into submodules with

For 1, I think I agree. The current output is very verbose and gets unwieldy quickly if there are a lot of submodules, and gets quite nested if the module hierarchy is deep. I think that, by default, --list should not print out the recipes in submodules, but only the submodules themselves.

So something like:

$ just --list
Available recipes:
  foo
  bar

Available submodules:
  baz
  bob

If there are no recipes at the top level, it would just be:

$ just --list
Available submodules:
  baz
  bob

I'm undecided about whether to completely remove the nested output, or require --verbose or --nested or whatever to get it.

For 2, I'm working on a patch that allows --list to take a module path, which are space- or ::- separated module names, and will descend into that module, and only print the --list output for that module.

@gl-yziquel and @valscion what do you think?

[casey]

I just merged #2108, which allows passing a submodule path to --list, so the second item should be good.

[gl-yziquel]

My use case would be commands and subcommands. So, ideally, I'd need the module to be on the same level as the recipes.

As to the nesting layout, I'd advise gating behind unstable some directive that controls what is being shown, and iteratively collect feedback as to the layout needs. I'd started with a [folded] directive on the mod declaration to keep the same behaviour as today but add that directive to get the submodule recipes folded. IMO, [folded] should be the default and [unfolded] the explicitly requested functionality, but, well...

Again, in the ideal world, the default command of the module should/could be listed as just a recipe in the toplevel, when [folded].

[casey]

Another alternative to this:

$ just --list
Available recipes:
  foo
  bar

Available submodules:
  baz
  bob

Would be listing submodules along with recipes:

$ just --list
Available recipes:
  foo
  bar
  baz
  bob

This could be done with some kind of visual indication:

$ just --list
Available recipes:
  foo
  bar
  baz…
  bob…

[gl-yziquel]

@casey The visual indication like that would be fine.

The only point I'd like, which is perhaps too far fetched, is the ability to do something like:

$ just --list --unsorted
Available recipes:
    foo
    bar…
    baz
    bob…

But I'd really advise for ASCII '...' instead of non-ASCII '…'.

I do work, more than occasionally, in a raw tty unix terminal provided by the ubuntu OS when no graphics are available. And I noticed that the fancy utf-8 characters do not pass well. In general terminal tools, so be it. But just should be able to run in such a context, with really low-level stuff. IMO.

[valscion]

I'm in favor of not displaying the submodules under their own heading as I do think for the one who calls just, the submodules should be an implementation detail. That is, submodules should be the way the Justfile is organized but should not force the caller of just to know where each recipe came from.

I also don't feel strongly about this as either way as long as the submodule recipes are not shown in the initial just --list output, I'm happy.

I do concur with @gl-yziquel that using plain ASCII would be better than the ellipsis character ….

So like this:

$ just --list
Available recipes:
  foo
  bar
  baz ...
  bob ...

The space between baz and ... is on purpose as it would signal one can call just baz something — that is, the space is meaningful in there.

[casey]

Done! I used ... instead of … because it stands out more. In the future, we can add a flag which displays recipes in submodules. If we do, I think I'll display them as foo::bar::baz::recipe, instead of using nesting, since even though it's a little more verbose, it's easier to read.

[psibi]

I'm undecided about whether to completely remove the nested output, or require --verbose or --nested or whatever to get it.

Sorry, I haven't been closely following this since I haven't yet started using modules yet. But if there is a way to extract all recipes - that would be very helpful for easily building tooling (eg: https://github.com/psibi/justl.el) around just. I currently use just --unstable --dump --dump-format=json to get all the recipes. I'm hoping that it will work for modules too.

[casey]

@psibi I believe JSON dumps include submodules, and just --summary prints all recipes, including those in submodules. Feel free to open an issue if those don't do what you want!

[psibi]

@casey Cool, thanks for the confirmation.

[crdx]

I had a message drafted yesterday which I forgot to send (re nested output):

I like it and it would remain my preferred output style even if the defaults change. I don't mind if it's not the default and I need to pass a flag, but please don't remove it completely.

Looks like I'm just too late... 😛

[casey]

@crdx It's easy enough to add back! I opened #2113 to add the nested view as an option with --list-submodules.