poly
Search
⌃K

Shell

An interactive way of working with the poly tool.
The goal of the shell is to make us more productive and to have more fun!
The shell uses jline3 under the hood which supports the following operating systems: Mac OS X, Linux, FreeBSD, Solaris, and Windows.
Let's start a shell by typing poly from the workspace root:
The prompt is set to the workspace name. From here we can execute different commands and get instant feedback.
We can list all available commands by pressing the <tab> key:
If we type i and press <tab> it will show all commands starting with ‘i’:
If we press <tab> again, it will complete the info command and suggest available parameters:
Most parameters starting with a colon (:) can be selected by typing their name, e.g. l for :loc:
Press <tab> to select :loc:
We mentioned that parameters starting with a colon can be selected by their name. The exception is :project which has to start with :p to distinguish it from project:
Complete with <tab> and type p and press <tab> again to list all available projects in the workspace:
When we have only one candidate, then it can be selected by pressing <tab> :
The trailing colon indicates that this is a multi-select parameter (more than one project can be selected). We can leave the multi-select input mode by pressing <space> to remove the trailing colon:
An alternative way of selecting a candidate is by pressing <tab> twice, and using the arrow keys to move the "cursor" around, e.g:
Press <enter> to make a choice:
The brick parameter lists all bricks, including "no brick" represented by a dash (if brick:- is chosen, then no bricks will be selected for testing):
A command that really benefits from being executed from the shell is the ws command. Instead of trying to remember all the different attributes, we get them suggested for us:
From here we can dig deeper into the structure. Sometimes we encounter two words that start the same, where one of them is an exact match:
We can select user in this case, by typing ::
We can continue browsing the workspace structure and view the information we are interested in, e.g.:

Switching workspace

When starting a shell from a workspace directory (where the workspace.edn file lives) we can execute all available commands from that directory. It's also possible to switch workspace without leaving the shell, but then the create and test commands will not work (or show up in the autocomplete).
Let's say we have cloned the realworld-example-app. We can now switch to that workspace using the switch-ws command in combination with the dir parameter:
This will list all directories and files ending with .edn in the current directory.
We can select the clojure-polylith-realworld-example-app directory by typing . followed by <tab> to select .. and then typing clo (or something long enough) followed by <tab> to select the workspace:
Switch workspace by pressing <enter>:
The "dir:" prefix indicates that commands will be executed from the selected workspace, and not from the current directory. We can go back to the workspace directory by executing switch-ws:
If a workspace has been exported to a file using something like ws out:ws.edn then we can switch to that workspace. Here we use the usermanager project as an example:
The promt name is picked from the :name attribute in the file and is prefixed with 'file:' to indicate that it has been imported from a file.
The "trick" the shell does is to append ws-dir:DIR or ws-file:FILE to the command for us before the command is executed (if we have switched workspace using the dir:DIR or file:FILE parameters).

Autocomplete

The autocomplete helps us execute different commands with correct parameters:
  • Available commands can be suggested when we first select a command.
  • Available parameters are suggested for the current command.
  • The file system can be browsed when selecting files and directories.
  • The workspace structure can be browsed via the ws command.
  • Tag patterns defined in workspace.edn are suggested when using the since:X parameter.
  • Remote git branches are suggested when using the branch:X parameter.
  • Relevant bricks and projects are suggested when using the brick:X and project:X parameters:
    • If a project:X parameter is selected from the info or test command, only projects that are marked for testing will be suggested (we don't need to select already filtered out projects).
    • If a brick has been selected from the deps command, only projects that contain that brick will be suggested.
    • If a project has been selected from the deps command, only bricks from that project will be suggested.
When browsing the file system from a dir:PATH parameter, there are a couple of things worth mentioning:
  • If we want to go to the user home directory we have to type ~/ and not just ~ (this is a problem with the underlying jline3 integration).
  • When a file or directory contains spaces, it will be surrounded with quotes, e.g. "My path". To select such a path we need to include the first " in the path for the autocomplete to work.
Rarely used parameters are sometimes not suggested, e.g. color-mode. Another example is the create workspace command that we normally only execute outside of a repository and is therefore not suggested.
To quit the shell, type exit or quit or press <ctrl>+C or <ctrl>+D.

Tap

The tap command is mainly for poly tool development for now, but might be interesting for those who like to peek under the covers and understand how things work.
We can open a portal window by passing in :tap when starting a shell, e.g. poly shell :tap or by executing the tap command from a shell:
Let's produce some output by typing i:
The portal window outputs data from tap> statements produced by the poly tool itself.
It's possible to browse the internal workspace structure by clicking the {13} link to the right of :workspace:
Let's continue by looking at tools.deps.
Architecture - Previous
Project
Next - Workflow
Tools.deps
Last modified 10mo ago