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.:

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).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 thesince:X
parameter. - Remote git branches are suggested when using the
branch:X
parameter. - Relevant bricks and projects are suggested when using the
brick:X
andproject:X
parameters:- If a
project:X
parameter is selected from theinfo
ortest
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.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
:
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.
Last modified 10mo ago