skip to content

How does `swift package edit` let you patch a remote SwiftPM dependency in place, and how does it compare with a root-level `.package(path:)` override?

level: middleimportance: nice to knowfreq 25%

answer

  1. a checkout under Packages/
  2. builds whatever is on disk
  3. one copy for the whole graph
  4. unedit refuses unpushed work
  5. --path attaches your own clone

basics

~20 s

swift package edit puts a dependency into an editable Git checkout under Packages/, built for every use of the package until swift package unedit. A root .package(path:) with the same identity does the same through the manifest.

solid answer

~50 s

`swift package edit <name>` takes a dependency out of SwiftPM's managed checkouts and puts a Git working copy under `Packages/`, at the currently resolved commit or on a new branch with `--branch`, or at a commit with `--revision`. From then on SwiftPM builds exactly those sources, whatever their tags or the version resolution wanted, and uses them for every instance of the package in the graph. `--path` attaches a clone you already have, or creates one there, and links it into `Packages/`. `swift package unedit <name>` restores the resolved version and refuses if the checkout has uncommitted or unpushed changes unless you pass `--force`. A `.package(path:)` dependency in the root manifest with the same identity overrides the remote package the same way, without version checks and without a pin, but it changes `Package.swift`, so it must never be committed.

code

bash · 9 lines
bash
# Put the dependency into edit mode on a new branch
swift package edit app-logging --branch fix-crash
# ...edit Packages/app-logging, build and test the app...

# Or attach a clone you already have
swift package edit app-logging --path ../app-logging

# Return to the resolved version (fails on unpushed work unless --force)
swift package unedit app-logging

go deeper

for a junior

Know that swift package edit gives you a local, editable copy of a dependency and that unedit returns to the resolved version.

for a middle

Explain where the checkout lives, the --branch, --revision and --path options, and why the edited copy satisfies every use of the package in the graph.

for a senior

Spot the team hazards: a dropped pin in Package.resolved during edit mode, a committed path override, and unedit --force discarding work.

for a principal

Set the route an unreleased fix takes, from local edit to a pinned fork branch to an upstream tag, with an owner for removing each workaround.

## Why you need a local override Sooner or later a dependency has a bug you need fixed before its maintainers tag a release, or you want to try an API change in a package and in the app that uses it at the same time. Swift Package Manager offers two ways to build against local sources of a remote dependency without forking the whole graph: **editable packages** via `swift package edit`, and a **local path dependency** in the root manifest. ## swift package edit The documentation describes it as temporarily switching a remote dependency to local. SwiftPM moves the dependency into a directory under `Packages/` (named after the package identity in SwiftPM 6.4) as a Git working copy: - `swift package edit <name> --branch bugFix` creates a branch called `bugFix` from the currently resolved version. - `swift package edit <name> --revision 969c6a9` leaves the checkout at a detached HEAD on that commit. - With neither option, the checkout is the currently resolved version on a detached HEAD. While a package is in the editable state, the documentation says SwiftPM builds "the exact sources in this directory ... regardless of their state, Git repository status, tags, or the tag desired by dependency resolution", and the edited package "is used to satisfy all instances of that package in the dependency graph". You can edit several packages at once. Two consequences matter in a team: - `swift package show-dependencies` lists the edited package's version as `unspecified`, because no version is being resolved for it. - In SwiftPM 6.4, putting a package into edit mode removes its pin from `Package.resolved`, and `unedit` restores it. Committing the file while a package is being edited would drop that pin for everyone. When you are done, `swift package unedit <name>` removes the checkout and restores the resolved version. It fails if the checkout has uncommitted changes or commits that were not pushed; `--force` discards them. ## Attaching your own checkout with --path The documentation calls this **top-of-tree development**: `swift package edit <name> --path <dir>` attaches an existing checkout, or creates one at that path if none exists, and adds a symlink in `Packages/` pointing to it. SwiftPM treats it as completely unmanaged and uses it as is; it only checks that the package name at that path has not changed. `unedit` removes the link, and the checkout at `<dir>` stays where it was, which suits a clone you also open on its own. ## A root-level path dependency Declaring `.package(path: "../app-logging")` in the root manifest, where the directory's identity matches the remote package's, also replaces every reference to that package in the graph. The SwiftPM documentation notes that local dependencies "do not enforce version constraints, and instead use the version that is available at the path". In a SwiftPM 6.4 check, such a dependency took over for two packages that required the remote one by version, and it got no pin in `Package.resolved`. The difference is that this lives in `Package.swift`, so it travels with any commit of the manifest, unlike edit mode, which lives in the local workspace. | Mechanism | Where the state lives | Version checks | Typical use | |---|---|---|---| | `swift package edit <name>` | local `Packages/` checkout | none while edited | a quick fix to send upstream | | `swift package edit <name> --path <dir>` | your own clone, linked | none | co-developing two packages | | root `.package(path:)` | the manifest | none | a short local experiment, never committed | | root `branch:` on a fork | the manifest and pins | none; unversioned | sharing an unreleased fix with the team | ## A routine for patching a dependency 1. Run `swift package edit <name> --branch fix-crash` and make the change in `Packages/`. 2. Build and test the app against it; the change applies wherever the package is used. 3. Push the branch to a fork and open a pull request upstream. 4. Run `swift package unedit <name>`; it succeeds once nothing is left uncommitted or unpushed. 5. When upstream tags the fix, run `swift package update <name>` and commit the new `Package.resolved`. ## Pitfalls - Expecting `unedit` to keep your work; with `--force` it discards uncommitted changes. - Committing `Package.resolved` while a package is in edit mode, losing its pin. - Leaving a root `.package(path:)` override in a pushed manifest, which breaks CI and teammates without that directory. - Changing the package's name in the attached checkout, which SwiftPM rejects.

  • Why can't you simply edit the sources in SwiftPM's own checkout directory instead?
    Those checkouts are managed by SwiftPM, which can check them out again at the pinned revision during resolution, so local changes there are not safe. `swift package edit` tells SwiftPM to stop managing that package and to build the sources as they are, which makes the change survive the next resolve and visible to every package that uses it.
  • How do you share an unreleased fix with the whole team once local editing works?
    Push the fix to a fork and point the app's manifest at it with a `branch:` or `revision:` requirement, which records the exact commit in `Package.resolved` for everyone. Because a root-level unversioned requirement takes precedence, it also covers dependencies that require the package by version. Switch back to a tagged release as soon as upstream ships one.

  • swift package edit makes SwiftPM re-check the edited package against version requirements.
  • An edited package is used only where my own manifest references it, not transitively.
  • swift package unedit keeps uncommitted changes in a safe place for later.
  • A root .package(path:) override is fine to commit because CI ignores local paths.
  • Editing files inside SwiftPM's managed checkout is the supported way to patch a dependency.