€•@      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ-/translations/zh_CN/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/zh_TW/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/it_IT/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ja_JP/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ko_KR/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/sp_SP/maintainer/messy-diffstat”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒG/var/lib/git/docbuild/linux/Documentation/maintainer/messy-diffstat.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ%Handling messy pull-request diffstats”h]”hŒ%Handling messy pull-request diffstats”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hXe  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_.”h]”(hŒ$Subsystem maintainers routinely use ”…””}”(hhËhžhhŸNh NubhŒliteral”“”)”}”(hŒ``git request-pull``”h]”hŒgit request-pull”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhhËubhX   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 ”…””}”(hhËhžhhŸNh NubhŒ	reference”“”)”}”(hŒLinus1_”h]”hŒLinus1”…””}”(hhéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒLinus1”Œrefuri”Œ`https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/”uh1hçhhËŒresolved”KubhŒ and ”…””}”(hhËhžhhŸNh Nubhè)”}”(hŒLinus2_”h]”hŒLinus2”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒLinus2”hùŒ`https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/”uh1hçhhËhûKubhŒ.”…””}”(hhËhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒtarget”“”)”}”(hŒl.. _Linus1: https://lore.kernel.org/lkml/CAHk-=wg3wXH2JNxkQi+eLZkpuxqV+wPiHhw_Jf7ViH33Sw7PHA@mail.gmail.com/”h]”h}”(h]”Œlinus1”ah ]”h"]”Œlinus1”ah$]”h&]”hùhúuh1j  h Khh¶hžhhŸh³Œ
referenced”Kubj  )”}”(hŒl.. _Linus2: https://lore.kernel.org/lkml/CAHk-=wgXbSa8yq8Dht8at+gxb_idnJ7X5qWZQWRBN4_CUPr=eQ@mail.gmail.com/”h]”h}”(h]”Œlinus2”ah ]”h"]”Œlinus2”ah$]”h&]”hùj  uh1j  h Khh¶hžhhŸh³j)  KubhÊ)”}”(hŒA Git development history proceeds as a series of commits.  In a simplified
manner, mainline kernel development looks like this::”h]”hŒ€A Git development history proceeds as a series of commits.  In a simplified
manner, mainline kernel development looks like this:”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒliteral_block”“”)”}”(hŒA... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN”h]”hŒA... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN”…””}”hjF  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h Khh¶hžhubhÊ)”}”(hŒ^If one wants to see what has changed between two points, a command like
this will do the job::”h]”hŒ]If one wants to see what has changed between two points, a command like
this will do the job:”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubjE  )”}”(hŒ*$ git diff --stat --summary vN-rc2..vN-rc3”h]”hŒ*$ git diff --stat --summary vN-rc2..vN-rc3”…””}”hjb  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h Khh¶hžhubhÊ)”}”(hŒå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.”h]”hŒé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.”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒ†When a subsystem maintainer creates a branch and commits changes to it, the
result in the simplest case is a history that looks like::”h]”hŒ…When a subsystem maintainer creates a branch and commits changes to it, the
result in the simplest case is a history that looks like:”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K#hh¶hžhubjE  )”}”(hŒ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
                        |
                        +-- c1 --- c2 --- ... --- cN”h]”hŒ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
                        |
                        +-- c1 --- c2 --- ... --- cN”…””}”hjŒ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h K&hh¶hžhubhÊ)”}”(hXQ  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::”h]”(hŒIf that maintainer now uses ”…””}”(hjš  hžhhŸNh NubhÔ)”}”(hŒ``git diff``”h]”hŒgit diff”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjš  ubhŒÁ 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 ”…””}”(hjš  hžhhŸNh NubhÔ)”}”(hŒ``git request-pull``”h]”hŒgit request-pull”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjš  ubhŒY will also be as expected.  But now
consider a slightly more complex development history:”…””}”(hjš  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K*hh¶hžhubjE  )”}”(hŒ×... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
              |         |
              |         +-- c1 --- c2 --- ... --- cN
              |                   /
              +-- x1 --- x2 --- x3”h]”hŒ×... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
              |         |
              |         +-- c1 --- c2 --- ... --- cN
              |                   /
              +-- x1 --- x2 --- x3”…””}”hjÌ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h K0hh¶hžhubhÊ)”}”(hŒä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.”h]”hŒä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.”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K6hh¶hžhubhÊ)”}”(hXS  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.”h]”(hŒPWhat is happening here is that there are no longer two clear end points for
the ”…””}”(hjè  hžhhŸNh NubhÔ)”}”(hŒ``git diff``”h]”hŒgit diff”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjè  ubhŒq operation to use.  The development culminating in cN
started in two different places; to generate the diffstat, ”…””}”(hjè  hžhhŸNh NubhÔ)”}”(hŒ``git diff``”h]”hŒgit diff”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhjè  ubhXz  
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.”…””}”(hjè  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K;hh¶hžhubhÊ)”}”(hX]  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.”h]”hX]  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.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KEhh¶hžhubhÊ)”}”(hX  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::”h]”hX  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:”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KKhh¶hžhubjE  )”}”(hXL  ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
              |         |                                      |
              |         +-- c1 --- c2 --- ... --- cN           |
              |                   /               |            |
              +-- x1 --- x2 --- x3                +------------+-- TEMP”h]”hXL  ... vM --- vN-rc1 --- vN-rc2 --- vN-rc3 --- ... --- vN-rc7 --- vN
              |         |                                      |
              |         +-- c1 --- c2 --- ... --- cN           |
              |                   /               |            |
              +-- x1 --- x2 --- x3                +------------+-- TEMP”…””}”hj6  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h KPhh¶hžhubhÊ)”}”(hX
  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::”h]”hX	  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:”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KVhh¶hžhubjE  )”}”(hŒ*$ git diff -C --stat --summary linus..TEMP”h]”hŒ*$ git diff -C --stat --summary linus..TEMP”…””}”hjR  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jD  hŸh³h K[hh¶hžhubhÊ)”}”(hX   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.”h]”hX   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.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K]hh¶hžhubeh}”(h]”Œ%handling-messy-pull-request-diffstats”ah ]”h"]”Œ%handling messy pull-request diffstats”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j™  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”(Œlinus1”]”héaŒlinus2”]”j   auŒrefids”}”Œnameids”}”(js  jp  j&  j#  j3  j0  uŒ	nametypes”}”(js  ‰j&  ˆj3  ˆuh}”(jp  h¶j#  j  j0  j*  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.