gistfile1.rst

The setup:

• Some top level tasks
• A 'docs' submodule
• docs.build is configured to be the default task for 'docs'
• So, 'invoke docs' == 'invoke docs.build'. Either is allowed.

The question is, how should this setup display in --list? Our options:

1. Fab 1.x style: display both, no indication of what maps to what:

   $ invoke --list
       top
       level
       docs
       docs.clean
       docs.build
       docs.browse

2. Super-compact style: display only the default/shorthand. Kind of meh, "hides" the "real" task name:

   $ invoke --list
       top
       level
       docs
       docs.clean
       docs.browse

3. Compact style: focus on the default/shorthand, but display the "real" name alongside:

   $ invoke --list
       top
       level
       docs (docs.build)
       docs.clean
       docs.browse

4. Doubled-up/highly explicit style: still show what the default maps to, but ALSO show the "real" name in-place:

   $ invoke --list
       top
       level
       docs (docs.build)
       docs.clean
       docs.build
       docs.browse

5. Variation on either of the above two, the "alongside" display could be compacted a bit, e.g.:

   $ invoke --list
       top
       level
       docs (.build)
       docs.clean
       docs.build
       docs.browse

   or:

   docs(.build)

   or:

   docs[.build]

   or so forth.

Drink Drank Drunk

I would vote for #4 all the valid commands are clear to the user, albiet the default in the brackets would be confusing without saying it actually defaults to that, like @aaugustin's first example but binding it to the command.

Maybe:

$ invoke --list
    top
    level
    docs [default: docs.build]
    docs.build
    docs.clean
    docs.browse

or

$ invoke --list
    top
    level
    docs (default: docs.build)
    docs.build
    docs.clean
    docs.browse

@myusuf3 My main issue with having the word 'default' here, is that the default-ness isn't really what's important, all that really matters to a user in this context is A) which identifiers are available/allowed, and B) the fact that 'docs' is the same as calling 'docs.build'.

---

It was late when I posted this, and I just remembered now that this needs to account for non-default aliasing as well. For example, let's pretend we have a top level task release which is an alias of deploy (i.e. deploy was decorated with @task(aliases=['release'])). We might want something like:

$ invoke --list
    deploy (release)
    level
    docs (docs.build)
    docs.build
    ...

Seems like this gets cluttered fast if we allow defaults/aliases' "real" targets to have their own lines, so I think from that angle, it's best to be compact and only show any given identifier once. (See e.g. svn help output for prior art here.)

That solves aliases. Given a default task is an "alias" of sorts to its collection/namespace, I think I'll go with consistency for now:

$ invoke --list
    deploy (release)
    docs (docs.build)
    docs.clean
    docs.browse

First release will be an 0.9 series so I reserve the right to backtrack on any of these opinions after folks actually start using it :D

Second thought, if we're focusing on the target of an alias w/ its aliases in parentheses, that actually implies it's more consistent to put default tasks' collection names in parens too. I.e. backwards from the above:

$ invoke --list
    deploy (release)
    docs.build (docs)
    docs.clean
    docs.browse

Will go with this for now. Again, subject to change & likely to have different list format options available either way (e.g. ye olde nested view).

👍 on the last one actually quite clear.