move the rest of the docs over

book/src/usage.md

@@ -0,0 +1,230 @@
+# Usage
+
+## Quick examples
+
+- Start a Nextcloud instance with `postgresql`, and `s3` primary storage:
+
+  ```bash
+  haze start pgsql s3
+  ```
+
+- Start a Nextcloud instance with `sqlite`, `php 8.3` and an `smb` external
+  storage:
+
+  ```bash
+  haze start 8.3 smb
+  ```
+
+- Run specific units test against an `oracle` database
+  ```bash
+  haze test oracle apps/dav/tests/unit/Connector/Sabre
+  ```
+
+## Managing instances
+
+### Starting an instance
+
+```bash
+haze start [--name <name>] [--detach] [database] [php-version] [services] [vX.Y.Z]
+```
+
+Where `database` is one of `sqlite`, `mysql`, `mariadb`, `pgsql` or `oracle`
+with an optional version (e.g. `pgsql:12`), defaults to `sqlite`. And
+`php-version` is one of `8.0`, `8.1`, `8.2`, `8.3`, `8.4` or `8.5`, defaults to
+the maximum version support by the current Nextcloud version.
+
+You can specify a version number (e.g. `v32.0.2`) to use the sources from a
+release instead of using the local sources.
+
+Use `--name <name>` to give the instance a specific name instead of a randomly
+generated one. For example:
+
+Use `--detach` to give the instance
+[its own sources](#instances-with-their-own-sources) instead of sharing
+`sources_root` with all other instances.
+
+See the [services documentation](./services.html) for a list of available
+services.
+
+### List running instances
+
+```bash
+haze
+```
+
+or
+
+```bash
+haze list
+```
+
+### Stop an instance
+
+```bash
+haze [match] stop
+```
+
+### Remove all unpinned running instances
+
+```bash
+haze clean
+```
+
+### Pin an instance
+
+```bash
+haze [match] pin
+```
+
+Pinned instances will not be removed by `haze clean`.
+
+### Unpin an instance
+
+```bash
+haze [match] unpin
+```
+
+## Run commands in a temporary instance
+
+```bash
+haze shell [database] [php-version] [services] [cmd]
+```
+
+This will create an instance, run the provided command, and cleanup the
+instance.
+
+If no `cmd` is specified it will launch `bash`
+
+## Run tests in a new instance
+
+```bash
+haze test [database] [php-version] [services] [phpunit version] [path]
+```
+
+Where `path` is a file or folder to run PHPUnit in, relative to the sources
+root.
+
+This will create a fresh instance, run the PHPUnit tests, and clean up the
+created instance.
+
+## Interacting with running instances
+
+The following commands run against the most recently started instance by default
+and allow optionally providing a `match` to select a specific instance by its
+name.
+
+### Open an instance in the browser
+
+```bash
+haze [match] open
+```
+
+### Execute a command on an instance
+
+```bash
+haze [match] [service] [cmd]
+```
+
+If no `cmd` is specified it will launch `bash`
+
+If a service name or `db` is provided, the command will be in the container of
+the service or database.
+
+If no `cmd` is specified it will launch `bash`
+
+### Execute an occ command on an instance
+
+```bash
+haze [match] occ [cmd]
+```
+
+### Connect to the database on an instance
+
+```bash
+haze [match] db
+```
+
+### Show the logs of an instance
+
+```bash
+haze [match] logs
+```
+
+### Edit a file in an instance with the local $EDITOR
+
+```bash
+haze [match] edit <path>
+```
+
+Where `<path>` is the path of a file inside the container, for example
+`config/config.php`.
+
+### Reload the php config of an instance
+
+```bash
+haze [match] reload
+```
+
+The php configuration can edit changed with `haze edit  /config/php.ini`
+
+### Run a command with instance environment variables set
+
+```bash
+haze [match] env <cmd> [args]
+```
+
+Runs the provided command with `NEXTCLOUD_URL`, `DATABASE_URL` and `REDIS_URL`
+environment variables set for the matched instance.
+
+This is intended to run a local
+[push daemon](https://github.com/nextcloud/notify_push) against an instance.
+
+## Git tools
+
+Haze provides a couple of utilities to make working with many git repositories
+for apps easier.
+
+### Checkout a branch for all local apps
+
+```bash
+haze git checkout [branch]
+```
+
+Checks out the branch in all git repositories within the apps folder.
+
+Defaults to the branch matching the current checked out server versions (e.g.
+`master` or `stable33`).
+
+`master` and `main` can be used interchangeably.
+
+### Pull remote changes for all local apps
+
+```bash
+haze git pull
+```
+
+Performs a pull in all git repositories within the apps folder.
+
+## Update the container images
+
+```bash
+haze update
+```
+
+## Instances with their own sources
+
+By default every instance shares the sources configured as `sources_root`, so
+all instances always run the same code. An instance started with `--detach` gets
+its own `git worktree` of `sources_root` instead, created in `worktree_dir`,
+which lets you run several instances on different branches at the same time.
+
+```bash
+haze start --name my-fix --detach
+```
+
+The worktree is checked out with a detached head. Every app in one of the
+`app_directories` that gets enabled during setup receives its own worktree as
+well, other apps keep running from the shared app directory.
+
+The worktrees are removed together with the instance, by `haze stop` or
+`haze clean`.