Liking cljdoc? Tell your friends :D

Shell

Table of Contents

Launching
Quitting
Let’s Play
The Dash Item
Using Autocomplete to Explore
Switching Workspace
Autocomplete Examples
Limitations
- Browsing Directories
- Creating a Workspace

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.

Our examples assume you are exploring from our ongoing tutorial example workspace.

Launching

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.

Quitting

To quit the shell, type exit or quit or press either of:

Ctrl+C
Ctrl+D (if not on Windows)

Let’s Play

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 Dash Item

The brick argument shows you all available bricks. Selecting the - (the dash character) tells poly you want no bricks selected (e.g., for testing):

Using Autocomplete to Explore

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:

Switching Workspace

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.

The create and test commands don’t work on workspaces you have switched to.

If you want to play along, exit the shell, then clone clojure-polylith-realworld-example-app under the same parent directory as your example workspace:

cd ..
git clone https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app.git

And relaunch the poly shell:

cd example
poly

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.

Switching to an Exported Workspace

You can switch to an exported workspace.

You can export a workspace to a .edn file, e.g. via poly ws out:usermanager.edn.

If you want to play along, exit the shell, then clone the polylith branch of usermanager-example project under the same parent directory as your example workspace, and export its workspace:

cd ..
git clone --branch polylith https://github.com/seancorfield/usermanager-example.git
cd usermanager-example
poly ws out:usermanager.edn

And relaunch the poly shell:

cd ../example
poly

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

The poly tool supports reading old exported files, with older versions of the workspace structure, which are automatically migrated to the current version. This is also true when reading an older version of a workspace, e.g. if you go back in the git history with git checkout or switch.

Switching workspace by name

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.

Switch at Launch

You can launch a shell and immediately switch to a workspace:

…or load a workspace from an export file, e.g.:

Workspace Switch Mechanics

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 Examples

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

Limitations

Browsing Directories

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"/

Creating a Workspace

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.

❮Project Doc❯

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcuts Report a problem cljdoc on GitHub

× close