Basic usage¶
Start a new workspace¶
You can create a new workspace in the current working directory:
Info
You can also specify the path to the workspace using the --path option.
This creates a file called workspace.json, which contains metadata about the workspace. This file marks the root directory of the workspace.
When detecting the active workspace, the CLI looks for a workspace.json file in the current directory first, followed by its parents.
Info
To display the current workspace path, run workspace info.
Managing projects¶
Creating a project from scratch¶
A workspace contains one or more projects. You can create a new project with workspace new:
Info
This creates a Poetry project at the specified path. For other types of project, see Project types below.
We can check this project exists by listing all projects in the workspace:
Info
The name above was auto-generated from the directory name of the project. To specify a custom name, pass the --name flag to workspace new or workspace add.
Adding an existing project¶
If you already have an existing project, add it to be tracked by the workspace:
Info
We didn't specify --type here, because the CLI will attempt to automatically detect from the available types. If the wrong type is detected, you can specify this explicitly.
Removing a project¶
To stop tracking a workspace:
Warning
This will not delete anything by default. To delete the project directory, pass the --delete flag.
Listing projects¶
To show information about all projects, use workspace list:
Tip
This command (and others) support alternative output formats, including json. Run workspace list --help for more information.
Tip
You can pass or pipe project names (or globbed names) to list a subset of projects. This can be combined with other commands which only output project names, to show more information about them.
Project environments¶
Each project will have some environment, containing their dependencies. You can synchronise those environments for all projects at once, using:
In the case of Poetry projects, this runs poetry install to prepare each project's virtual environment. Other project types will perform other tasks.
Running commands¶
Arbitrary commands can be run in every tracked project in parallel, ensuring that each uses their respective environments:
Tip
The above command runs tests in parallel, which will only write command output if a command fails. To see the output of each command, omit the --parallel flag.
To run commands in specific projects, provide their names as positional arguments:
Example
workspace run supports piping a list of target project names, as well globbed names, for example:
echo "library-*" | workspace run -c 'pytest'
Dependency inference¶
Projects in a workspace will often depend on each other. This can be inspected with the appropriate commands:
Info
Both of the above commands will traverse all transitive dependencies. To show only direct dependencies or dependees, pass the --no-transitive flag.
Tip
Pass multiple inputs to output the union of results. As with run, piped and globbed arguments can be used.
To identify which project a particular file belongs to, use workspace reverse:
Tip
Combine run, dependees and reverse to run tests on only the affected projects of a git diff:
git --no-pager diff --name-only |\
workspace reverse |\
workspace dependees |\
workspace run -c 'pytest'
Project types¶
Every project in a workspace has a "type", which defines how the CLI interacts with that project and its environment. By default, two types are supported Poetry and Pipenv, both of which manage Python project environments.
Additional types can be added via plugins.