Adopt an existing app#
sourdough feed only reaches an app that carries .sourdough/manifest.json, and sourdough new writes one only into the apps it bakes. Most Wayne State apps were mixed somewhere else, years ago. sourdough adopt is the way in for them: it writes the manifest the app would have had if Sourdough had baked it, and from then on feed looks after it like any other loaf. Not every loaf came from our starter, but every loaf can be fed.
Adopt writes one file, .sourdough/manifest.json. It never changes your code, never writes .sourdough/base/, and never reads a file the template does not ship.
When to adopt#
- The app is close to one of the five shapes. Adopt compares the app with a fresh bake of the shape you name, file by file. The closer the app is to that shape, the more files Sourdough can keep current.
- Older Laravel apps: upgrade with Booster first. Adopt compares with today's
laravel/laravelskeleton, so an app on Laravel 8 is mostlyyours. That is correct, not a failure, but every hop Booster takes brings more files level with the template, and each one that matches gets updates from then on. - Older PHP is fine. The PHP floor comes from CREED's policy at bake time, never from an option, so an app on an older PHP gets
composer.jsonand.gitlab-ci.ymlmarkedyours. Upgrade and they can come back (see Take a yours file over).
WELD is not adopted yet: it was built by hand and checks its drift against a fresh Inertia bake with its own regen check. See Keeping apps current.
Before you start#
Adopt only runs inside a git repository, on a clean tree, so the adoption is one commit you can review and git revert can take back. An app that is not in git yet:
git init
git add -A
git commit -m "Before Sourdough"
Adopt needs git on PATH (or SOURDOUGH_GIT pointing at it), on Windows, macOS and Linux alike. The Laravel shapes bake a fresh laravel/laravel skeleton to compare with, so adopting one needs Composer and the network (or a warm Composer cache), the same as sourdough new.
Pick the shape and the name#
sourdough adopt [<dir>] --shape <shape> [--name <name>] [--sail | --docker] [--no-playbook] [--no-advisor] [--dry-run] [--json] [-v]
<dir> is the app's root folder; the default is the current directory. --shape is required, because you are naming what the app already is, not composing a new one:
--shape |
The app |
|---|---|
raw |
Raw PHP with WayneUI's standalone path |
raw-vue |
Raw PHP + Vue SPA over JSON |
laravel-blade |
Laravel + Blade |
laravel-blade-vue |
Laravel + Blade + Vue islands |
laravel-inertia |
Laravel + Inertia/Vue |
Leave it off and adopt refuses, with a guess from the app's files (artisan, inertiajs/inertia-laravel in composer.json, vue in package.json). Adopt never picks a shape itself:
$ sourdough adopt
--shape is required: raw, raw-vue, laravel-blade, laravel-blade-vue or laravel-inertia. This app looks like laravel-inertia (it has artisan and inertiajs/inertia-laravel).
The name. The template writes the app's name into some files (composer.json, public/index.php, the README). --name defaults to the basename of the folder. If the app goes by another name, every file that carries it differs and lands in yours. Adopt cannot know the right name, but it says when the name looks wrong: the file's line says so, and two or more such files add a note after the summary:
yours composer.json differs; the template writes the app name here as "ticketing", and your file does not have it: if the app goes by another name, delete .sourdough/ and adopt again with --name
yours public/index.php differs; the template writes the app name here as "ticketing", and your file does not have it: if the app goes by another name, delete .sourdough/ and adopt again with --name
...
note: 2 files differ where the template writes the app name; if the app goes by another name, delete .sourdough/ and adopt again with --name.
The oven. --sail and --docker are for the Laravel shapes, with the same meaning as for sourdough new. Pass one only when the app runs on Sourdough's own oven files. An app with its own Docker setup leaves both off, so its Dockerfile and compose.yaml stay outside the manifest and Sourdough never sees them.
Playbook and ADVISOR. --no-playbook and --no-advisor change what the template bakes (composer.json, .env.example, the README, .gitignore), and they are recorded in the manifest's answers, so every later feed bakes the same way. Leave them off unless the app should never have that wiring; WSU apps need Playbook.
Look first#
sourdough adopt --shape raw --dry-run
A dry run prints the same report and writes nothing. It opens with Would adopt and ends Run sourdough adopt without --dry-run to write the manifest. It still refuses a wrong command (a missing or unknown shape, a bad oven or name, a folder that is missing, already adopted, or left from an old manifest), but git and the folder only earn a note, so you can look at an app before it is in git:
Not inside a git repository: a real adopt would refuse.Uncommitted changes: a real adopt would refuse until the tree is clean.The folder is not writable: a real adopt would fail.git is not available: a real adopt would fail.
Read the report#
Here is a small, older raw PHP app, parking-permits, with a hand-built public/index.php, a composer.json that requires PHP 7.4, its own public/.htaccess and a README:
$ sourdough adopt --shape raw
Adopting "parking-permits" as a raw app (Raw PHP with WayneUI's standalone path) with Sourdough 0.4.2.
Compared your app with a fresh raw bake: 41 template files.
yours composer.json differs from the template: yours, never overwritten
yours public/.htaccess differs from the template: yours, never overwritten
yours public/index.php differs; the template writes the app name here as "parking-permits", and your file does not have it: if the app goes by another name, delete .sourdough/ and adopt again with --name
seeded README.md yours, as in every Sourdough app
missing .env.example the next sourdough feed adds it
missing .env.squire.example the next sourdough feed adds it
missing .gitattributes the next sourdough feed adds it
missing .gitignore the next sourdough feed adds it
missing .gitlab-ci.yml the next sourdough feed adds it
missing .squire/ (15 files) the next sourdough feed adds them
missing build.sh the next sourdough feed adds it
missing deployments/ (1 file) the next sourdough feed adds it
missing docker-compose.squire.yml the next sourdough feed adds it
missing health.php the next sourdough feed adds it
missing oracle-check.php the next sourdough feed adds it
missing phpstan.neon the next sourdough feed adds it
missing phpunit.xml.dist the next sourdough feed adds it
missing pint.json the next sourdough feed adds it
missing public/up.php the next sourdough feed adds it
missing scripts/ (3 files) the next sourdough feed adds them
missing src/ (2 files) the next sourdough feed adds them
missing stubs/ (1 file) the next sourdough feed adds it
missing tests/ (2 files) the next sourdough feed adds them
Adopted: 0 match, 3 yours, 1 seeded, 37 missing. Wrote .sourdough/manifest.json.
Files the template does not ship are not recorded: Sourdough never reads or touches them.
Next: git add .sourdough && git commit -m "Adopt with Sourdough 0.4.2"
then sourdough feed --dry-run lists the 37 files the first feed adds.
Only one file carries the name hint here, and it takes two for the note: a hand-built index.php simply never had the name in it. Every template path gets one status. The report lists yours first, then seeded, then missing; match lines show only with -v. A top-level folder whose every template file is missing folds into one line (.squire/ (15 files)); -v lists each file.
| Status | When | Recorded as | What feed does with it |
|---|---|---|---|
match |
the app's file is the template's, line endings aside | managed |
keeps it current, like any file Sourdough baked |
yours |
the file differs, is a symlink (or sits under one), or is named in another case (readme.md for README.md) |
yours |
never writes, merges, removes or reports it; takes it over the day it matches the template |
seeded |
a file the template seeds (.env.example, README.md, package-lock.json) that the app has |
seeded |
never touches it |
missing |
the app has no file at that path | not recorded | adds it, through its "new in the template" path |
Every recorded hash is the template's, never the app's. A Windows checkout with CRLF endings still matches. Files the template does not ship (your own code, vendor/, node_modules/, uploads) are never read and never recorded.
yours and missing are normal outcomes: adopt exits 0 with any mix of them. Adopt is not a CI gate; feed --dry-run is.
A vendored Squire kit gets a note too. When .squire.json says an older kit than the one this Sourdough bakes, the note says to run vendor/bin/squire update and commit; the next feed takes over each kit file that then matches.
Commit the adoption#
git add .sourdough
git commit -m "Adopt with Sourdough 0.4.2"
The adoption is its own commit, so git revert takes it back cleanly. Commit the manifest and do not hand-edit it: it is the starter's memory.
The first feed#
sourdough feed --dry-run
The first feed adds every missing file. A raw app that had lost its .gitlab-ci.yml and phpstan.neon, with its own composer.json and public/index.php:
$ sourdough feed --dry-run
Would feed the raw app: Sourdough 0.4.2 to 0.4.2 (dry run: nothing written)
add .gitlab-ci.yml (new in the template)
add phpstan.neon (new in the template)
Plan: 2 add.
Run sourdough feed without --dry-run to apply it.
Then feed for real, on the clean tree:
sourdough feed
git status
git diff
This is how the stack's wiring (Squire's kit, the pipeline with PROCTOR and the sourdough-feed job, PHPStan, Pint) reaches an older app. Review what arrived, run your checks, and commit. An app that had no .gitlab-ci.yml gets the shape's full pipeline, and some of its gates may fail on an older app until you fix them.
Delete what you do not want. Delete the file, commit, and feed remembers: it never adds the file again, and when the template changes it the plan only shows keep. sourdough manifest --check lists it as missing <file>, a report the CI job never fails on. To undo a whole feed instead: git restore . && git clean -fd.
Your own .gitlab-ci.yml#
When .gitlab-ci.yml is yours, the app's pipeline has no sourdough-feed job, so nothing warns when the app falls behind. Copy the job by hand from a fresh bake of the same shape:
sourdough new ../fresh-bake --raw
Copy the sourdough-feed: job from ../fresh-bake/.gitlab-ci.yml into yours, with what it leans on: the .composer-cache template it extends and the IMAGE_PREFIX variable its image uses. Then delete the fresh bake. Feed in CI explains what the job reports.
Take a yours file over#
A yours file is never written, merged or reported, until the day your copy equals the template's. To hand one to Sourdough, make it match the template (copy it from a fresh bake of the same shape and name, or bring your copy level), commit, and feed:
$ sourdough feed --dry-run
Would feed the raw app: Sourdough 0.4.2 to 0.4.2 (dry run: nothing written)
record composer.json (your file now matches the template's: Sourdough manages it from here)
Plan: 1 record.
Run sourdough feed without --dry-run to apply it.
A record line changes no file, only the manifest: the file is managed from then on and gets every template update. The sourdough-feed job warns until that feed is committed. Squire's kit files come back the same way after vendor/bin/squire update.
Start over#
Wrong shape, wrong name? Delete .sourdough/, commit, and adopt again. Adopt never writes over a manifest, because that would lose the record feed stands on:
$ sourdough adopt /srv/apps/parking-permits --shape raw
"/srv/apps/parking-permits" already has a Sourdough manifest: Sourdough made or adopted this app. Bring it up to date with sourdough feed. To adopt it again with another --shape or --name, delete .sourdough/, commit, and run adopt again.
A .sourdough/base/ folder with no manifest beside it is left from a record that is gone, and adopt refuses that too, until you delete .sourdough/ and commit.
Exit codes#
| Exit | Meaning | When |
|---|---|---|
0 |
adopted, or a dry run printed its plan | any mix of match, yours, seeded and missing |
1 |
refused: fix the command or the repo and run again | a missing or unknown shape, a bad oven, a folder that is missing or a file, a manifest already there, a leftover .sourdough/base/, a bad name, not a git repository, a dirty tree |
2 |
tool error | no git, a folder adopt cannot write, a failed bake, a failed write |
The whole command (options, refusals, JSON and environment) is in Commands. Failing lines and their fixes are in Troubleshooting.