doc: document git patch workflow

Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

1 files changed, 51 insertions, 4 deletions

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index a54888b43..5671e8dae 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -1223,7 +1223,6 @@ Creating Patches for a Package
 PTXdist uses the utilities *git*, *patch* or *quilt* to work with
 patches or patch series. We recommend *git*, as it can manage patch
 series in a very easy way.
-For this manual and the example we use *quilt* instead.
 
 Creating a Patch Series for a Package
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1231,6 +1230,9 @@ Creating a Patch Series for a Package
 To create a patch series for the first time, we can run the following
 steps. We are still using our *foo-1.1.0* example package here:
 
+Using quilt
+"""""""""""
+
 We create a special directory for the patch series in the local project
 directory:
 
@@ -1263,12 +1265,57 @@ present in ``patches/foo-1.1.0`` and can be used the next time we
 extract the package again.
 
 All we have to do now is to do the modification we need to make the
-package work. We change into the build directory and use *quilt* to
+package work. We change into the build directory and use quilt_ to
 create new patches, add files to respective patches, modify these files
 and refresh the patches to save our changes.
+See the *quilt* documentation (``man 1 quilt``) for more information.
+
+.. _quilt: http://savannah.nongnu.org/projects/quilt
+
+Using Git
+"""""""""
+
+Create the patch directory like above for *quilt*,
+but only add an empty series file::
+
+    $ mkdir -p patches/foo-1.1.0
+    $ touch patches/foo-1.1.0/series
+
+Then extract the package with an additional command line switch:
+
+::
+
+    $ ptxdist --git extract foo
+
+The empty series file makes PTXdist create a Git repository in the
+respective package build directory,
+and import the package source as the first commit.
+
+.. note:: Optionally, you can enable the setting *Developer Options →
+  use git to apply patches* in `ptxdist setup` to get this behaviour
+  as a default for every package.
+  However, note that this setting is still experimental and can lead to
+  failures for some packages.
+
+Then you can change into the package build directory
+(``platform-<name>/build-target/foo-1.1.0``),
+patch the required source files,
+and make Git commits on the way.
+The Git history should now look something like this:
+
+::
+
+    $ git log --oneline --decorate
+    * df343e821851 (HEAD -> master) Makefile: don't build the tests
+    * 65a360c2bd60 strfry.c: frobnicate the excusator
+    * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
+
+Finally, call ``git ptx-patches`` to regenerate the patch series in the
+``patches/foo-1.1.0`` folder.
+This way they don't get lost when cleaning the package.
 
-We recommend this way when modifying source files. But this way is
-improper when an autotools based buildsystem itself needs modifications.
+Both approaches (Git and quilt) are not suitable for modifying files
+that are autogenerated in autotools-based buildsystems.
 Refer to section :ref:`configure_rebuild` on how PTXdist can
 handle this special task.