Add format-patch command to dfetch.

Fixes #943

Author: spoorcc

CHANGELOG.rst

@@ -15,6 +15,7 @@ Release 0.12.0 (unreleased)
 * Respect `NO_COLOR <https://no-color.org/>`_ (#960)
 * Group logging under a project name header (#953)
 * Introduce new ``update-patch`` command (#614)
+* Introduce new ``format-patch`` command (#943)
 
 Release 0.11.0 (released 2026-01-03)
 ====================================

dfetch/__main__.py

@@ -13,6 +13,7 @@
 import dfetch.commands.check
 import dfetch.commands.diff
 import dfetch.commands.environment
+import dfetch.commands.format_patch
 import dfetch.commands.freeze
 import dfetch.commands.import_
 import dfetch.commands.init
@@ -46,6 +47,7 @@ def create_parser() -> argparse.ArgumentParser:
     dfetch.commands.check.Check.create_menu(subparsers)
     dfetch.commands.diff.Diff.create_menu(subparsers)
     dfetch.commands.environment.Environment.create_menu(subparsers)
+    dfetch.commands.format_patch.FormatPatch.create_menu(subparsers)
     dfetch.commands.freeze.Freeze.create_menu(subparsers)
     dfetch.commands.import_.Import.create_menu(subparsers)
     dfetch.commands.init.Init.create_menu(subparsers)

dfetch/commands/diff.py

@@ -32,35 +32,9 @@
 Using the generated patch
 =========================
 The patch can be used in the manifest; see the :ref:`patch` attribute for more information.
-It can also be sent to the upstream maintainer in case of bug fixes.
 
-The generated patch is a relative patch and should be by applied specifying the base directory of the *git repo*.
-See below for the version control specifics. The patch will also contain the content of binary files.
-
-.. tabs::
-
-    .. tab:: Git
-
-        .. code-block:: sh
-
-            git apply --verbose --directory='some-project' some-project.patch
-
-    .. tab:: SVN
-
-        .. code-block:: sh
-
-            svn patch some-project.patch
-
-.. warning::
-
-   The path given to ``--directory`` when applying the patch in a git repo, *must* be relative to the base
-   directory of the repo, i.e. the folder where the ``.git`` folder is located.
-
-   For example if you have the patch ``Core/MyModule/MySubmodule.patch``
-   for files in the directory ``Core/MyModule/MySubmodule/`` and your current working directory is ``Core/MyModule/``.
-   The correct command would be:
-
-   ``git apply --verbose --directory='Core/MyModule/MySubmodule' MySubmodule.patch``
+Because the patch is generated relative to the project's directory, you should use the :ref:`format-patch`
+command to reformat the patch for upstream use.
 
 """
 

dfetch/commands/format_patch.py

@@ -0,0 +1,124 @@
+"""Formatting patches.
+
+*Dfetch* allows you to keep local changes to external projects in the form of
+patch files. When those local changes evolve over time, an existing patch can
+be updated to reflect the new state of the project.
+
+.. code-block:: sh
+
+   dfetch update-patch some-project
+
+.. tabs::
+
+   .. tab:: Git
+
+      .. scenario-include:: ../features/update-patch-in-git.feature
+
+   .. tab:: SVN
+
+      .. scenario-include:: ../features/update-patch-in-svn.feature
+"""
+
+import argparse
+import pathlib
+import re
+
+import dfetch.commands.command
+import dfetch.manifest.project
+import dfetch.project
+from dfetch.log import get_logger
+from dfetch.project.superproject import SuperProject
+from dfetch.util.util import catch_runtime_exceptions, in_directory
+from dfetch.vcs.patch import PatchAuthor, PatchInfo, format_patch_with_prefix
+
+logger = get_logger(__name__)
+
+
+class FormatPatch(dfetch.commands.command.Command):
+    """Format a patch to reflect the last changes.
+
+    The ``format-patch`` reformats all patches of a project to make
+    them usable for the upstream project.
+    """
+
+    @staticmethod
+    def create_menu(subparsers: dfetch.commands.command.SubparserActionType) -> None:
+        """Add the menu for the format-patch action."""
+        parser = dfetch.commands.command.Command.parser(subparsers, FormatPatch)
+        parser.add_argument(
+            "projects",
+            metavar="<project>",
+            type=str,
+            nargs="*",
+            help="Specific project(s) to format patches of",
+        )
+        parser.add_argument(
+            "-o",
+            "--output-dir",
+            metavar="<output_dir>",
+            type=str,
+            default=".",
+            help="Output directory for formatted patches",
+        )
+
+    def __call__(self, args: argparse.Namespace) -> None:
+        """Perform the format patch."""
+        superproject = SuperProject()
+
+        exceptions: list[str] = []
+
+        output_dir_path = pathlib.Path(args.output_dir).resolve()
+
+        if not output_dir_path.relative_to(superproject.root_directory):
+            raise RuntimeError(
+                f"Output directory '{output_dir_path}' must be inside"
+                f" the superproject root '{superproject.root_directory}'"
+            )
+
+        output_dir_path.mkdir(parents=True, exist_ok=True)
+
+        with in_directory(superproject.root_directory):
+            for project in superproject.manifest.selected_projects(args.projects):
+                with catch_runtime_exceptions(exceptions) as exceptions:
+                    subproject = dfetch.project.make(project)
+
+                    # Check if the project has a patch, maybe suggest creating one?
+                    if not subproject.patch:
+                        logger.print_warning_line(
+                            project.name,
+                            f'skipped - there is no patch file, use "dfetch diff {project.name}"'
+                            " to generate one instead",
+                        )
+                        continue
+
+                    for idx, patch in enumerate(subproject.patch):
+
+                        version = subproject.on_disk_version()
+
+                        patch_text = format_patch_with_prefix(
+                            patch_text=pathlib.Path(patch).read_bytes(),
+                            patch_info=PatchInfo(
+                                author=PatchAuthor(
+                                    name=superproject.get_username(),
+                                    email=superproject.get_useremail(),
+                                ),
+                                subject="Fixes made",
+                                total_files=len(subproject.patch),
+                                current_idx=idx + 1,
+                                revision="" if not version else version.revision,
+                            ),
+                            path_prefix=re.split(r"\*", subproject.source, 1)[0].rstrip(
+                                "/"
+                            ),
+                        )
+
+                        output_patch_file = output_dir_path / pathlib.Path(patch).name
+                        output_patch_file.write_text(patch_text)
+
+                        logger.print_info_line(
+                            project.name,
+                            f"formatted patch written to {output_patch_file}",
+                        )
+
+        if exceptions:
+            raise RuntimeError("\n".join(exceptions))

dfetch/project/superproject.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import getpass
 import os
 import pathlib
 from collections.abc import Sequence
@@ -110,3 +111,25 @@ def current_revision(self) -> str:
             return SvnRepo.get_last_changed_revision(self.root_directory)
 
         return ""
+
+    def get_username(self) -> str:
+        """Get the username of the superproject VCS."""
+        username = ""
+        if GitLocalRepo(self.root_directory).is_git():
+            username = GitLocalRepo(self.root_directory).get_username()
+
+        elif SvnRepo(self.root_directory).is_svn():
+            username = SvnRepo(self.root_directory).get_username()
+
+        return username or getpass.getuser() or os.getlogin()
+
+    def get_useremail(self) -> str:
+        """Get the user email of the superproject VCS."""
+        email = ""
+        if GitLocalRepo(self.root_directory).is_git():
+            email = GitLocalRepo(self.root_directory).get_useremail()
+
+        elif SvnRepo(self.root_directory).is_svn():
+            email = SvnRepo(self.root_directory).get_useremail()
+
+        return email or f"{self.get_username()}@example.com"

dfetch/vcs/git.py

@@ -589,3 +589,25 @@ def find_branch_containing_sha(self, sha: str) -> str:
         ]
 
         return "" if not branches else branches[0]
+
+    def get_username(self) -> str:
+        """Get the username of the local git repo."""
+        try:
+            result = run_on_cmdline(
+                logger,
+                ["git", "config", "user.name"],
+            )
+            return str(result.stdout.decode().strip())
+        except SubprocessCommandError:
+            return ""
+
+    def get_useremail(self) -> str:
+        """Get the user email of the local git repo."""
+        try:
+            result = run_on_cmdline(
+                logger,
+                ["git", "config", "user.email"],
+            )
+            return str(result.stdout.decode().strip())
+        except SubprocessCommandError:
+            return ""

dfetch/vcs/patch.py

@@ -1,5 +1,6 @@
 """Various patch utilities for VCS systems."""
 
+import datetime
 import difflib
 import hashlib
 import stat
@@ -191,3 +192,87 @@ def reverse_patch(patch_text: bytes) -> str:
         reverse_patch_lines.append(b"")  # blank line between files
 
     return (b"\n".join(reverse_patch_lines)).decode(encoding="UTF-8")
+
+
+@dataclass
+class PatchAuthor:
+    """Information about a patch author."""
+
+    name: str
+    email: str
+
+
+@dataclass
+class PatchInfo:
+    """Information about a patch file."""
+
+    author: PatchAuthor
+    subject: str
+    total_files: int = 1
+    current_idx: int = 1
+    revision: str = ""
+    date: datetime.datetime = datetime.datetime.utcnow()
+    description: str = ""
+
+    def to_string(self) -> str:
+        """Convert patch info to a string."""
+        subject_line = (
+            f"[PATCH {self.current_idx}/{self.total_files}] {self.subject}"
+            if self.total_files > 1
+            else f"[PATCH] {self.subject}"
+        )
+        return (
+            f"From {self.revision or '0000000000000000000000000000000000000000'} Mon Sep 17 00:00:00 2001\n"
+            f"From: {self.author.name} <{self.author.email}>\n"
+            f"Date: {self.date:%a, %d %b %Y %H:%M:%S +0000}\n"
+            f"Subject: {subject_line}\n"
+            "\n"
+            f"{self.description if self.description else self.subject}\n"
+        )
+
+
+def format_patch_with_prefix(
+    patch_text: bytes, patch_info: PatchInfo, path_prefix: str
+) -> str:
+    """Rewrite a patch to prefix file paths and add a mail-style header."""
+    patch = patch_ng.fromstring(patch_text)
+
+    if not patch:
+        return ""
+
+    out: list[bytes] = patch_info.to_string().encode("utf-8").splitlines()
+
+    for file in patch.items:
+        # normalize prefix (no leading/trailing slash surprises)
+        prefix = path_prefix.strip("/").encode()
+        prefix = prefix + b"/" if prefix else b""
+
+        src = file.source
+        tgt = file.target
+
+        # strip a/ b/ if present
+        if src.startswith(b"a/"):
+            src = src[2:]
+        if tgt.startswith(b"b/"):
+            tgt = tgt[2:]
+
+        new_src = b"a/" + prefix + src
+        new_tgt = b"b/" + prefix + tgt
+
+        # diff header
+        out.append(b"")
+        out.append(b"diff --git " + new_src + b" " + new_tgt)
+        out.append(b"--- " + new_src)
+        out.append(b"+++ " + new_tgt)
+
+        for hunk in file.hunks:
+            out.append(
+                f"@@ -{hunk.startsrc},{hunk.linessrc} "
+                f"+{hunk.starttgt},{hunk.linestgt} @@".encode()
+            )
+            for line in hunk.text:
+                out.append(line.rstrip(b"\n"))
+
+        out.append(b"")  # blank line between files
+
+    return b"\n".join(out).decode("utf-8")

dfetch/vcs/svn.py

@@ -334,3 +334,26 @@ def create_diff(
             patch_text = run_on_cmdline(logger, cmd).stdout
 
         return filter_patch(patch_text, ignore)
+
+    def get_username(self) -> str:
+        """Get the username of the local svn repo."""
+        try:
+            result = run_on_cmdline(
+                logger,
+                [
+                    "svn",
+                    "info",
+                    "--non-interactive",
+                    "--show-item",
+                    "author",
+                    self._path,
+                ],
+            )
+            return str(result.stdout.decode().strip())
+        except SubprocessCommandError:
+            return ""
+
+    def get_useremail(self) -> str:
+        """Get the user email of the local svn repo."""
+        # SVN does not have user email concept
+        return ""