Add basic patching documentation

Author: spoorcc

doc/getting_started.rst

@@ -139,3 +139,64 @@ details on working with remotes see :ref:`Remotes`.
         repo-path: cpputest/cpputest
 
 .. scenario-include:: ../features/journey-basic-usage.feature
+
+My first patch
+-----------------
+Sometimes you need to patch a dependency to get it working with your project.
+*Dfetch* supports creating and applying patches after fetching the dependency.
+
+Given you have fetched ``dfetch-org/test-repo`` and you need to apply a patch.
+First commit the fetched version to your version control system. This provides
+*Dfetch* a reference point.
+
+.. code-block:: console
+
+  git add ext/test-repo-tag
+  git commit -m "Add test-repo-tag v2.0"
+
+Then you can work on the files inside ``ext/test-repo-tag``, once you are happy
+you can run ``dfetch diff`` to create a patch file with respect to the committed
+version.
+
+.. code-block:: console
+
+  dfetch diff
+
+This patch file can now be applied automatically by *Dfetch* in next updates.
+Add it to your manifest as shown below.
+
+.. code-block:: yaml
+
+  manifest:
+    version: '0.0'
+
+    remotes:
+      - name: github
+        url-base: https://github.com/
+
+    projects:
+      - name: ext/test-repo-tag
+        repo-path: dfetch-org/test-repo
+        patch: ext-test-repo-tag.patch
+
+      - name: cpputest
+        repo-path: cpputest/cpputest
+
+To test the patch, update the project again but with the ``-f`` option to force
+overwriting the local changes. The local changes will be lost but the patch will
+be applied.
+
+.. code-block:: console
+
+  dfetch update -f ext/test-repo-tag
+
+Now all changes can be amended to the last committed version including the patch.
+
+.. code-block:: console
+
+   git add ext/test-repo-tag ext-test-repo-tag.patch
+   git commit --amend -no-edit
+
+For more details on working with patches see :ref:`Diff` and :ref:`Patch`.
+
+.. scenario-include:: ../features/journey-basic-patching.feature

features/journey-basic-patching.feature

@@ -0,0 +1,61 @@
+Feature: Basic patch journey
+
+    The main user journey is for patching is:
+    - Adding a project to a manifest
+    - Fetching the new project and committing it.
+    - Changing files in the fetched project.
+    - Generating a patch file.
+    - Update the project again to verify the patch.
+    - Amending the changed project and the patch to version control.
+
+    Below scenario is described in the getting started and should at least work.
+
+    Scenario: Basic patch journey
+
+        Given a local git repo "MyPatchExample" with the manifest
+            """
+            manifest:
+              version: '0.0'
+
+              projects:
+                - name: test-repo
+                  dst: ext/test-repo
+                  tag: v1
+                  url: https://github.com/dfetch-org/test-repo
+            """
+        When I run "dfetch update test-repo" in MyPatchExample
+        Then the following projects are fetched
+            | path                           |
+            | MyPatchExample/ext/test-repo   |
+        When all files in MyPatchExample/ext/test-repo are committed
+        And "ext/test-repo/my-new-file.md" in MyPatchExample is created
+        When I run "dfetch diff test-repo" in MyPatchExample
+        Then the patch file 'MyPatchExample/test-repo.patch' is generated
+            """
+            diff --git a/my-new-file.md b/my-new-file.md
+            new file mode 100644
+            index 0000000..0ee3895
+            --- /dev/null
+            +++ my-new-file.md
+            @@ -0,0 +1 @@
+            +Some content
+            """
+        When the manifest 'dfetch.yaml' in MyPatchExample is changed to
+            """
+            manifest:
+              version: '0.0'
+
+              projects:
+                - name: test-repo
+                  dst: ext/test-repo
+                  tag: v1
+                  url: https://github.com/dfetch-org/test-repo
+                  patch: test-repo.patch
+            """
+        And I run "dfetch update -f test-repo"
+        Then the output shows
+            """
+            Dfetch (0.10.0)
+              test-repo           : Fetched v1
+              test-repo           : Applied patch "test-repo.patch"
+            """

features/steps/generic_steps.py

@@ -150,7 +150,8 @@ def step_impl(context, name):
 
 
 @given('"{path}" in {directory} is created')
-def step_impl(context, directory, path):
+@when('"{path}" in {directory} is created')
+def step_impl(context, path, directory="."):
     with in_directory(directory):
         generate_file(path, context.text or "Some content")
 

features/steps/git_steps.py

@@ -7,7 +7,7 @@
 import pathlib
 import subprocess
 
-from behave import given  # pylint: disable=no-name-in-module
+from behave import given, when  # pylint: disable=no-name-in-module
 
 from dfetch.util.util import in_directory
 from features.steps.generic_steps import call_command, extend_file, generate_file
@@ -138,6 +138,15 @@ def step_impl(context):
         commit_all("Initial commit")
 
 
+@given('a local git repo "{directory}" with the manifest')
+def step_impl(context, directory):
+    pathlib.Path(directory).mkdir(parents=True, exist_ok=True)
+    with in_directory(directory):
+        create_repo()
+        generate_manifest(context)
+        commit_all("Initial commit")
+
+
 @given("files as '{pattern}' are ignored in git in {directory}")
 def step_impl(_, pattern, directory):
     with in_directory(directory):
@@ -158,6 +167,12 @@ def step_impl(context, directory, path):
         commit_all("A change")
 
 
+@when("all files in {directory} are committed")
+def step_impl(_, directory):
+    with in_directory(directory):
+        commit_all("A change")
+
+
 @given('"{path}" in {directory} is created and committed with')
 def step_impl(context, directory, path):
     with in_directory(directory):