From 8d6451b9a51b555be2c9a6c326a980b2de00741a Mon Sep 17 00:00:00 2001 From: "Guilherme G. Piccoli" Date: Mon, 21 Mar 2022 11:41:33 -0300 Subject: [PATCH 01/11] Documentation: Fix duplicate statement about raw_spinlock_t type Unless it was duplicate on purpose, to emphasize that a raw_spinlock_t is always a spinning lock regardless of PREEMPT_RT or kernel config, it's a bit odd that this text is duplicate. So, this patch just clean it up, keeping the consistency with the other sections of the text. Cc: Thomas Gleixner Fixes: 919e9e6395cf ("Documentation: Add lock ordering and nesting documentation") Signed-off-by: Guilherme G. Piccoli Link: https://lore.kernel.org/r/20220321144133.49804-1-gpiccoli@igalia.com Signed-off-by: Jonathan Corbet --- Documentation/locking/locktypes.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index bfa75ea1b66a..9933faad4771 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -211,9 +211,6 @@ raw_spinlock_t and spinlock_t raw_spinlock_t -------------- -raw_spinlock_t is a strict spinning lock implementation regardless of the -kernel configuration including PREEMPT_RT enabled kernels. - raw_spinlock_t is a strict spinning lock implementation in all kernels, including PREEMPT_RT kernels. Use raw_spinlock_t only in real critical core code, low-level interrupt handling and places where disabling From d987d5ae51ecfa75e61f4de56c7e2bb77be57fea Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Sat, 26 Mar 2022 16:48:39 +0900 Subject: [PATCH 02/11] docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs' SVG -> PDF conversion is not required in "make htmldocs". It is pointless to always warn of a missing converter. Demote the log message in setupTools() to verbose. For "make pdfdocs" (or "make latexdocs"), promote the dynamic message of "include SVG raw" to a warn. Expand the message and recommend installing Inkscape or ImageMagick. Fixes: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion") Signed-off-by: Akira Yokosawa Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Cc: linux-doc@vger.kernel.org Acked-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kfigure.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index 24d2b2addcce..cefdbb7e7523 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -212,7 +212,7 @@ def setupTools(app): if convert_cmd: kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else: - kernellog.warn(app, + kernellog.verbose(app, "Neither inkscape(1) nor convert(1) found.\n" "For SVG to PDF conversion, " "install either Inkscape (https://inkscape.org/) (preferred) or\n" @@ -296,8 +296,10 @@ def convert_image(img_node, translator, src_fname=None): if translator.builder.format == 'latex': if not inkscape_cmd and convert_cmd is None: - kernellog.verbose(app, - "no SVG to PDF conversion available / include SVG raw.") + kernellog.warn(app, + "no SVG to PDF conversion available / include SVG raw." + "\nIncluding large raw SVGs can cause xelatex error." + "\nInstall Inkscape (preferred) or ImageMagick.") img_node.replace_self(file2literal(src_fname)) else: dst_fname = path.join(translator.builder.outdir, fname + '.pdf') From 01096e5cfe3ce5b26ccc933ad20401e24074a76a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:19 +0100 Subject: [PATCH 03/11] scripts/get_feat.pl: allow output the parsed file names Such output could be helpful while debugging it, but its main goal is to tell kernel_feat.py about what files were used by the script. Thie way, kernel_feat.py can add those as documentation dependencies. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/11b438ee01e00c866f5ea197d6aecc26e9f86945.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_feat.pl | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl index 457712355676..76cfb96b59b6 100755 --- a/scripts/get_feat.pl +++ b/scripts/get_feat.pl @@ -13,6 +13,7 @@ my $man; my $debug; my $arch; my $feat; +my $enable_fname; my $basename = abs_path($0); $basename =~ s,/[^/]+$,/,; @@ -31,6 +32,7 @@ GetOptions( 'arch=s' => \$arch, 'feat=s' => \$feat, 'feature=s' => \$feat, + "enable-fname" => \$enable_fname, man => \$man ) or pod2usage(2); @@ -95,6 +97,10 @@ sub parse_feat { return if ($file =~ m,($prefix)/arch-support.txt,); return if (!($file =~ m,arch-support.txt$,)); + if ($enable_fname) { + printf ".. FILE %s\n", abs_path($file); + } + my $subsys = ""; $subsys = $2 if ( m,.*($prefix)/([^/]+).*,); @@ -580,6 +586,11 @@ Output features for a single specific feature. Changes the location of the Feature files. By default, it uses the Documentation/features directory. +=item B<--enable-fname> + +Prints the file name of the feature files. This can be used in order to +track dependencies during documentation build. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple From 85999f03147e73fc5c0a0a3c0db1fad368ca75e4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:20 +0100 Subject: [PATCH 04/11] docs: kernel_feat.py: add build dependencies Ensure that the feature files will be regenerated if any changes happen at the Documentation/features files that were processed by gen_feat.pl. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/5cdf7a8300019129dcc09d4c2557f75908754445.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel_feat.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index 8138d69a6987..27b701ed3681 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -33,6 +33,7 @@ u""" import codecs import os +import re import subprocess import sys @@ -82,7 +83,7 @@ class KernelFeat(Directive): env = doc.settings.env cwd = path.dirname(doc.current_source) - cmd = "get_feat.pl rest --dir " + cmd = "get_feat.pl rest --enable-fname --dir " cmd += self.arguments[0] if len(self.arguments) > 1: @@ -102,7 +103,22 @@ class KernelFeat(Directive): shell_env["srctree"] = srctree lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) - nodeList = self.nestedParse(lines, fname) + + line_regex = re.compile("^\.\. FILE (\S+)$") + + out_lines = "" + + for line in lines.split("\n"): + match = line_regex.search(line) + if match: + fname = match.group(1) + + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(fname)) + else: + out_lines += line + "\n" + + nodeList = self.nestedParse(out_lines, fname) return nodeList def runCmd(self, cmd, **kwargs): From b4541803d858dc058e6ba5f1817ab89af95c9c21 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:21 +0100 Subject: [PATCH 05/11] docs: kernel_abi.py: add sphinx build dependencies Ensure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated. Reported-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel_abi.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index 4392b3cb4020..efab9b14a9f5 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -128,6 +128,7 @@ class KernelCmd(Directive): return out def nestedParse(self, lines, fname): + env = self.state.document.settings.env content = ViewList() node = nodes.section() @@ -154,6 +155,9 @@ class KernelCmd(Directive): self.do_parse(content, node) content = ViewList() + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(f)) + f = new_f # sphinx counts lines from 0 From bcf0a536bff913f3c77c4c469bff13fd9ebeb1e9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:22 +0100 Subject: [PATCH 06/11] docs: kernel_include.py: add sphinx build dependencies The files included by kernel-include should be added as build dependencies, in order for sphinx-build to rebuild the corresponding docs if any changes at the included file happens. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d30fc4fa422a13b7e1623d690945c46b58a55e79.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel_include.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index f523aa68a36b..abe768088377 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -59,6 +59,7 @@ class KernelInclude(Include): u"""KernelInclude (``kernel-include``) directive""" def run(self): + env = self.state.document.settings.env path = os.path.realpath( os.path.expandvars(self.arguments[0])) @@ -70,6 +71,8 @@ class KernelInclude(Include): self.arguments[0] = path + env.note_dependency(os.path.abspath(path)) + #return super(KernelInclude, self).run() # won't work, see HINTs in _run() return self._run() From 92b6de17b21cf74448d2397ef92d5ca856c6419f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:23 +0100 Subject: [PATCH 07/11] scripts/get_abi: change the file/line number meta info In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel_abi.py | 2 +- scripts/get_abi.pl | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index efab9b14a9f5..b5feb5b1d905 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -138,7 +138,7 @@ class KernelCmd(Directive): code_block += "\n " + l lines = code_block + "\n\n" - line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$") ln = 0 n = 0 f = fname diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 6212f58b69c6..25836ac0a33d 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -326,7 +326,7 @@ sub output_rest { my @filepath = split / /, $data{$what}->{filepath}; if ($enable_lineno) { - printf "#define LINENO %s%s#%s\n\n", + printf ".. LINENO %s%s#%s\n\n", $prefix, $file[0], $data{$what}->{line_no}; } @@ -1022,7 +1022,7 @@ logic (B<--no-rst-source>). =item B<--enable-lineno> -Enable output of #define LINENO lines. +Enable output of .. LINENO lines. =item B<--debug> I From b79dfef0e2fcf41c736e7012c59d1260aa60f075 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 26 Mar 2022 11:27:24 +0100 Subject: [PATCH 08/11] scripts/kernel-doc: change the line number meta info In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kerneldoc.py | 2 +- scripts/kernel-doc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 8189c33b9dda..9395892c7ba3 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -130,7 +130,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^#define LINENO ([0-9]+)$") + line_regex = re.compile("^\.\. LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match: diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9c084a2ba3b0..7516949bb049 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -424,7 +424,7 @@ sub get_kernel_version() { sub print_lineno { my $lineno = shift; if ($enable_lineno && defined($lineno)) { - print "#define LINENO " . $lineno . "\n"; + print ".. LINENO " . $lineno . "\n"; } } ## @@ -2478,7 +2478,7 @@ May be specified multiple times. =item -enable-lineno -Enable output of #define LINENO lines. +Enable output of .. LINENO lines. =back From 9df072c73b9891e44f7f59f3b7c8f852b4485e80 Mon Sep 17 00:00:00 2001 From: David Gow Date: Sat, 26 Mar 2022 13:44:15 +0800 Subject: [PATCH 09/11] Documentation: kunit: Fix cross-referencing warnings The Architecture chapter of the KUnit documentation tried to include copies of the kernel-doc for a couple of things, despite these already existing in the API documentation. This lead to some warnings: architecture:31: ./include/kunit/test.h:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture:163: ./include/kunit/test.h:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. architecture.rst:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture.rst:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. Get rid of these, and cleanup the mentions of the struct and macro in question so that sphinx generates a link to the existing copy of the documentation in the api/test document. Fixes: bc145b370c11 ("Documentation: KUnit: Added KUnit Architecture") Signed-off-by: David Gow Reviewed-by: Brendan Higgins Tested-by: Brendan Higgins Link: https://lore.kernel.org/r/20220326054414.637293-1-davidgow@google.com Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/kunit/architecture.rst | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/Documentation/dev-tools/kunit/architecture.rst b/Documentation/dev-tools/kunit/architecture.rst index aa2cea821e25..ff9c85a0bff2 100644 --- a/Documentation/dev-tools/kunit/architecture.rst +++ b/Documentation/dev-tools/kunit/architecture.rst @@ -26,10 +26,7 @@ The fundamental unit in KUnit is the test case. The KUnit test cases are grouped into KUnit suites. A KUnit test case is a function with type signature ``void (*)(struct kunit *test)``. These test case functions are wrapped in a struct called -``struct kunit_case``. For code, see: - -.. kernel-doc:: include/kunit/test.h - :identifiers: kunit_case +struct kunit_case. .. note: ``generate_params`` is optional for non-parameterized tests. @@ -152,18 +149,12 @@ Parameterized Tests Each KUnit parameterized test is associated with a collection of parameters. The test is invoked multiple times, once for each parameter value and the parameter is stored in the ``param_value`` field. -The test case includes a ``KUNIT_CASE_PARAM()`` macro that accepts a +The test case includes a KUNIT_CASE_PARAM() macro that accepts a generator function. The generator function is passed the previous parameter and returns the next parameter. It also provides a macro to generate common-case generators based on arrays. -For code, see: - -.. kernel-doc:: include/kunit/test.h - :identifiers: KUNIT_ARRAY_PARAM - - kunit_tool (Command Line Test Harness) ====================================== From be78837ca3c88eebd405103a7a2ce891c466b0db Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Tue, 29 Mar 2022 15:07:02 +0900 Subject: [PATCH 10/11] docs: sphinx/requirements: Limit jinja2<3.1 jinja2 release 3.1.0 (March 24, 2022) broke Sphinx<4.0. This looks like the result of deprecating Python 3.6. It has been tested against Sphinx 4.3.0 and later. Setting an upper limit of <3.1 to junja2 can unbreak Sphinx<4.0 including Sphinx 2.4.4. Signed-off-by: Akira Yokosawa Cc: Mauro Carvalho Chehab Cc: stable@vger.kernel.org # v5.15+ Link: https://lore.kernel.org/r/7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/sphinx/requirements.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 9a35f50798a6..2c573541ab71 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,2 +1,4 @@ +# jinja2>=3.1 is not compatible with Sphinx<4.0 +jinja2<3.1 sphinx_rtd_theme Sphinx==2.4.4 From 022bb490c79799229ef467d9ccc3e5966001b0ae Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 25 Mar 2022 15:51:35 -0600 Subject: [PATCH 11/11] docs: Add a document on how to fix a messy diffstat A branch with merges in will sometimes create a diffstat containing a lot of unrelated work at "git request-pull" time. Create a document based on Linus's advice (found in the links below) and add it to the maintainer manual in the hope of saving some wear on Linus's keyboard going forward. Link: https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/ Link: https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/ Acked-by: Borislav Petkov Reviewed-by: Akira Yokosawa Signed-off-by: Jonathan Corbet --- Documentation/maintainer/index.rst | 1 + Documentation/maintainer/messy-diffstat.rst | 96 +++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 Documentation/maintainer/messy-diffstat.rst diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index f0a60435b124..3e03283c144e 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -12,6 +12,7 @@ additions to this manual. configure-git rebasing-and-merging pull-requests + messy-diffstat maintainer-entry-profile modifying-patches diff --git a/Documentation/maintainer/messy-diffstat.rst b/Documentation/maintainer/messy-diffstat.rst new file mode 100644 index 000000000000..c015f66d7621 --- /dev/null +++ b/Documentation/maintainer/messy-diffstat.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Handling messy pull-request diffstats +===================================== + +Subsystem maintainers routinely use ``git request-pull`` as part of the +process of sending work upstream. Normally, the result includes a nice +diffstat that shows which files will be touched and how much of each will +be changed. Occasionally, though, a repository with a relatively +complicated development history will yield a massive diffstat containing a +great deal of unrelated work. The result looks ugly and obscures what the +pull request is actually doing. This document describes what is happening +and how to fix things up; it is derived from The Wisdom of Linus Torvalds, +found in Linus1_ and Linus2_. + +.. _Linus1: https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/ +.. _Linus2: https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/ + +A Git development history proceeds as a series of commits. In a simplified +manner, mainline kernel development looks like this:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + +If one wants to see what has changed between two points, a command like +this will do the job:: + + $ git diff --stat --summary vN-rc2..vN-rc3 + +Here, there are two clear points in the history; Git will essentially +"subtract" the beginning point from the end point and display the resulting +differences. The requested operation is unambiguous and easy enough to +understand. + +When a subsystem maintainer creates a branch and commits changes to it, the +result in the simplest case is a history that looks like:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | + +-- c1 --- c2 --- ... --- cN + +If that maintainer now uses ``git diff`` to see what has changed between +the mainline branch (let's call it "linus") and cN, there are still two +clear endpoints, and the result is as expected. So a pull request +generated with ``git request-pull`` will also be as expected. But now +consider a slightly more complex development history:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | | + | +-- c1 --- c2 --- ... --- cN + | / + +-- x1 --- x2 --- x3 + +Our maintainer has created one branch at vN-rc1 and another at vN-rc2; the +two were then subsequently merged into c2. Now a pull request generated +for cN may end up being messy indeed, and developers often end up wondering +why. + +What is happening here is that there are no longer two clear end points for +the ``git diff`` operation to use. The development culminating in cN +started in two different places; to generate the diffstat, ``git diff`` +ends up having pick one of them and hoping for the best. If the diffstat +starts at vN-rc1, it may end up including all of the changes between there +and the second origin end point (vN-rc2), which is certainly not what our +maintainer had in mind. With all of that extra junk in the diffstat, it +may be impossible to tell what actually happened in the changes leading up +to cN. + +Maintainers often try to resolve this problem by, for example, rebasing the +branch or performing another merge with the linus branch, then recreating +the pull request. This approach tends not to lead to joy at the receiving +end of that pull request; rebasing and/or merging just before pushing +upstream is a well-known way to get a grumpy response. + +So what is to be done? The best response when confronted with this +situation is to indeed to do a merge with the branch you intend your work +to be pulled into, but to do it privately, as if it were the source of +shame. Create a new, throwaway branch and do the merge there:: + + ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN + | | | + | +-- c1 --- c2 --- ... --- cN | + | / | | + +-- x1 --- x2 --- x3 +------------+-- TEMP + +The merge operation resolves all of the complications resulting from the +multiple beginning points, yielding a coherent result that contains only +the differences from the mainline branch. Now it will be possible to +generate a diffstat with the desired information:: + + $ git diff -C --stat --summary linus..TEMP + +Save the output from this command, then simply delete the TEMP branch; +definitely do not expose it to the outside world. Take the saved diffstat +output and edit it into the messy pull request, yielding a result that +shows what is really going on. That request can then be sent upstream.