apm export-patch
Synopsis
Section titled “Synopsis”apm export-patch [OPTIONS]Description
Section titled “Description”apm export-patch turns local edits to APM-managed files into unified diffs against the packages that deployed them, so the edits can be contributed back upstream.
It replays the locked install into a scratch tree (the same machinery as the apm audit drift check) and, for every managed file that was modified locally, maps the change back to the package source file that produced it. Each package with exportable edits gets one patch file, patches/<pkg>@<ref>.patch (the pnpm and Bun convention), ready for git apply in a clone of the package repository. <pkg> is the dependency key with / written as __; <ref> is the locked version for registry packages, otherwise the locked git ref (or the short commit when no ref was recorded). For example, microsoft/apm-sample-package locked at v1.2.0 becomes patches/microsoft__apm-sample-package@v1.2.0.patch. When two packages would sanitize to the same filename, each gets a short digest suffix so nothing is overwritten.
Every patch file records its base in a leading comment block: the package key, its source, and the exact snapshot the diff applies to (commit <sha> for git dependencies, version <x> for registry packages). Diff paths are relative to the package repository root (a subdirectory package’s paths include its subdirectory). Apply the patch from the package repository root, checked out at that base, then open your upstream pull request from the result:
git -C path/to/package-clone checkout <base-commit>git -C path/to/package-clone apply path/to/patches/<pkg>@<ref>.patchOnly verbatim-deployed files can be exported: a local edit maps cleanly back to its source only when the deployment copied that source byte-for-byte, ignoring the differences apm audit already tolerates (build-id headers, CRLF, a BOM) – those are normalized away on both sides, so they never reach the patch body. Everything else is listed as skipped with the reason instead of producing a patch that would not apply:
- Deployments that transform their content (frontmatter rewrites for rule directories, compiled
AGENTS.mdoutput, aggregatedcopilot-instructions.mdsections, files with resolved links). - Source files that are not normalization-clean (CRLF line endings, a UTF-8 BOM, or a build-id header): the deployed copy matches them only after normalization, so an exported diff could not be applied to the raw file.
- Ambiguous sources: when several package files hold the same bytes, the edit is skipped instead of guessing. A Claude plugin skill that install copied into
.apm/skills/maps back to its original plugin directory; an authored.apm/source never counts as such a copy. - Conflicting edits: when one source file is deployed to several targets and the copies were edited differently, the conflict is reported instead of exporting either version. Identical edits across copies export as a single diff.
- Local deletions of managed files are never exported, since deleting a deployed copy does not imply the file should be removed from the package.
Findings that belong to local path dependencies or to the project’s own .apm/ content are also skipped: their source already lives on disk, so the edit belongs there directly. A lockfile containing only local dependencies short-circuits before the replay.
The replay is cache-only and read-only: it needs a lockfile and a populated apm_modules/ (run apm install first) and never modifies the project tree, apm.lock.yaml, or apm.yml. Patch files are the only output, and --out may not point inside apm_modules/.
The next apm install overwrites local edits to managed files. apm audit drift output and apm install both point at this command when they find such edits, so export first if you want to keep them.
Options
Section titled “Options”| Flag | Default | Description |
|---|---|---|
--out, -o DIR |
patches |
Directory to write per-package <pkg>@<ref>.patch files into. Created if missing; only created when there is something to export. Must not point inside apm_modules/. |
--dry-run |
off | List what would be exported (and what gets skipped, with reasons) without writing patch files. |
--verbose, -v |
off | Show detailed replay progress. Skipped files and their reasons are always listed. |
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | Success, including “nothing to export” (skipped-only runs exit 0 with warnings). |
| 1 | Replay or export failed (missing apm.yml, missing or unparsable lockfile, cold cache, invalid --out). |
Examples
Section titled “Examples”# Export all local edits as per-package patches under ./patches/apm export-patch
# Preview what would be exported without writing anythingapm export-patch --dry-run
# Write patches somewhere elseapm export-patch -o /tmp/spec-patchesRelated
Section titled “Related”apm audit– detect the drift this command exports.- Drift and secure by default – why local edits to managed files are overwritten on the next install.
Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.