shell.adoc

Shell

Table of Contents

• Launching
• Quitting
• Let’s Play
• The Dash Item
• Using Autocomplete to Explore
• Switching Workspace
  • Switching to an Exported Workspace
  • Switching workspace by name
  • Switch at Launch
  • Workspace Switch Mechanics
• 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.

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

• kbd:[Ctrl+C]

• kbd:[Ctrl+D] (if not on Windows)

Let’s Play

Launch a poly shell and play along.

Press kbd:[Tab] to see all available commands:

Type i to match all commands starting with the letter i:

Press kbd:[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 kbd:[Tab] to autocomplete :loc:

To distinguish :project from project, type the leading : (colon character):

Complete :project by pressing kbd:[Tab]. Type p then press kbd:[Tab] to autocomplete project:, and kbd:[Tab] again, to list all projects in the workspace:

When you have only one candidate, select it by pressing kbd:[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 kbd:[Space]; this removes the trailing colon:

An alternative way of selecting a listed candidate is to press kbd:[Tab] twice and use the arrow keys to move the selection cursor around (kbd:[Tab] and kbd:[Shift+Tab] also work):

Press kbd:[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.

Note	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 kbd:[Tab] to select .. and then type clo (or something long enough) followed by kbd:[Tab] to select the workspace directory:

Switch workspace by pressing kbd:[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.

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

Note	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 kbd:[Tab] followed by kbd:[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.