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