April 24, 2019

Command line interface: redesign and upgrades

Command Line tools are always a challenge. We decided to simplify and make Plastic's CLI more intuitive and user-friendly and at the same time keep consistency of commands and functionality across the product's different GUIs. You shouldn't be scratching your head to a) know how a command expression is built or b) find specific help.

The main lines of action were the following:

  • Human readable command input and output
  • Enhanced discoverability and help
  • Command expression consistency

Following these principles, we decided to move on and continue upgrading our CLI like crazy lately.

HCI: Humans read, computers operate

Text is the key communication element between the user and the machine in CLIs. Machines can read fast and easy almost anything you throw at them, but we, humans, take way less time understanding text that is more similar to natural language representations. Following this train of thought commands like mkwk or lrep now are way more readable under commands like workspace create and repository list respectively.

In fact, for this matter, all workspace (wk in short form) commands have been revamped. Here are some usage examples:

cm wk
(Lists workspaces.)
cm wk MyNewWorkspace workspacePath
(Create a workspace.)
cm wk rename NewWorkspace
(Rename the current workspace.)
cm wk mv newWorkspacePath
(Move the current workspace.)
cm wk rm NewWorkspace
(Delete a workspace.)

When in doubt do not hesitate to promptly consult the workspace inline help with cm workspace --help. You know that form follows function, and meaning follows form. By providing more readable commands we are improving the semantics of the command line.

In this sense, push and pull are easier to grasp than the now deprecated cm replicate. These commands are now equivalent:

cm replicate br:/main@project@remote:8087 project@local:8087
cm pull br:/main@project@remote:8087 project@local:8087
cm replicate main@project project@remote:8087 --push
cm push main@project project@remote:8087
cm replicate main@project --package=project.package
cm push main@project --package=project.package
cm replicate project@localhost:8087 --import=project.package
cm pull project@localhost:8087 --package=project.package
cm replicate main@project@remote:8087 project --nodata
cm pull main@project@remote:8087 project --nodata
cm replicate hydrate project
cm pull hydrate project

There's new stuff too!

We have taken advantage of rethinking the CLI to introduce new commands like cm clone. Hopefully, cm clone is self-explanatory but here is a short description of what it does just in case:

clone command clones a source repository (all of its branches, changesets, labels, code reviews, and so on) into a destination repository. If the destination repository does not exist, it is created automatically. If it does, it must be empty, or the clone is cancelled.

These are a few examples of how to use the clone command:

cm clone codice@skull.home:9095
(Clones codice repository from skull.home:9095 into a repository also named codice in my default repository server.)

cm clone codice@skull.home:9095 codice-local (Clones codice repository into a repository called codice-local in my default repository server.)

You can also use the clone command to clone repositories from your Plastic Cloud organization:

cm clone myRepo@tardis@cloud
(Clones the myRepo repository from Plastic Cloud tardis organization into a repository with the same name in my default repository server.)

As before with workspace inline help, execute cm help clone to invoke the contextualized help you need.

Rinse and Repeat

CLI is great for repeatable actions. However, learning many commands can also be excruciating that's why contextual help and autocomplete have been enhanced plus all command expressions now follow the same logic: it's always the object followed by the verb. And it is always "create | delete | list | rename | edit".

To wrap up, what we are trying to achieve with these changes is to allow dev muscle memory to work its way easily through the mechanics of Plastic's CLI. The easier CLI gets, the more it's out of the way. This frees up your creativity and allows you to focus on your code and interaction with the machine.

Enjoy it!





I am sure you enjoyed this news on CLI updated. Plastic SCM is a cross-platform product so, in case you'd rather prefer GUI for your OS, don't hesitate and try them out!

No comments:

Post a Comment