ref: consistent cmd alias strategy

Current CLI aliases

Bugs marked with check boxes 🐞

• version-> doctor: the former doesn’t mention the latter; The latter has it’s own short page linking to the former (not great).

  • There are no links to either one from any other refs or guides. There should be some at least.

• list -> ls: the former mentions the ls alias; The latter doesn’t exist.

  • Other docs link to list only ATM. Update?
  • ls not existing seems like a bug ATM (quite inconsisntent)

• experiments -> exp: The former doesn’t exist; Only the latter (the alias) is on the cmd ref nav.

  • experments not existing is a bug – as it used to be the path, it should be redirecting to exp.
  • Also, the now exp page says it’s “aliased to exp” which no longer makes sense.

Solution

Let’s pick which name is considered most important, whether original or alias (I vote for version, ls, exp) and only have that on the nav (and terminal block highlighter?). WDYT @dberenbaum ?

Questions:

• Do we even mention the alternative name in docs?
• We should also review what the -h help output is doing for these, probably (Core DVC question)

Also…

We sometimes call the special remote:// remote URL format a “remote alias”. Should probably use this term consistently or remove it altogether.

UPDATE: Some decisions in https://github.com/iterative/dvc.org/issues/2989#issuecomment-966546066 below

[efiop]

version-> doctor: the former doesn’t mention the latter; The latter has it’s own short page linking to the former (not great).

Can just introduce a redirect, that should be enough. doctor is a successor to version, because people were confusing it with --version. We use doctor when talking with users these days.

list -> ls: the former mentions the ls alias; The latter doesn’t exist.

Good catch, looks like we forgot to add a redirection for dvc.org. https://github.com/iterative/dvc/pull/6683

Do we even mention the alternative name in docs?

I would say that redirections are enough, no need to elaborate on aliases, main cmd name is enough.

Should we also review what the -h help output is doing for these? (Core DVC question)

-h just shows the main name (e.g. list for dvc ls -h)

We sometimes call the special remote:// remote URL format a “remote alias”. Should probably use this term consistently or remove it altogether.

This is an advanced feature that will likely change in the future. I would probably just ignore it for now, no reason to spend time on it. Btw, don’t really remember remote alias, i use remote notation usually.

[dberenbaum]

TBH I’m not sure what the motivation was for each of these aliases (except for exp which is obviously just shorter). @efiop any reason why we developed these aliases?

I would probably lea

Let’s pick which name is considered most important, whether original or alias (I vote for version, ls, exp) and only have that on the nav (and terminal block highlighter?). WDYT @dberenbaum ?

Sounds good.

* Do we even mention the alternative name in docs?

I don’t think we need to.

* Should we also review what the `-h` help output is doing for these? (Core DVC question)

Sure, we can do that as a follow-up.

Related product question @dberenbaum @efiop : should exp list and other listing commands have ls aliases too?

Hm, maybe that’s a reason to keep list instead of ls for more consistency. I don’t think ls makes as much sense for commands that don’t return filesystem-like output.