Keeping apps current#
A project that was fresh on the day it was generated is stale a month later, so this page is about keeping generated apps fed: what the manifest records, how sourdough feed merges template updates in without clobbering your changes, and how CI tells you when an app falls behind. Like any starter, it needs regular feeding, or it goes flat. Commit the manifest in your app, keep the sourdough-feed job every shape's pipeline ships with, then read on.
Record where the app came from#
Every app carries a .sourdough/manifest.json recording the Sourdough version, the template, the answers you chose, and a sha256 hash of every file, each marked managed or seeded (or yours, in an app Sourdough adopted). Other tools do the same: Copier writes .copier-answers.yml, and cruft writes .cruft.json. Without this record there is nothing to compare against, so no update is possible.
The manifest has the full key list and the managed, seeded and yours split.
Poke it: one check for the whole story#
Bakers poke the dough: if it springs back, it is ready. sourdough check is that poke for an app. In one read-only run it says whether the app is fed, which managed files you have changed, and whether its shape and the framework line it runs on are still supported:
sourdough check
Support: supported, owned by Sourdough maintainers; PHP 8.3 gets security fixes until 2027-12-31
Manifest: clean: every managed file matches the manifest
Feed: fresh: nothing to feed from Sourdough 0.5.0
OK: the raw app is fed and supported.
It writes nothing and needs no clean tree, so run it any time. Exit codes: 0 fed and supported, 1 needs attention (the app is behind its template, its shape is deprecated, or its Laravel major or PHP floor is past security support; each gets a line under Needs attention:), 2 tool error. Your own edits to managed files are listed and never fail it, for the reason under Check for drift. --json gives machines the same answer. The two commands it puts together are below; Commands has every line it prints.
Check for drift#
sourdough manifest --check lists the managed files that have drifted from the manifest, the ones you (or someone) edited since Sourdough wrote them:
sourdough manifest --check
Exit codes: 0 clean, 1 a managed file changed or is missing, 2 tool error (no manifest, or no --check). Seeded and yours files are never reported. They're yours. Line endings are forgiven, as feed forgives them: a checkout that turned a file to CRLF (the raw shapes' .gitattributes does it for *.ps1) has not drifted. Drift is not wrong: feed merges your edits with the template's. The check tells you which files a feed will have to merge rather than simply replace, which is why the CI job reports drift and never fails on it.
Feed the app: a merge, not an overwrite#
Upgrade the Sourdough CLI first (Upgrading), then, in the app, on a clean git tree, look before you leap:
sourdough feed --dry-run
The report opens with the same Support: line sourdough new prints (the shape's owner, its status and the framework's end-of-security date from CREED's policy; --json carries it as support), so every feed, and every sourdough-feed CI run, reminds the app when its framework stops getting security fixes. The plan then lists one line per file that would change, with the reason, and writes nothing:
Would feed the laravel-inertia app: Sourdough 0.1.5 to 0.1.6 (dry run: nothing written)
update config/helmet.php (you had not changed it)
merge routes/web.php (your edits kept, the template's merged in)
conflict vite.config.ts (1 conflicting hunk: you and the template changed the same lines; resolve the markers)
Would keep the template's version of 2 changed files in .sourdough/base/, so the next feed can merge from it.
Plan: 1 update, 1 merge, 1 conflict.
Then feed it for real, and review it like any other change:
sourdough feed
git status
git diff
What feed does#
Feed is the update model of Copier and cruft (ADR-0014), built on plain git instead of a Python runtime:
- It reads
.sourdough/manifest.json: the template, your answers, and a sha256 of every file Sourdough wrote last time (the base). - It bakes the same shape with the same answers, with the Sourdough you have installed, into a scratch folder: the loaf
sourdough newwould bake today.newandfeedbake through the same code, so the two cannot disagree. - It compares the three versions of each file (the base, your app's, the new loaf's) and acts:
| The template | Your app | Feed |
|---|---|---|
| did not change it | anything | leaves it alone (no line in the plan) |
| changed it | never touched it | update: takes the template's new version |
| changed it | changed it too | merge: git merge-file applies the template's change on top of yours |
| changed it | already has the new version | record: nothing written; the manifest records the new version |
| changed the same lines | changed them too | conflict: git's markers in the file, <<<<<<< app ... >>>>>>> sourdough <version> |
| added it | has no such file | add |
| added it | has the very same file | record: nothing written; the manifest takes the file in |
| added it | has its own file there | conflict: both versions marked |
| dropped it | never touched it | remove (and its emptied folder) |
| dropped it | changed it | keep: it is yours now, and leaves the manifest |
| changed it | deleted it | keep: it stays deleted |
A record line changes no file, only the manifest, so sourdough manifest --check stops calling the file changed. It is how an app baked by Sourdough 0.1.6 with --sail or --docker catches up: 0.1.6 wrote the manifest before the oven's scaffold ran, so feed reads the oven from the app's files (it says so in a note: line) and records them.
Seeded files (README.md, .env.example, package-lock.json) are never touched; a seeded file new to the template is written only where you have none. In an adopted app, yours files are never touched either, and get no line in the plan, until your copy equals the template's: then feed records it, and it is managed from then on. A feed that changes package.json leaves your lock file alone, so run npm install and commit both files, or the pipeline's npm ci stops on the mismatch. Line endings are forgiven: a Windows checkout with CRLF endings still matches what Sourdough wrote, and the files feed writes keep your checkout's endings. Binary files are never merged: the template's copy lands next to yours as <file>.sourdough-new.
- It moves the manifest to the new base (the new loaf's hashes and the new Sourdough version) and keeps the template's version of every managed file you have changed in
.sourdough/base/<file>.base. Commit both.
Where the base comes from#
A three-way merge needs the version Sourdough wrote last time. The manifest records only its hash, so feed finds the content by that hash: first in .sourdough/base/ (kept by the previous feed), then in any commit of your app's git history (the commit right after sourdough new holds every file as baked). A candidate is used only when its sha256 matches the manifest, so a wrong base can never sneak in.
When neither has it (you edited a file before your first commit), feed cannot tell your edits from the template's, so it does not guess: every place the two versions differ is marked as a conflict, and the lines they share stand once. Commit right after sourdough new and this never happens.
Conflicts#
A conflict is never a silent overwrite. Feed exits 1, and the file holds git's markers:
<<<<<<< app
your version
=======
the template's version
>>>>>>> sourdough 0.1.6
Edit the file to what it should be, delete the markers, and run your checks. git diff --check lists any markers left behind, so put it in a pre-commit hook or CI. Until the markers (and any .sourdough-new copies) are gone, the next feed refuses with exit 2 and lists them: finish one feeding before the next.
Rules feed keeps#
- A clean git tree first. Copier recommends a clean
git statusbut does not enforce it; feed enforces it (exit2), untracked files included, sogit statusandgit diffshow exactly what it did. To undo a whole feed:git restore . && git clean -fd. - Git, and only git. Feed needs git on PATH (or
SOURDOUGH_GITpointing at it), on Windows, macOS and Linux alike. The Laravel shapes also bake on a freshlaravel/laravelskeleton through Composer, the same assourdough new, so feeding one needs Composer and the network; Laravel's own skeleton updates arrive as template updates, merged the same way. - Forward only. A manifest written by a newer Sourdough than the one running is refused (exit
2). Update Sourdough first: a starter only rises forward. - The answers stay. Feed bakes with the answers in the manifest (the shape,
--sailor--docker, Playbook and ADVISOR). It does not change them. - The plan is yours.
.sourdough/plan.yaml, the plan the app was baked from, is not in the manifest: feed never reads, rewrites or removes it, and never lists it in its plan, so editing it is not drift. An app baked before Sourdough saved its plan gets none written by feed. See The saved plan.
Exit codes#
| Run | 0 |
1 |
2 |
|---|---|---|---|
sourdough feed |
fed cleanly, or nothing to feed | fed, with conflicts to resolve | tool error: no manifest, no git, a dirty tree, conflicts left from the last feed, a newer manifest, a failed bake |
sourdough feed --dry-run |
fresh: nothing to feed | feeding would change files | tool error |
Add --json to either for a machine-readable plan: the template, from and to versions, one entry per file (path, action, detail), a summary count per action, the base copies, any notes, and the exit code.
Feed in CI#
Every shape's .gitlab-ci.yml ships a sourdough-feed job, so an app that falls behind its template says so in its own pipeline instead of surfacing as drift months later; that is what makes a starter "fed". The job runs on the shape's composer image (multi-arch, through ${IMAGE_PREFIX}, on the .composer-cache), installs the newest Sourdough release with composer create-project, and asks it two questions:
sourdough-feed:
extends: .composer-cache
image: ${IMAGE_PREFIX}/composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0
variables:
SOURDOUGH_HOME: /tmp/sourdough
allow_failure:
exit_codes: [1]
script:
- composer create-project --no-dev --no-interaction --no-progress --prefer-dist waynestate/sourdough "$SOURDOUGH_HOME"
- mkdir -p .git/info && echo .cache/ >> .git/info/exclude
- drift=0; php "$SOURDOUGH_HOME/bin/sourdough" manifest --check || drift=$?
- fed=0; php "$SOURDOUGH_HOME/bin/sourdough" feed --dry-run || fed=$?
- if [ "$drift" -gt 1 ] || [ "$fed" -gt 1 ]; then exit 2; fi
- if [ "$fed" -eq 1 ]; then echo "This app has template changes to feed. Run sourdough feed, review and commit." >&2; exit 1; fi
What each answer does to the pipeline, read from the commands' own exit codes:
| The app | manifest --check |
feed --dry-run |
The job |
|---|---|---|---|
| fresh, as baked or fed | 0 clean |
0 fresh |
passes |
| a managed file edited by hand | 1, one changed line per file |
0 fresh |
passes, with the files listed: drift is normal, and feed merges it |
| a newer release has template changes it has not fed | 0 or 1 |
1, the plan |
warns: exit 1, which allow_failure shows as a warning, so a pending feed never blocks a deploy |
| a broken record: no manifest, one from a newer Sourdough, conflicts left over from the last feed, a failed bake | 2 |
2 |
fails |
To clear the warning, feed the app on your machine (upgrade the CLI, sourdough feed, review, commit); the next pipeline is green again. The .git/info/exclude line keeps the restored .cache/ download folder out of git's view, so the dry run sees the clean tree a real feed needs. tests/TemplateFeedJobTest.php holds every shape to the same job and runs its lines on a fresh bake of each shape: clean, edited, behind and broken.
Copier's copier check-update is the same idea: --quiet makes it exit 2 when an update exists, and --output-format json gives machines the answer.
Apps Sourdough did not make, and WELD#
Feed needs a manifest. An app without one gets exit 2, with the way in: sourdough adopt <dir> --shape <shape> (ADR-0014). Adopt bakes the shape fresh, compares the app with it file by file, and writes the manifest the app would have had: files that match become managed, files that differ stay yours and are never touched, and files the app lacks arrive with the first feed. Adopt an existing app walks through it, from picking the shape to the first feed.
sourdough adopt --shape raw --dry-run
sourdough adopt --shape raw
git add .sourdough && git commit -m "Adopt with Sourdough 0.4.2"
sourdough feed --dry-run
A yours file gets no step in any feed, so the sourdough-feed job stays green on every release; the day your copy equals the template's, feed records it (record) and manages it from then on.
WELD itself is not adopted yet: it was built by hand and checks its drift against a fresh Inertia bake with its own regen check.
Versioned template releases#
Tag template releases with semantic versions, and put a short "what changed, what to do" entry in the changelog for each. Copier picks the newest tag by default. An update tool is only as good as the history it can read.
Compatibility CI#
On every change to Sourdough, and on every release of WayneUI, SESAME, HELMET and PROCTOR, generate each permutation, install it and run its own tests and the PROCTOR check. Run it on a schedule (nightly), not only on changes, covering PHP 8.4 and 8.5 and the current and previous Laravel major. The starter is the place where all the stack libraries meet, so it is where a break shows first. A starter with no commits still rots, because the things it depends on keep moving.
Keep templates thin#
Put shared behavior in libraries, not in the template. Code that lives in SESAME, HELMET and PROCTOR updates with composer update, so only the glue lives in the template and the merge stays small. Other universities ship starters the same way: a Composer package plus an install command. A new site installs it with composer require and php artisan starterkit:install, and an existing site can require the library without publishing the project files. This is the core-plus-adapters rule applied to the starter itself.
Owners, windows and sunsets#
Starters die quietly. The React team deprecated Create React App on 2025-02-14, saying it had no active maintainers, and installing it now prints a warning that points at current frameworks. Laravel replaced Breeze and Jetstream with new kits when Laravel 12 shipped. Each permutation should name an owner, tie its support window to the framework and PHP end dates, run the scheduled build, and have the check print a deprecation notice with the migration note.
Refreshing the Squire templates#
The deploy files in your app (build.sh, scripts/release.sh, the .squire/ config, and their friends) come from Squire's exported copy, checked into the Sourdough repository at templates/squire/. Squire owns them; Sourdough installs them as-is and records them in the manifest, so you never edit them by hand. When Squire's templates change, regenerate the copy from a Squire checkout, then verify it:
php ../squire/bin/export-templates.php --to=../sourdough/templates/squire
php ../squire/bin/export-templates.php --to=../sourdough/templates/squire --check
Commit the refreshed copy with the Squire commit in the message, and add a CHANGELOG line. From the installed package the same refresh is composer squire-copy:sync, verified by composer squire-copy:check (part of composer ci). Apps generated earlier pick up the refreshed files with their next sourdough feed.