diff --git a/doc/howto/patching.rst b/doc/howto/patching.rst index 39d7355c..f2d484f6 100644 --- a/doc/howto/patching.rst +++ b/doc/howto/patching.rst @@ -11,6 +11,12 @@ patch file that is automatically re-applied on every :ref:`dfetch update into a contributor-ready unified diff that upstream maintainers can apply directly. +.. note:: + + New to patching with *Dfetch*? Start with :ref:`first-patch` in the + getting-started tutorial, which walks through creating and applying + your first patch step by step. + The full lifecycle looks like this: 1. :ref:`patching-create` — capture local edits as a ``.patch`` file with ``dfetch diff`` @@ -45,6 +51,8 @@ base. You can override this: - Single base revision: ``dfetch diff some-project --revs 23864ef2`` - Explicit range: ``dfetch diff some-project --revs 23864ef2:4a9cb18`` +See :ref:`diff` in the command reference for all options. + .. tabs:: .. tab:: Git @@ -74,8 +82,24 @@ Once you have a patch file, reference it from the project entry in patch: some-project.patch From this point on, every ``dfetch update`` will fetch the upstream source and -re-apply the patch on top. See :ref:`patch` in the manifest reference for the -full attribute syntax. +re-apply the patch on top. + +**Multiple patches** + +You can split your changes into separate, focused patch files and list them in +order: + +.. code-block:: yaml + + patch: + - 001-fix-null-dereference.patch + - 002-add-missing-header.patch + +Patches are applied in the order listed. A good convention is to prefix each +file name with a zero-padded number so they sort correctly and their purpose is +clear at a glance. + +See :ref:`patch` in the manifest reference for the full attribute syntax. .. _patching-update: @@ -94,8 +118,15 @@ This regenerates the last patch for ``some-project`` from the current working tree, keeping the upstream revision unchanged. It is safe to run repeatedly as you iterate on the fix. +When the upstream version changes, *Dfetch* applies patches with fuzzy +matching, so a patch can survive minor context changes without needing an +immediate refresh. If the patch no longer applies at all, ``dfetch update`` +will report the failure and you can refresh with ``dfetch update-patch``. + .. asciinema:: ../asciicasts/update-patch.cast +See :ref:`update-patch` in the command reference for all options. + .. tabs:: .. tab:: Git @@ -121,10 +152,10 @@ for a project: $ dfetch format-patch some-project This writes a ``formatted-some-project.patch`` file (or one file per patch if -there are several) that is ready to attach to a pull request or send by email. - +there are several) that is ready to share with the upstream project. -You can verify the formatted patch applies cleanly before submitting: +Before sending it, do a dry-run check to confirm it applies cleanly to a local +clone of the upstream repository: .. tabs:: @@ -136,6 +167,16 @@ You can verify the formatted patch applies cleanly before submitting: .. scenario-include:: ../features/format-patch-in-git.feature + Once confirmed, hand the file off to the upstream project. Upstream + maintainers can apply it with `git am + `_: + + .. code-block:: console + + $ git am formatted-some-project.patch + + Each patch file results in a separate commit. + .. tab:: SVN .. code-block:: console @@ -145,3 +186,5 @@ You can verify the formatted patch applies cleanly before submitting: .. scenario-include:: ../features/format-patch-in-svn.feature .. asciinema:: ../asciicasts/format-patch.cast + +See :ref:`format-patch` in the command reference for all options. diff --git a/doc/reference/commands.rst b/doc/reference/commands.rst index 116100ef..a9a17d12 100644 --- a/doc/reference/commands.rst +++ b/doc/reference/commands.rst @@ -96,6 +96,8 @@ Update .. seealso:: :ref:`Update projects ` — covers the update workflow, pinning versions, and force-fetching. +.. _diff: + Diff ---- .. argparse:: @@ -108,6 +110,8 @@ Diff .. seealso:: :ref:`Patch a project ` — creating, applying, and maintaining patches across upstream version bumps. +.. _update-patch: + Update patch ------------ .. argparse:: diff --git a/doc/tutorials/getting_started.rst b/doc/tutorials/getting_started.rst index 05aa5109..877da413 100644 --- a/doc/tutorials/getting_started.rst +++ b/doc/tutorials/getting_started.rst @@ -156,6 +156,8 @@ details on working with remotes see :ref:`Remotes`. .. scenario-include:: ../features/journey-basic-usage.feature +.. _first-patch: + My first patch ----------------- Sometimes you need to :term:`patch ` a dependency to get it working with your project.