Explore the Workspace

Table of Contents

Exploring With ws
Referencing a Saved Workspace Structure
Referencing a Workspace in Another Dir

The poly tool stores the workspace structure internally in an in-memory map. It is used by poly internally to support all commands. All operations happen efficiently and directly on the map.

We expose the workspace structure via ws to allow our users to explore the complete state of any workspace.

The workspace structure represents internal state and can change with new releases of poly. See Versions for a changelog.

This document is a guide, see workspace structure for a complete reference.

All examples operate on our tutorial example workspace.

Exploring With `ws`

We recommend you always use the shell. Its command autocompletion really shines when exploring workspace structures with the ws command.

The Basics

To return the entire workspace structure:

poly ws

The workspace structure is large. You can limit what poly returns via the get argument. For example, to return settings:

poly ws get:settings

{:active-profiles #{"default"}
 :color-mode "dark"
 :compact-views #{}
 :default-profile-name "default"
 :empty-character "."
 :interface-ns "interface"
 :m2-dir "/Users/joakimtengstrand/.m2"
 :profile-to-settings {"default" {:base-names []
                                  :component-names ["user"]
                                  :lib-deps {}
                                  :paths ["components/user/resources"
                                          "components/user/src"
                                          "components/user/test"]
                                  :project-names []}
                       "remote" {:base-names []
                                 :component-names ["user-remote"]
                                 :lib-deps {"compojure/compojure" {:size 15172
                                                                   :type "maven"
                                                                   :version "1.6.2"}
                                            "http-kit/http-kit" {:size 191467
                                                                 :type "maven"
                                                                 :version "2.4.0"}
                                            "ring/ring" {:size 4621
                                                         :type "maven"
                                                         :version "1.8.1"}
                                            "slacker/slacker" {:size 28408
                                                               :type "maven"
                                                               :version "0.17.0"}}
                                 :paths ["components/user-remote/resources"
                                         "components/user-remote/src"
                                         "components/user-remote/test"]
                                 :project-names []}},
 :projects {"command-line" {:alias "cl",
                            :test {:create-test-runner [polylith.clj.core.clojure-test-test-runner.interface/create]}},
            "development" {:alias "dev",
                           :test {:create-test-runner [polylith.clj.core.clojure-test-test-runner.interface/create]}},
            "user-service" {:alias "user-s",
                            :test {:create-test-runner [polylith.clj.core.clojure-test-test-runner.interface/create]}}},
 :tag-patterns {:release "v[0-9]*", :stable "stable-*"},
 :thousand-separator ",",
 :top-namespace "se.example",
 :user-config-filename "/Users/joakimtengstrand/.config/polylith/config.edn",
 :user-home "/Users/joakimtengstrand",
 :vcs {:auto-add true,
       :branch "issue-205",
       :git-root "/Users/joakimtengstrand/source/polylith",
       :is-git-repo true,
       :name "git",
       :polylith {:branch "master",
                  :repo "https://github.com/polyfy/polylith.git"},
       :stable-since {:sha "b3b6e2ae3dfea55713312591313ef13c57858991",
                      :tag "stable-master"}}}

See the workspace structure reference for descriptions.

Digging Deeper

If you are only interested in a specific element in this structure, you can dig deeper, e.g.:

poly ws get:settings:profile-to-settings:default:paths

["components/user/src" "components/user/resources" "components/user/test"]

Learning What Data is Available

When exploring, it is nice to know what is available. To list top level keys:

poly ws get:keys

[:bases
 :changes
 :components
 :configs
 :interfaces
 :messages
 :name
 :paths
 :projects
 :settings
 :user-input
 :version
 :ws-dir
 :ws-local-dir
 :ws-reader
 :ws-type]

To list the components keys:

poly ws get:components:keys

["user" "user-remote"]

To show the user component:

poly ws get:components:user

{:interface {:definitions [{:name "hello"
                            :arglist [{:name "name"}]
                            :type "function"}]
             :name "user"}
 :interface-deps {:src [], :test []}
 :lib-deps {}
 :lib-imports {:test ["clojure.test"]}
 :lines-of-code {:src 9, :test 7}
 :name "user"
 :namespaces {:src [{:file-path "components/user/src/se/example/user/interface.clj"
                     :imports ["se.example.user.core"]
                     :name "interface"
                     :namespace "se.example.user.interface"}
                    {:file-path "components/user/src/se/example/user/core.clj"
                     :imports []
                     :name "core"
                     :namespace "se.example.user.core"}]
              :test [{:file-path "components/user/test/se/example/user/interface_test.clj"
                      :imports ["clojure.test" "se.example.user.interface"]
                      :name "interface-test"
                      :namespace "se.example.user.interface-test"}]}
 :paths {:src ["src" "resources"], :test ["test"]}
 :type "component"}

See the workspace structure reference for descriptions.

Fetching Library Usage

We’ve shown you how the libs command reports 3rd-party library usage. You can also retrieve library usage via ws, e.g.:

poly ws get:components:user-remote:lib-deps

{"compojure/compojure" {:size 15172, :type "maven", :version "1.6.2"},
 "http-kit/http-kit" {:size 191467, :type "maven", :version "2.4.0"},
 "ring/ring" {:size 4621, :type "maven", :version "1.8.1"},
 "slacker/slacker" {:size 28408, :type "maven", :version "0.17.0"}}

Saving the Workspace Structure

To save output to a file:

poly ws out:ws.edn

An alternative way to reach the same result from your OS shell (e.g. bash, redirection does not work from the poly shell) is to turn off the coloring and redirect to ws.edn:

poly ws color-mode:none > ws.edn

A saved workspace can be a convenient way to share the workspace structure with others without sharing the entire workspace codespace.

Referencing a Saved Workspace Structure

To load a workspace structure from a file, specify the ws-file argument, e.g.:

poly info ws-file:ws.edn

You’ll see the same output as if you executed poly info from the machine that created ws.edn.

You can run all commands with ws-file except create and test.

To inspect the arguments used to produce the file:

poly ws get:old:user-input:args ws-file:ws.edn

["ws" "out:ws.edn"]

Referencing a Workspace in Another Dir

Similar to ws-file is the ws-dir argument.

It allows you to explore workspaces in other directories. Like ws-file, you can run all commands with ws-dir except create and test.

Assuming you have a workspace in ../local-dep, you could check it from your current directory like so:

poly check ws-dir:../local-dep

A shorthand syntax for specifying the workspace dir is the :: argument, it sets the workspace dir to the first parent directory that contains a workspace.edn file, e.g.:

cd projects/command-line (1)

poly info :: (2)

1	Move to two directories down
2	Ask `poly` to find and use the workspace dir by looking upwards

Which is equivalent to the explicit:

poly info ws-dir:../..

❮Artifacts Polyx❯