<a id="exp-projects"></a>

# Projects

<!-- @artefact project -->
<!-- @artefact project workshops -->
<!-- @artefact workshop definition -->
<!-- @artefact workshop .lock -->

Technically, a project is a directory
containing one workshop definition or more.

To initialize a directory as a project,
create a
[workshop definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition)
in it
and run **workshop launch**.
Launching a workshop from a project
establishes the relationship between the two
that’s required to actually start a workshop.
This is achieved with a hidden `.workshop.lock` file,
which must remain in the project directory
and must not be copied or stored externally, e.g., in a repository.

You can store workshop definitions in two ways:

<!-- @artefact workshop name -->
- If you use a single workshop in the project,
  store its definition in the project directory as `workshop.yaml`.
  This allows you to omit the workshop name in [the CLI](https://ubuntu.com/workshop/docs//explanation/workshops/workshop-cli.md#exp-workshop-cli).
- If your project involves multiple workshops,
  store their definitions in files with the same name as the workshops
  under the `.workshop/` subdirectory of the project directory:
  ```none
  .workshop/foo.yaml
  .workshop/bar.yaml
  ```

  When multiple workshop definitions are present,
  you can’t omit the workshop name in commands.

Projects can also store SDK definitions in subdirectories of `.workshop/`:

```none
.workshop/build-tools/sdk.yaml
.workshop/system-services/sdk.yaml
```

Such SDKs can be used by any workshop in the project.

When a workshop is then started with **workshop start**,
the project directory is mounted to it as `/project/`;
conversely, the **workshop stop** command unmounts it.

<!-- @artefact workshop --project -->

External changes to the project are tracked by the **Workshop** daemon.
Thus, if the project is moved or copied,
all workshops that reference it are updated,
so you can continue working without interruption.

If the project is deleted by external means
without first removing its workshops,
any workshops that reference it
enter the *Error* state;
the only command applicable to them is **workshop remove**.

#### NOTE
There are more workshop CLI commands;
some have a `--project` option
that accepts a pathname to use as the project directory.

## See also

Explanation:

- [Workshops and projects](https://ubuntu.com/workshop/docs//explanation/index.md#exp-workshop)
- [Workshop definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition)

How-to guides:

- [How to move projects around](https://ubuntu.com/workshop/docs//how-to/customize-workshops/move-projects.md#how-move-projects)

Reference:

- [workshop launch](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-launch)
- [workshop remove](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-remove)
- [workshop start](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-start)
- [workshop stop](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-stop)