Show available commands for a given query

[chbndrhnns]

I'd like to have a way to show available commands for a given query without looking through the yaml file. If there is one now, I am not aware.

[davvid]

garden ls <query>... will show you the commands, but it also shows a bunch of other stuff so I'm not sure if you've tried that. It only lists the command names, though. It doesn't list the command definitions.

Is that view good enough, or would having a specialized garden ls --cmds <query> mode that only shows the commands names be better for your usage? Is seeing the command definition useful as well?

This makes me wonder whether having a "dry run" mode when running commands would be useful or not, since having that mode would let you run commands speculatively to see what actually gets run.

e.g. we could add garden your-command -vv --dry-run <query> and that'd let you see all the places where your-command would get run without actually running anything. The -vv option would let you decide whether or not you want to see the definitions.

Let me know what you think. I kinda like the "dry run" idea on its own, and I'm curious to know whether a garden ls --cmds <query> mode would be useful or not as well, and what it should display.

[chbndrhnns]

garden ls seems to be what I was looking for. An argument to limit it to only commands seems nice. What would be even nicer is a consistent sorting of the output. Currently, it seems kind of random. I have not yet felt the need for a specific dry-run mode.

[davvid]

What would be even nicer is a consistent sorting of the output. Currently, it seems kind of random

I'll write this up soon if it's not already documented. Tree traversal order when resolving tree queries is defined by the order in which entries appear in your garden.yaml. That can definitely seem kinda random if you're not expecting it.

Groups, for example, are an ordered list of trees, and that order is defined by the order that the group lists those trees. Same for gardens when resolving tree queries, and for the tree entries themselves.

Slightly related ~ garden plant -s makes garden plant sort the trees block when planting a new tree in case you don't want to sort your files manually. Replant an existing tree using the the sort option and you'll have sorted traversals after it edits your garden.yaml.

If you don't specify a tree query then garden ls defaults to using @* as its query. This makes it match all trees and the order will match the trees block in your garden.yaml.

Adding a garden ls -s as a way to sort the trees by name before printing them sounds like a useful option. That way we can keep parity between what garden ls <query> displays by default and what someone will get when using the same tree query with other commands. I can also imagine things like garden ls -t to sort things by directory modification time and -r to reverse the results being useful, analogous to ls's behavior.

The rationale for using the user-defined order is that it gives users full control over tree traversal, which can be critical for certain workflows where you might want trees to be visited in a very specific order. The cost of this behavior is more documentation and a one-time learning cost for users to become aware of the behavior, so hopefully it's not too random now that you know about it.

Unrelated, but one inconsistency between garden ls and garden <custom-command> is that custom commands default to a tree query of . (the current tree) when no query is specified, and garden ls defaults to @* (all trees) when no query is specified.

I'm okay with this inconsistency since it's the unspecified scenario and these defaults better reflect how the commands should are used. ls is an interrogator and should therefore cast a wide net and let you see more, whereas custom commands perform operations and should therefore be more careful and stay limited in scope to your current tree/directory when nothing is specified.

I deeply rely on the . default for commands so that won't ever change, but I could probably be easily convinced that maybe garden ls should use the same . default as custom commands instead of its current @* default. I can see it being useful to have the output filtered to just the current tree when jumping around in a large collection of garden repos, but since it's so easy to type garden ls . it seemed like @* was a more convenient default. I'm all ears if you have opinions.

[chbndrhnns]

Tree traversal order when resolving tree queries is defined by the order in which entries appear in your garden.yaml. That can definitely seem kinda random if you're not expecting it.

This sounds like running the command twice will give me the same output. It does not which is why I said it seems random.

[davvid]

Oh dang, okay, thanks for the heads-up. I'll have to look into that for sure.

[davvid]

We now have garden ls -c for displaying just the commands and the commands are now displayed in a non-random order. I was only thinking about trees and related entities that I didn't realize that commands were not getting stored using an ordered container. It's all fixed now. Thanks for spotting that!