Skip to content

apm export-patch

Terminal window
apm export-patch [OPTIONS]

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:

Terminal window
git -C path/to/package-clone checkout <base-commit>
git -C path/to/package-clone apply path/to/patches/<pkg>@<ref>.patch

Only 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.md output, aggregated copilot-instructions.md sections, 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.

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.
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).
Terminal window
# Export all local edits as per-package patches under ./patches/
apm export-patch
# Preview what would be exported without writing anything
apm export-patch --dry-run
# Write patches somewhere else
apm export-patch -o /tmp/spec-patches

Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.