Applying updates locally
patchula apply looks up the working tree in the current directory and writes
the updates into its files, with no branches and no pull requests. It is for
scripts, Makefiles and pre-commit hooks: pin and update a checkout’s CI refs,
images and packages, then review and commit the change yourself.
patchula apply # write every updatepatchula apply --dry-run # print the diff insteadpatchula apply --check # exit 3 if anything is waiting, 4 if a lookup failedpatchula apply --manager github-actions --type pin --type digestIt reads the working tree the way lookup
does with no repository named: the patchula.pkl here, or --config,
uncommitted changes included. It takes the same cache, concurrency and HTTP
flags, and needs a token for the lookups like
every other command. It always runs on this machine. Repository arguments,
--all-repos and --remote are refused, and a checkout you chose to run
on a server is never offered to it.
In a checkout with no patchula.pkl it asks
first. Scripts and hooks pass
--default-config, or the command exits 2.
Nothing is written to the checkout except the updates. The cache lives in your
user cache directory, shared by every checkout; see
Installation for where, and --cache DIR to
move it.
What gets written
Section titled “What gets written”The Count reads each file again, finds the same declaration at the same place,
and rewrites only its version and digest; the terminal UI makes
the same edits. A digest pin, such as
actions/checkout@v5 becoming the commit it points to, is an update like any
other.
When the lookup proposes several updates for one declaration, such as a patch
on the current line and a new minor, the largest is written: major, then
minor, patch, pin and digest. Filter with --type to stay on a smaller step.
Some updates cannot be written in place. He leaves them alone, says why, and writes the rest:
- a package only a lockfile names, such as a vulnerable transitive crate in
Cargo.lock, which only its package manager can update; - an update the file already allows, such as a new release inside a range
like
~> 6.0, where only the lockfile would change; - a declaration that changed between the lookup and the write.
Every file is opened for writing before any is changed, so a file that is missing or read-only stops the write before anything changes. Files are written in place, keeping their owner, permissions and links. Only a failure while writing, such as a full disk, can leave some written, and the error names them.
Lockfiles are not regenerated. When an update’s current version came from a
lockfile, the summary reminds you to refresh it with your package manager
(aube install, cargo update -w, uv lock and so on).
Some managers only report a newer version and never edit it, such as a
template’s new tag. The summary lists those, and the JSON result carries them
as notices; see Managers.
Choosing updates
Section titled “Choosing updates”| Flag | Selects |
|---|---|
--manager MANAGER |
updates from this manager, such as github-actions or dockerfile |
--dependency PATTERN |
dependencies whose name as written, or registry package, matches; patterns take glob:, regex: and ! as in config selectors |
--type TYPE |
major, minor, patch, pin or digest updates |
Each flag can be repeated, and repeats widen it: --type pin --type digest
selects both. Different flags narrow each other. The update policy in
patchula.pkl still applies first, so an update a rule turns off, or a
release still in its release-age wait, is never
written.
Output and exit codes
Section titled “Output and exit codes”The summary goes to stderr. It opens with what was written, or would be, and
lists those updates; then what was left alone and why, template updates,
failed lookups and warnings; and last how many updates the filters left out. --dry-run prints a unified diff
of every file to stdout, so patchula apply --dry-run > pin.patch gives a
patch for git apply. With --json, stdout is one JSON object instead:
updates, skipped with each reason, files with each diff,
written, filtered, warnings, lookupFailures and exitCode.
lookupFailures lists each failed lookup as the
report does.
| Code | Meaning |
|---|---|
| 0 | nothing selected is left: everything was written, or there was nothing to write |
| 1 | runtime error, such as an unreadable working tree or an unwritable file |
| 2 | usage or configuration error |
| 3 | selected updates are still waiting: --check or --dry-run found some, or some could not be written in place |
| 4 | a dependency’s lookup failed, so its updates are unknown |
--check and --dry-run never write. A real run that leaves something alone
also exits 3, so a script can tell “done” from “done, but look at the
summary”.
Exit 4 wins over 3, since a failed lookup means the waiting list may be
incomplete; without --check or --dry-run, what could be looked up is still
written. Each failure is listed under “Lookup failures” with the dependency,
its file, its datasource, the kind of error and the registry’s message. The
CLI reference has the exit codes of the other commands.
Copier templates
Section titled “Copier templates”The Count runs copier only when you ask, on your own working tree: u on the
TUI’s Templates tab updates one template after a y, and
patchula apply --copier updates every template the filters select
(--manager and --dependency apply; any --type leaves templates out) before
writing the other updates, which are then planned against the tree copier
left. It is your own copier from PATH, run as you with
copier update --vcs-ref <new tag> --skip-answered, never --trust, and
nothing is committed. The template’s new, unreviewed code runs with your
permissions, so read the compare link first.
- The tree must be clean, untracked files included. With
applyand two templates, the second is refused: commit, then run again. - Copier asks the template’s new questions on the terminal. Without one,
applyrefuses the template unless you pass--copier-defaults. - A template that needs
--truststops copier; review it and runcopier update --trustyourself. - Conflicts stay as copier leaves them, and the Count lists the files it changed and the ones with conflicts.
- With
apply, a template copier did not update exits 3, and--copierdoes not combine with--dry-run,--checkor--json.
In hooks and scripts
Section titled “In hooks and scripts”A pre-commit hook that fails while the workflows have refs to pin or update:
repos: - repo: local hooks: - id: patchula name: Count Patchula entry: patchula apply --check --manager github-actions language: system pass_filenames: falseDrop --check to have the hook write the updates; pre-commit then fails
because files changed, and you stage them.
A Makefile target:
pin: patchula apply --type pin --type digestCommitting, branching and pushing are left to you. For pull requests, use
patchula run.
© 2026 Sweepy
