doc: dev manual: how to recover from patch merge conflicts with git

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
Message-Id: <20210616155631.12180-2-rhi@pengutronix.de>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

1 files changed, 72 insertions, 0 deletions

diff --git a/doc/dev_patching.rst b/doc/dev_patching.rst
index e3690dfe1..a17983aa8 100644
--- a/doc/dev_patching.rst
+++ b/doc/dev_patching.rst
@@ -159,6 +159,78 @@ that are autogenerated in autotools-based buildsystems.
 Refer to the section :ref:`configure_rebuild` on how PTXdist can
 handle this special task.
 
+Recovering from merge conflicts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When updating packages, it can happen that older patches no longer apply.
+In this case, the *extract* stage will throw errors like this::
+
+   -----------------------------
+   target: ima-evm-utils.extract
+   -----------------------------
+
+   extract: pkg_src=/ptx/src/ima-evm-utils-1.3.2.tar.gz
+   extract: pkg_extract_dir=DistroKit/platform-v7a/build-target/ima-evm-utils-1.3.2
+   patchin: git: initializing repository
+   patchin: git: done
+
+   pkg_patch_dir:     'ptxdist/patches/ima-evm-utils-1.3.2'
+   pkg_patch_series:  'ptxdist/patches/ima-evm-utils-1.3.2/series'
+
+   patchin: git: apply 'ptxdist/patches/ima-evm-utils-1.3.2/series'
+   tagging -> base
+   0001-INSTALL-remove-file-at-it-s-autogenerated-by-autotoo.patch
+   0002-Makefile.am-rename-INCLUDES-AM_CPPFLAGS.patch
+   error: patch failed: src/Makefile.am:1
+   error: src/Makefile.am: patch does not apply
+   make: *** […/ptxdist/rules/post/ptxd_make_world_extract.make:41: …/DistroKit/platform-v7a/state/ima-evm-utils.extract] Error 4
+
+In the example above, the first patch was applied cleanly, but the second one
+was not because src/Makefile.am contained different lines than expected.
+If this happens, you have to clean up the merge conflict,
+and apply the remaining patches manually.
+
+First, change into the package's build directory, and abort the current patch::
+
+   …/distrokit/master (master) $  cd platform-v7a/build-target/ima-evm-utils-1.3.2/
+
+   …/build-target/ima-evm-utils-1.3.2 (master|AM/REBASE) $  git log --oneline --graph
+   * 6687ab46087c (HEAD -> master) INSTALL: remove file, as it's autogenerated by autotools
+   * 01a52624237f (tag: ima-evm-utils-1.3.2, tag: base) initial commit
+
+   …/build-target/ima-evm-utils-1.3.2 (master|AM/REBASE) $  git am --abort
+
+   …/build-target/ima-evm-utils-1.3.2 (master) $
+
+(Notice how the Git integration in the shell prompt still shows ``AM/REBASE``
+before the cleanup, signaling the ongoing conflict resolution.)
+
+The remaining patches are still available in the ``./patches`` directory
+relative to your current location.
+Try to apply each of them in turn using ``git am``.
+If a patch fails to apply, Git will not change any files, but will still
+remember the patch's author and commit message, and prompt you to resolve
+the conflicts::
+
+   …/build-target/ima-evm-utils-1.3.2 (master) $  git am patches/0005-evmctl-add-fallback-definitions-for-XATTR_NAME_IMA.patch
+
+   Applying: evmctl: add fallback definitions for XATTR_NAME_IMA
+   Patch failed at 0005 evmctl: add fallback definitions for XATTR_NAME_IMA
+   hint: Use 'git am --show-current-patch=diff' to see the failed patch
+   When you have resolved this problem, run "git am --continue".
+   If you prefer to skip this patch, run "git am --skip" instead.
+   To restore the original branch and stop patching, run "git am --abort".
+
+* If you find that the patch is no longer necessary (e.g. because it was
+  already merged upstream in the new package version), skip it with
+  ``git am --skip``.
+* Otherwise, apply the same patch again manually via ``patch --merge -p1 <
+  patches/filename.patch``, and resolve any resulting conflicts using your
+  favourite editor.
+* Finally, ``git am --continue`` commits your conflict resolution with the
+  patch's original author and log message.
+
+After porting all patches, update the package's patch queue with ``git ptx-patches``.
 
 Adding More Patches to a Package
 ================================