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.

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

or

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

Had also considered docs (.build) which is similar to @aaugustin's docs[.build]. Originally I rejected this style because it felt not obvious enough, but it is an elegant way of displaying the information.

EDIT: I'm not really a huge fan of @aaugustin's 1st example because it doesn't make it quite clear enough that docs by itself is a legal task identifier.

EDIT 2: Added his 2nd form / my earlier version of same, to the main gist.

I like 4 or 5 or @aaugustin's. 1-4 I don't really like.

I'm a fan of docs[.build]. Doesn't hide anything, makes the list compact, and it clearly says 'typing this is optional' in unix style.

Either #3 or #4. A normal person would have no idea what's going on. This thread has enough context that anyone can answer because they understand what it is from the beginning, but that's not how it would be in normal use.

Also dont listen to @dstufft he's drunk :)

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.