Skip to content

pymobiledevice3 patches

This directory holds our local modifications to doronz88/pymobiledevice3, pinned to the version in UPSTREAM_VERSION. We do not maintain a fork — upstream is cloned fresh at install time and our patches are applied on top.

This is a temporary arrangement. Python will be replaced with Go as soon as the architecture stabilizes; when that happens, this entire directory disappears along with scripts/iosmux-install-pymobiledevice3.sh. Until then, every patch must be self-documenting so the Go rewrite can pick up each change deliberately, not accidentally.

Layout

  • UPSTREAM_VERSION — single-line pin of the upstream tag we apply patches against. Bumping this file is the only way to change the pinned upstream version.
  • PATCHES.md — human-readable index of every patch in this directory. One row per .patch file with a one-line summary, the files it touches, the why, and — crucially — the Go-rewrite note that tells a future us what this change corresponds to in a Python-free world.
  • NNNN-<kebab-case-title>.patch — the patches themselves, in git format-patch format so each carries a commit message with Subject + full description + unified diff. Numeric prefixes define apply order.

Workflow

Adding a patch

  1. On the Linux host, clone upstream at the pinned version to a scratch location:
git clone --branch $(cat docs/patches/pymobiledevice3/UPSTREAM_VERSION) \
    https://github.com/doronz88/pymobiledevice3.git /tmp/pymob-scratch
cd /tmp/pymob-scratch
  1. Apply any existing patches first so you are starting from the state the new patch will stack on:
for p in /home/op/dev/myrepos/iosmux/docs/patches/pymobiledevice3/*.patch; do
    git am "$p"
done
  1. Make your edits. Commit them as one or more normal git commits. The commit message body is the patch's long-form documentation and should include a Go-Rewrite-Note: trailer:
Subject line describing the change

Longer explanation of what and why. This is what future readers
(and the Go rewriter) will see when they read the .patch file.

Go-Rewrite-Note: In the Go port, we must ... because ...
  1. Export the new commit(s) as git format-patch:
git format-patch -o /home/op/dev/myrepos/iosmux/docs/patches/pymobiledevice3/ \
    --start-number <next-number> origin/$(cat UPSTREAM_VERSION_FILE)

(Or simply -1 / -2 etc. to export the last N commits.)

  1. Update PATCHES.md with a new row.

  2. Run the install script to deploy to havoc and verify the patch loads cleanly:

./scripts/iosmux-install-pymobiledevice3.sh
  1. Commit the new .patch file and the updated PATCHES.md in the iosmux repo.

Dropping a patch

Delete the .patch file and its row in PATCHES.md, then rerun the install script. Removed patches simply don't exist any more — if we ever want them back, git history of the iosmux repo has them.

Bumping UPSTREAM_VERSION

  1. Change the version in UPSTREAM_VERSION.
  2. Run through the existing patches in order, re-applying each against the new upstream. If any fail, fix them by hand (this is the same workflow as maintaining a patch queue in quilt or stgit).
  3. Re-export the updated patches with git format-patch, replacing the old .patch files in place.
  4. Re-run the install script; commit everything.

Install workflow at a high level

Everything above is about maintaining the patches. To actually get a patched pymobiledevice3 running on havoc, run:

./scripts/iosmux-install-pymobiledevice3.sh

The script:

  1. Reads UPSTREAM_VERSION.
  2. Ships docs/patches/pymobiledevice3/*.patch to havoc under /tmp/iosmux-patches/.
  3. On havoc: clones upstream at the pinned tag into ~/pymobiledevice3-iosmux/, applies every patch via git am, and installs editable into the existing ~/pymobiledevice3-venv with pip install -e ..
  4. Verifies pymobiledevice3 version still reports the expected upstream version (patches do not change the version string).

The install script is idempotent: re-running it wipes the scratch checkout on havoc and rebuilds from scratch.

Reverting to stock

To remove all iosmux patches from havoc and restore the vanilla pymobiledevice3 release:

ssh havoc '~/pymobiledevice3-venv/bin/pip install --force-reinstall pymobiledevice3==9.8.1'

(Or whatever version matches UPSTREAM_VERSION at the time.)

Removing Python entirely

When the Go port covers everything pymobiledevice3 currently does for us, the removal is mechanical:

  1. Verify that PATCHES.md has a non-empty Go-Rewrite-Note for every patch in the directory and that each note has been addressed in the Go code.
  2. rm -rf docs/patches/pymobiledevice3/
  3. rm scripts/iosmux-install-pymobiledevice3.sh
  4. ssh havoc rm -rf ~/pymobiledevice3-iosmux ~/pymobiledevice3-venv
  5. Commit the deletion.

Step 1 is the one that matters — without it, we may silently lose a behavior that was previously patched into Python but never ported. That is precisely what this directory exists to prevent.