Not only does the shell
make you more productive, but it’s also fun to use!
It takes full advantage of jline3 under the hood, which supports macOS, Linux, FreeBSD, Solaris, and Windows.
Let’s explore some shell features.
Start a shell by typing poly
from your workspace root directory (shell is the default command):
Notice that the example$
prompt includes your current workspace name.
From here, you can run commands and get instant feedback.
To quit the shell, type exit
or quit
or press either of:
Ctrl+C
Ctrl+D (if not on Windows)
Launch a poly shell and play along.
Press Tab to see all available commands:
Type i
to match all commands starting with the letter i
:
Press Tab to autocomplete the info command and list valid arguments:
You can usually skip the leading colon character; for example, type l
to match :loc
.
Press Tab to autocomplete :loc
:
To distinguish :project
from project
, type the leading :
(colon character):
Complete :project
by pressing Tab.
Type p
then press Tab to autocomplete project:
, and Tab again, to list all projects in the workspace:
When you have only one candidate, select it by pressing Tab:
The trailing :
(colon character) indicates a multi-select argument (you can select more than one project).
You can leave the multi-select input mode by pressing Space; this removes the trailing colon:
An alternative way of selecting a listed candidate is to press Tab twice and use the arrow keys to move the selection cursor around (Tab and Shift+Tab also work):
Press Enter to choose the item at the cursor:
The brick
argument shows you all available bricks.
Selecting the -
(the dash character) tells poly
you want no bricks selected (e.g., for testing):
Autocomplete really shines when there are many available suggestions.
The ws command offers a good example.
Instead of trying to remember all the different get:
arguments, the shell
lists them for you:
After you select components
, the shell
lists valid arguments.
Sometimes, you encounter multiple matching suggestions.
When one of them is an exact match for what you have typed:
You can select it by typing :
(the colon character):
You can continue navigating down into the workspace structure to find the information you are interested in:
When you start a shell from a workspace root directory (where the workspace.edn
file lives), the workspace is automatically loaded, and you can execute all available commands against it.
You can switch to a different workspace without leaving the poly shell.
You can switch to another workspace using the switch-ws command in combination with its dir
argument:
The shell
lists all directories and .edn
files under the current directory.
Select the clojure-polylith-realworld-example-app
directory by typing .
followed by Tab to select ..
and then type clo
(or something long enough) followed by Tab to select the workspace directory:
Switch workspace by pressing Enter:
Notice the prompt has changed to show the currently selected workspace (by dir). All commands will be run against this selected workspace.
You can go back to the example
workspace by invoking switch-ws
without arguments:
If you invoke switch-ws
again when you are already on the root, this will read the workspace from disk again, which can be useful in some situations.
You can switch to an exported workspace.
You can export a workspace to a .edn file, e.g. via poly ws out:usermanager.edn .
|
Switch to the exported workspace using the file
argument:
example$ switch-ws file:../usermanager-example/usermanager.edn
file:usermanager-example$
Notice that the prompt has changed to show the currently selected workspace (by export file).
If you have workspaces within your workspace, other cloned workspaces, or workspaces exported to file, there is a convenient way to access these from the shell.
First you need to configure these in the :ws-shortcuts key in your user config file (~/.config/polylith/config.edn
).
A workspace that lives in a directory is specified with :dir
, while exported workspaces are specified with :file
. They are accessed by the name of the directory/file, or :name
if given.
This example assumes that you have cloned the repos polylith and clojure-polylith-realworld-example-app, and that you have exported "another-ws" to a file, e.g.:
{...
:ws-shortcuts {:root-dir "/Users/joakimtengstrand/source/polylith"
:paths [{:dir "examples/doc-example"}
{:dir "../clojure-polylith-realworld-example-app" :name "realworld"}
{:file "../sandbox/another-ws.edn"}]}
}
The value of :root-dir
is added to each path to get a full path.
Now we can switch workspace from the shell with via:NAME
where NAME is the name of the directory/file:
polylith$ switch-ws via:
another-ws (../sandbox/another-ws.edn)
backend (examples/multiple-workspaces2/backend)
doc-example (examples/doc-example)
realworld (../clojure-polylith-realworld-example-app)
If we type d
and press Tab followed by Enter we switch to the examples/doc-example
workspace directory:
polylith$ switch-ws via:doc
dir:doc-example$
We can always switch back to the root workspace with:
dir:backend$ switch-ws
polylith$
A workspace that has been exported to a file, e.g. poly ws out:another-ws.edn
, can be selected with:
polylith$ switch-ws via:another-ws
file:another-ws
This is equivalent to switch-ws file:../sandbox/another-ws.edn
.
You can launch a shell and immediately switch to a workspace:
…or load a workspace from an export file, e.g.:
Knowing how the shell supports workspace switching can be helpful. It is pretty simple:
After switching to workspace dir D
, the shell silently appends ws-dir:D
to each command before it runs it.
After switching to workspace export file F
, the shell silently appends ws-file:F
to each command before it runs it.
Autocomplete helps you execute different commands with the correct arguments:
All valid sub-commands are suggested for a command:
example$ create
base component project
All valid arguments are suggested for a command:
example$ test
:all :all-bricks :dev :loc :project :verbose
brick project since
Browse your file system when selecting files and directories:
example$ switch-ws dir:
../ bases/ components/ deps.edn development/
projects/ workspace.edn ~/
Browse outdated libraries via the libs command:
example$ libs library:
org.clojure/clojure org.slf4j/slf4j-nop zprint/zprint
Browse your workspace structure via the ws command:
example$ ws get:interfaces:user:
definitions implementing-components name type
Browse documentation with the doc command:
example$ doc help:
check deps-brick doc tap
create-base deps-project-brick info test
create-component deps-project libs version
create-project deps-workspace overview ws
create-workspace deps shell
create diff switch-ws
Tag patterns defined in workspace.edn
are suggested for the since:
argument:
example$ info since:
previous-release previous-stable release stable
Remote git branches are suggested for some commands for the branch:
argument (for autocomplete to work here, you need to start your shell with :all e.g., poly :all
):
usermanager-example$ ws branch:
develop master polylith
Only relevant bricks and projects are suggested for the brick
and project
arguments:
The shell only suggests projects marked for testing for the info and test commands:
usermanager-example$ test project:
development usermanager
After you select a brick from the deps command, only projects that contain that brick will be suggested:
usermanager-example$ deps brick:database project:
development usermanager
After you select a project from the deps command, only bricks from that project will be suggested:
usermanager-example$ deps project:usermanager brick:
app-state department schema-fixture web
database schema user web-server
When browsing the file system from the dir:
argument, there are a couple of things worth mentioning:
To go to the user home directory, you must type the full ~/
and not just ~
(this reflects a limitation in the underlying jline3 integration):
example$ switch-ws dir:~/
Public/ Desktop/ Templates/
proj/ Documents/ Videos/
Downloads/ Dropbox/ bin/
Music/ Pictures/
To navigate to a directory containing spaces, you must type the leading "
.
Notice directory "foo bar baz"
:
example$ switch-ws dir:
"foo bar baz"/ bases/ deps.edn projects/ ~/
../ components/ development/ workspace.edn
To match it type the leading "
:
example$ switch-ws dir:"
"foo bar baz"/
The poly shell will not suggest workspace
for the create command when already associated with a workspace:
example$ create
base component project
You’ll typically run create workspace from your terminal shell (bash, PowerShell, zsh, etc) and then use the poly shell on that workspace:
$ poly create workspace name:myws top-ns:com.example
$ cd myws
$ poly
If you prefer to use the shell to create a workspace, run the poly shell outside of any workspace directory:
Notice the lack of a workspace name in the prompt. After you create your workspace, exit the shell and relaunch it from the new workspace directory.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close