Single and multi layout

Where a project's code sits relative to its declaration. Two shapes, and the difference is only on your machine — inside the container the path is the same either way.

Single: the application repository is the project

my-app/                     ← the application's own repository
├── .dq/config.yml          ← committed, the source of truth
├── .dq/docker-compose.yml  ← generated, gitignored
├── app/  composer.json  artisan
└── INSTALL.md              ← generated, how to install this project

One repository, one clone, one thing to keep in step. This is the right shape for the common case: a project that is one application.

Multi: a wrapper holding several checkouts

my-project/                 ← a wrapper repository
├── .dq/config.yml
├── docker-compose.yml      ← generated
└── www/
    ├── api.example.test/   ← its own repository
    └── app.example.test/   ← its own repository

The wrapper exists to hold the declaration and the shared environment for several applications that are deployed separately. Each site has its own repository, and dqx clones them.

Which one you have, and changing it

dqx layout                  # what this project is, and whether it could be the other
dqx layout single --dry-run # what the conversion would do
dqx layout single           # do it

A conversion moves files, so it says exactly what it would move first — and it refuses rather than merging when both sides claim the same name.

Three names collide on almost every project and each has an answer rather than a refusal: the generated .dq/ stays as it is, .gitignore is merged with the application's lines first, and the application's README.md wins because the wrapper's was install instructions, which come back as INSTALL.md.

What changes, and what does not

Converting to single removes the wrapper repository, and only once every commit in it is somewhere else. The application's history becomes the project's history. Converting the other way creates a wrapper and moves the code under www/.

What does not change: the container paths, the domains, the database, and everything the declaration says. A conversion is about where files sit on your disk.

When single is not possible

A project serving several sites from several repositories stays multi — there is nowhere for a second repository to go. dqx layout says which projects could be single and why the rest cannot:

multi — 2 site(s), 2 checkout(s)
  stays multi: it has 2 sites