1 .. SPDX-License-Identifier: GPL-2.0
2
3 =====================================
4 Handling messy pull-request diffstats
5 =====================================
6
7 Subsystem maintainers routinely use ``git requ
8 process of sending work upstream. Normally, t
9 diffstat that shows which files will be touche
10 be changed. Occasionally, though, a repositor
11 complicated development history will yield a m
12 great deal of unrelated work. The result look
13 pull request is actually doing. This document
14 and how to fix things up; it is derived from T
15 found in Linus1_ and Linus2_.
16
17 .. _Linus1: https://lore.kernel.org/lkml/CAHk-
18 .. _Linus2: https://lore.kernel.org/lkml/CAHk-
19
20 A Git development history proceeds as a series
21 manner, mainline kernel development looks like
22
23 ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 ---
24
25 If one wants to see what has changed between t
26 this will do the job::
27
28 $ git diff --stat --summary vN-rc2..vN-rc3
29
30 Here, there are two clear points in the histor
31 "subtract" the beginning point from the end po
32 differences. The requested operation is unamb
33 understand.
34
35 When a subsystem maintainer creates a branch a
36 result in the simplest case is a history that
37
38 ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 ---
39 |
40 +-- c1 --- c2 --- ..
41
42 If that maintainer now uses ``git diff`` to se
43 the mainline branch (let's call it "linus") an
44 clear endpoints, and the result is as expected
45 generated with ``git request-pull`` will also
46 consider a slightly more complex development h
47
48 ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 ---
49 | |
50 | +-- c1 --- c2 --- ..
51 | /
52 +-- x1 --- x2 --- x3
53
54 Our maintainer has created one branch at vN-rc
55 two were then subsequently merged into c2. No
56 for cN may end up being messy indeed, and deve
57 why.
58
59 What is happening here is that there are no lo
60 the ``git diff`` operation to use. The develo
61 started in two different places; to generate t
62 ends up having pick one of them and hoping for
63 starts at vN-rc1, it may end up including all
64 and the second origin end point (vN-rc2), whic
65 maintainer had in mind. With all of that extr
66 may be impossible to tell what actually happen
67 to cN.
68
69 Maintainers often try to resolve this problem
70 branch or performing another merge with the li
71 the pull request. This approach tends not to
72 end of that pull request; rebasing and/or merg
73 upstream is a well-known way to get a grumpy r
74
75 So what is to be done? The best response when
76 situation is to indeed to do a merge with the
77 to be pulled into, but to do it privately, as
78 shame. Create a new, throwaway branch and do
79
80 ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 ---
81 | |
82 | +-- c1 --- c2 --- ..
83 | /
84 +-- x1 --- x2 --- x3
85
86 The merge operation resolves all of the compli
87 multiple beginning points, yielding a coherent
88 the differences from the mainline branch. Now
89 generate a diffstat with the desired informati
90
91 $ git diff -C --stat --summary linus..TEMP
92
93 Save the output from this command, then simply
94 definitely do not expose it to the outside wor
95 output and edit it into the messy pull request
96 shows what is really going on. That request c
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.