brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 1 | Submitting Patches |
| 2 | ================== |
| 3 | |
| 4 | == Guidelines |
| 5 | |
Emily Shaffer | b75a219 | 2020-06-08 14:11:32 -0700 | [diff] [blame] | 6 | Here are some guidelines for people who want to contribute their code to this |
| 7 | software. There is also a link:MyFirstContribution.html[step-by-step tutorial] |
| 8 | available which covers many of these same guidelines. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 9 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 10 | [[base-branch]] |
| 11 | === Decide what to base your work on. |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 12 | |
| 13 | In general, always base your work on the oldest branch that your |
| 14 | change is relevant to. |
| 15 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 16 | * A bugfix should be based on `maint` in general. If the bug is not |
| 17 | present in `maint`, base it on `master`. For a bug that's not yet |
| 18 | in `master`, find the topic that introduces the regression, and |
| 19 | base your work on the tip of the topic. |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 20 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 21 | * A new feature should be based on `master` in general. If the new |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 22 | feature depends on other topics that are in `next`, but not in |
| 23 | `master`, fork a branch from the tip of `master`, merge these topics |
| 24 | to the branch, and work on that branch. You can remind yourself of |
| 25 | how you prepared the base with `git log --first-parent master..`. |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 26 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 27 | * Corrections and enhancements to a topic not yet in `master` should |
| 28 | be based on the tip of that topic. If the topic has not been merged |
| 29 | to `next`, it's alright to add a note to squash minor corrections |
| 30 | into the series. |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 31 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 32 | * In the exceptional case that a new feature depends on several topics |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 33 | not in `master`, start working on `next` or `seen` privately and |
| 34 | send out patches only for discussion. Once your new feature starts |
| 35 | to stabilize, you would have to rebase it (see the "depends on other |
| 36 | topics" above). |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 37 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 38 | * Some parts of the system have dedicated maintainers with their own |
| 39 | repositories (see the section "Subsystems" below). Changes to |
| 40 | these parts should be based on their trees. |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 41 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 42 | To find the tip of a topic branch, run `git log --first-parent |
Johannes Schindelin | 828197d | 2020-06-25 12:18:57 +0000 | [diff] [blame] | 43 | master..seen` and look for the merge commit. The second parent of this |
Ramkumar Ramachandra | d0c26f0 | 2010-04-19 01:24:20 +0530 | [diff] [blame] | 44 | commit is the tip of the topic branch. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 45 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 46 | [[separate-commits]] |
| 47 | === Make separate commits for logically separate changes. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 48 | |
| 49 | Unless your patch is really trivial, you should not be sending |
| 50 | out a patch that was generated between your working tree and |
| 51 | your commit head. Instead, always make a commit with complete |
| 52 | commit message and generate a series of patches from your |
| 53 | repository. It is a good discipline. |
| 54 | |
Junio C Hamano | d0f7dcb | 2011-03-08 16:58:19 -0800 | [diff] [blame] | 55 | Give an explanation for the change(s) that is detailed enough so |
| 56 | that people can judge if it is good thing to do, without reading |
| 57 | the actual patch text to determine how well the code does what |
| 58 | the explanation promises to do. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 59 | |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 60 | If your description starts to get too long, that's a sign that you |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 61 | probably need to split up your commit to finer grained pieces. |
Sam Vilain | 47afed5 | 2009-04-28 02:38:47 +1200 | [diff] [blame] | 62 | That being said, patches which plainly describe the things that |
| 63 | help reviewers check the patch, and future maintainers understand |
René Genz | 01e60a9 | 2017-04-30 17:42:21 +0200 | [diff] [blame] | 64 | the code, are the most beautiful patches. Descriptions that summarize |
Sam Vilain | 47afed5 | 2009-04-28 02:38:47 +1200 | [diff] [blame] | 65 | the point in the subject well, and describe the motivation for the |
| 66 | change, the approach taken by the change, and if relevant how this |
Junio C Hamano | d0f7dcb | 2011-03-08 16:58:19 -0800 | [diff] [blame] | 67 | differs substantially from the prior version, are all good things |
| 68 | to have. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 69 | |
Junio C Hamano | 54cc5d2 | 2014-11-24 09:43:29 -0800 | [diff] [blame] | 70 | Make sure that you have tests for the bug you are fixing. See |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 71 | `t/README` for guidance. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 72 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 73 | [[tests]] |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 74 | When adding a new feature, make sure that you have new tests to show |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 75 | the feature triggers the new behavior when it should, and to show the |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 76 | feature does not trigger when it shouldn't. After any code change, |
| 77 | make sure that the entire test suite passes. When fixing a bug, make |
| 78 | sure you have new tests that break if somebody else breaks what you |
| 79 | fixed by accident to avoid regression. Also, try merging your work to |
| 80 | 'next' and 'seen' and make sure the tests still pass; topics by others |
| 81 | that are still in flight may have unexpected interactions with what |
| 82 | you are trying to do in your topic. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 83 | |
Ævar Arnfjörð Bjarmason | f003a91 | 2021-07-22 14:11:24 +0200 | [diff] [blame] | 84 | Pushing to a fork of https://github.com/git/git will use their CI |
| 85 | integration to test your changes on Linux, Mac and Windows. See the |
| 86 | <<GHCI,GitHub CI>> section for details. |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 87 | |
| 88 | Do not forget to update the documentation to describe the updated |
| 89 | behavior and make sure that the resulting documentation set formats |
Jeff King | 7a76f5c | 2018-08-21 15:23:22 -0400 | [diff] [blame] | 90 | well (try the Documentation/doc-diff script). |
| 91 | |
| 92 | We currently have a liberal mixture of US and UK English norms for |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 93 | spelling and grammar, which is somewhat unfortunate. A huge patch that |
| 94 | touches the files all over the place only to correct the inconsistency |
| 95 | is not welcome, though. Potential clashes with other changes that can |
| 96 | result from such a patch are not worth it. We prefer to gradually |
| 97 | reconcile the inconsistencies in favor of US English, with small and |
| 98 | easily digestible patches, as a side effect of doing some other real |
| 99 | work in the vicinity (e.g. rewriting a paragraph for clarity, while |
| 100 | turning en_UK spelling to en_US). Obvious typographical fixes are much |
| 101 | more welcomed ("teh -> "the"), preferably submitted as independent |
| 102 | patches separate from other documentation changes. |
Marc Branchaud | 42e0fae | 2013-08-01 14:49:54 -0400 | [diff] [blame] | 103 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 104 | [[whitespace-check]] |
Marc Branchaud | 42e0fae | 2013-08-01 14:49:54 -0400 | [diff] [blame] | 105 | Oh, another thing. We are picky about whitespaces. Make sure your |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 106 | changes do not trigger errors with the sample pre-commit hook shipped |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 107 | in `templates/hooks--pre-commit`. To help ensure this does not happen, |
| 108 | run `git diff --check` on your changes before you commit. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 109 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 110 | [[describe-changes]] |
| 111 | === Describe your changes well. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 112 | |
Junio C Hamano | cdba029 | 2022-01-27 11:02:59 -0800 | [diff] [blame] | 113 | The log message that explains your changes is just as important as the |
| 114 | changes themselves. Your code may be clearly written with in-code |
| 115 | comment to sufficiently explain how it works with the surrounding |
| 116 | code, but those who need to fix or enhance your code in the future |
| 117 | will need to know _why_ your code does what it does, for a few |
| 118 | reasons: |
| 119 | |
| 120 | . Your code may be doing something differently from what you wanted it |
| 121 | to do. Writing down what you actually wanted to achieve will help |
| 122 | them fix your code and make it do what it should have been doing |
| 123 | (also, you often discover your own bugs yourself, while writing the |
| 124 | log message to summarize the thought behind it). |
| 125 | |
| 126 | . Your code may be doing things that were only necessary for your |
| 127 | immediate needs (e.g. "do X to directories" without implementing or |
| 128 | even designing what is to be done on files). Writing down why you |
| 129 | excluded what the code does not do will help guide future developers. |
| 130 | Writing down "we do X to directories, because directories have |
| 131 | characteristic Y" would help them infer "oh, files also have the same |
| 132 | characteristic Y, so perhaps doing X to them would also make sense?". |
| 133 | Saying "we don't do the same X to files, because ..." will help them |
| 134 | decide if the reasoning is sound (in which case they do not waste |
| 135 | time extending your code to cover files), or reason differently (in |
| 136 | which case, they can explain why they extend your code to cover |
| 137 | files, too). |
| 138 | |
| 139 | The goal of your log message is to convey the _why_ behind your |
| 140 | change to help future developers. |
| 141 | |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 142 | The first line of the commit message should be a short description (50 |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 143 | characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
| 144 | and should skip the full stop. It is also conventional in most cases to |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 145 | prefix the first line with "area: " where the area is a filename or |
| 146 | identifier for the general area of the code being modified, e.g. |
| 147 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 148 | * doc: clarify distinction between sign-off and pgp-signing |
| 149 | * githooks.txt: improve the intro section |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 150 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 151 | If in doubt which identifier to use, run `git log --no-merges` on the |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 152 | files you are modifying to see the current conventions. |
| 153 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 154 | [[summary-section]] |
Junio C Hamano | 151b6c2 | 2021-04-14 16:51:17 -0700 | [diff] [blame] | 155 | The title sentence after the "area:" prefix omits the full stop at the |
| 156 | end, and its first word is not capitalized unless there is a reason to |
| 157 | capitalize it other than because it is the first word in the sentence. |
| 158 | E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: |
| 159 | improve...", not "githooks.txt: Improve...". But "refs: HEAD is also |
| 160 | treated as a ref" is correct, as we spell `HEAD` in all caps even when |
| 161 | it appears in the middle of a sentence. |
Ævar Arnfjörð Bjarmason | 2ee0056 | 2017-03-21 14:21:53 +0000 | [diff] [blame] | 162 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 163 | [[meaningful-message]] |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 164 | The body should provide a meaningful commit message, which: |
| 165 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 166 | . explains the problem the change tries to solve, i.e. what is wrong |
| 167 | with the current code without the change. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 168 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 169 | . justifies the way the change solves the problem, i.e. why the |
| 170 | result with the change is better. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 171 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 172 | . alternate solutions considered but discarded, if any. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 173 | |
Junio C Hamano | fa1101a | 2022-01-27 11:02:57 -0800 | [diff] [blame] | 174 | [[present-tense]] |
| 175 | The problem statement that describes the status quo is written in the |
| 176 | present tense. Write "The code does X when it is given input Y", |
| 177 | instead of "The code used to do Y when given input X". You do not |
| 178 | have to say "Currently"---the status quo in the problem statement is |
| 179 | about the code _without_ your change, by project convention. |
| 180 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 181 | [[imperative-mood]] |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 182 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
| 183 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy |
| 184 | to do frotz", as if you are giving orders to the codebase to change |
René Genz | 01e60a9 | 2017-04-30 17:42:21 +0200 | [diff] [blame] | 185 | its behavior. Try to make sure your explanation can be understood |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 186 | without external resources. Instead of giving a URL to a mailing list |
| 187 | archive, summarize the relevant points of the discussion. |
| 188 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 189 | [[commit-reference]] |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 190 | |
| 191 | There are a few reasons why you may want to refer to another commit in |
| 192 | the "more stable" part of the history (i.e. on branches like `maint`, |
| 193 | `master`, and `next`): |
| 194 | |
| 195 | . A commit that introduced the root cause of a bug you are fixing. |
| 196 | |
| 197 | . A commit that introduced a feature that you are enhancing. |
| 198 | |
| 199 | . A commit that conflicts with your work when you made a trial merge |
| 200 | of your work into `next` and `seen` for testing. |
| 201 | |
| 202 | When you reference a commit on a more stable branch (like `master`, |
| 203 | `maint` and `next`), use the format "abbreviated hash (subject, |
| 204 | date)", like this: |
Beat Bolli | 4369523 | 2016-08-26 18:59:01 +0200 | [diff] [blame] | 205 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 206 | .... |
Denton Liu | fb2ffa7 | 2019-11-19 16:51:08 -0800 | [diff] [blame] | 207 | Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 208 | noticed that ... |
| 209 | .... |
Beat Bolli | 4369523 | 2016-08-26 18:59:01 +0200 | [diff] [blame] | 210 | |
| 211 | The "Copy commit summary" command of gitk can be used to obtain this |
Denton Liu | fb2ffa7 | 2019-11-19 16:51:08 -0800 | [diff] [blame] | 212 | format (with the subject enclosed in a pair of double-quotes), or this |
| 213 | invocation of `git show`: |
Heiko Voigt | 175d38c | 2016-07-28 14:55:14 +0200 | [diff] [blame] | 214 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 215 | .... |
Denton Liu | 3798149 | 2019-11-19 16:51:28 -0800 | [diff] [blame] | 216 | git show -s --pretty=reference <commit> |
| 217 | .... |
| 218 | |
| 219 | or, on an older version of Git without support for --pretty=reference: |
| 220 | |
| 221 | .... |
Denton Liu | fb2ffa7 | 2019-11-19 16:51:08 -0800 | [diff] [blame] | 222 | git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 223 | .... |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 224 | |
Ævar Arnfjörð Bjarmason | 4523dc8 | 2021-07-22 14:11:23 +0200 | [diff] [blame] | 225 | [[sign-off]] |
| 226 | === Certify your work by adding your `Signed-off-by` trailer |
| 227 | |
| 228 | To improve tracking of who did what, we ask you to certify that you |
| 229 | wrote the patch or have the right to pass it on under the same license |
| 230 | as ours, by "signing off" your patch. Without sign-off, we cannot |
| 231 | accept your patches. |
| 232 | |
| 233 | If (and only if) you certify the below D-C-O: |
| 234 | |
| 235 | [[dco]] |
| 236 | .Developer's Certificate of Origin 1.1 |
| 237 | ____ |
| 238 | By making a contribution to this project, I certify that: |
| 239 | |
| 240 | a. The contribution was created in whole or in part by me and I |
| 241 | have the right to submit it under the open source license |
| 242 | indicated in the file; or |
| 243 | |
| 244 | b. The contribution is based upon previous work that, to the best |
| 245 | of my knowledge, is covered under an appropriate open source |
| 246 | license and I have the right under that license to submit that |
| 247 | work with modifications, whether created in whole or in part |
| 248 | by me, under the same open source license (unless I am |
| 249 | permitted to submit under a different license), as indicated |
| 250 | in the file; or |
| 251 | |
| 252 | c. The contribution was provided directly to me by some other |
| 253 | person who certified (a), (b) or (c) and I have not modified |
| 254 | it. |
| 255 | |
| 256 | d. I understand and agree that this project and the contribution |
| 257 | are public and that a record of the contribution (including all |
| 258 | personal information I submit with it, including my sign-off) is |
| 259 | maintained indefinitely and may be redistributed consistent with |
| 260 | this project or the open source license(s) involved. |
| 261 | ____ |
| 262 | |
| 263 | you add a "Signed-off-by" trailer to your commit, that looks like |
| 264 | this: |
| 265 | |
| 266 | .... |
| 267 | Signed-off-by: Random J Developer <random@developer.example.org> |
| 268 | .... |
| 269 | |
| 270 | This line can be added by Git if you run the git-commit command with |
| 271 | the -s option. |
| 272 | |
| 273 | Notice that you can place your own `Signed-off-by` trailer when |
| 274 | forwarding somebody else's patch with the above rules for |
| 275 | D-C-O. Indeed you are encouraged to do so. Do not forget to |
| 276 | place an in-body "From: " line at the beginning to properly attribute |
| 277 | the change to its true author (see (2) above). |
| 278 | |
| 279 | This procedure originally came from the Linux kernel project, so our |
| 280 | rule is quite similar to theirs, but what exactly it means to sign-off |
| 281 | your patch differs from project to project, so it may be different |
| 282 | from that of the project you are accustomed to. |
| 283 | |
| 284 | [[real-name]] |
| 285 | Also notice that a real name is used in the `Signed-off-by` trailer. Please |
| 286 | don't hide your real name. |
| 287 | |
| 288 | [[commit-trailers]] |
| 289 | If you like, you can put extra tags at the end: |
| 290 | |
| 291 | . `Reported-by:` is used to credit someone who found the bug that |
| 292 | the patch attempts to fix. |
| 293 | . `Acked-by:` says that the person who is more familiar with the area |
| 294 | the patch attempts to modify liked the patch. |
| 295 | . `Reviewed-by:`, unlike the other tags, can only be offered by the |
| 296 | reviewers themselves when they are completely satisfied with the |
| 297 | patch after a detailed analysis. |
| 298 | . `Tested-by:` is used to indicate that the person applied the patch |
| 299 | and found it to have the desired effect. |
| 300 | |
| 301 | You can also create your own tag or use one that's in common usage |
| 302 | such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". |
| 303 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 304 | [[git-tools]] |
| 305 | === Generate your patch using Git tools out of your commits. |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 306 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 307 | Git based diff tools generate unidiff which is the preferred format. |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 308 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 309 | You do not have to be afraid to use `-M` option to `git diff` or |
| 310 | `git format-patch`, if your patch involves file renames. The |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 311 | receiving end can handle them just fine. |
| 312 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 313 | [[review-patch]] |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 314 | Please make sure your patch does not add commented out debugging code, |
| 315 | or include any extra files which do not relate to what your patch |
| 316 | is trying to achieve. Make sure to review |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 317 | your patch after generating it, to ensure accuracy. Before |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 318 | sending out, please make sure it cleanly applies to the base you |
| 319 | have chosen in the "Decide what to base your work on" section, |
| 320 | and unless it targets the `master` branch (which is the default), |
| 321 | mark your patches as such. |
| 322 | |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 323 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 324 | [[send-patches]] |
| 325 | === Sending your patches. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 326 | |
Thomas Gummerer | 2a00502 | 2018-05-30 21:52:55 +0100 | [diff] [blame] | 327 | :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] |
| 328 | |
| 329 | Before sending any patches, please note that patches that may be |
| 330 | security relevant should be submitted privately to the Git Security |
| 331 | mailing list{security-ml}, instead of the public mailing list. |
| 332 | |
Junio C Hamano | b25c469 | 2015-03-13 00:02:15 -0700 | [diff] [blame] | 333 | Learn to use format-patch and send-email if possible. These commands |
| 334 | are optimized for the workflow of sending patches, avoiding many ways |
| 335 | your existing e-mail client that is optimized for "multipart/*" mime |
| 336 | type e-mails to corrupt and render your patches unusable. |
| 337 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 338 | People on the Git mailing list need to be able to read and |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 339 | comment on the changes you are submitting. It is important for |
| 340 | a developer to be able to "quote" your changes, using standard |
| 341 | e-mail tools, so that they may comment on specific portions of |
René Scharfe | eaa6c98 | 2013-11-27 01:28:39 +0100 | [diff] [blame] | 342 | your code. For this reason, each patch should be submitted |
| 343 | "inline" in a separate message. |
| 344 | |
| 345 | Multiple related patches should be grouped into their own e-mail |
| 346 | thread to help readers find all parts of the series. To that end, |
| 347 | send them as replies to either an additional "cover letter" message |
| 348 | (see below), the first patch, or the respective preceding patch. |
| 349 | |
| 350 | If your log message (including your name on the |
Bradley M. Kuhn | 3abd4a6 | 2020-10-19 18:03:55 -0700 | [diff] [blame] | 351 | `Signed-off-by` trailer) is not writable in ASCII, make sure that |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 352 | you send off a message in the correct encoding. |
| 353 | |
| 354 | WARNING: Be wary of your MUAs word-wrap |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 355 | corrupting your patch. Do not cut-n-paste your patch; you can |
| 356 | lose tabs that way if you are not careful. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 357 | |
Junio C Hamano | 45d2b28 | 2006-02-17 16:15:26 -0800 | [diff] [blame] | 358 | It is a common convention to prefix your subject line with |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 359 | [PATCH]. This lets people easily distinguish patches from other |
Adam Dinwoodie | f6be7ed | 2017-11-10 15:02:50 +0000 | [diff] [blame] | 360 | e-mail discussions. Use of markers in addition to PATCH within |
| 361 | the brackets to describe the nature of the patch is also |
| 362 | encouraged. E.g. [RFC PATCH] (where RFC stands for "request for |
| 363 | comments") is often used to indicate a patch needs further |
| 364 | discussion before being accepted, [PATCH v2], [PATCH v3] etc. |
| 365 | are often seen when you are sending an update to what you have |
| 366 | previously sent. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 367 | |
Junio C Hamano | 1a5f2e4 | 2017-11-21 14:07:51 +0900 | [diff] [blame] | 368 | The `git format-patch` command follows the best current practice to |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 369 | format the body of an e-mail message. At the beginning of the |
| 370 | patch should come your commit message, ending with the |
Bradley M. Kuhn | 3abd4a6 | 2020-10-19 18:03:55 -0700 | [diff] [blame] | 371 | `Signed-off-by` trailers, and a line that consists of three dashes, |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 372 | followed by the diffstat information and the patch itself. If |
| 373 | you are forwarding a patch from somebody else, optionally, at |
| 374 | the beginning of the e-mail message just before the commit |
| 375 | message starts, you can put a "From: " line to name that person. |
Adam Dinwoodie | f6be7ed | 2017-11-10 15:02:50 +0000 | [diff] [blame] | 376 | To change the default "[PATCH]" in the subject to "[<text>]", use |
| 377 | `git format-patch --subject-prefix=<text>`. As a shortcut, you |
| 378 | can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or |
| 379 | `-v <n>` instead of `--subject-prefix="PATCH v<n>"`. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 380 | |
| 381 | You often want to add additional explanation about the patch, |
| 382 | other than the commit message itself. Place such "cover letter" |
Eric Sunshine | 8601099 | 2014-12-30 18:30:30 -0500 | [diff] [blame] | 383 | material between the three-dash line and the diffstat. For |
| 384 | patches requiring multiple iterations of review and discussion, |
| 385 | an explanation of changes between each iteration can be kept in |
| 386 | Git-notes and inserted automatically following the three-dash |
| 387 | line via `git format-patch --notes`. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 388 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 389 | [[attachment]] |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 390 | Do not attach the patch as a MIME attachment, compressed or not. |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 391 | Do not let your e-mail client send quoted-printable. Do not let |
| 392 | your e-mail client send format=flowed which would destroy |
| 393 | whitespaces in your patches. Many |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 394 | popular e-mail applications will not always transmit a MIME |
| 395 | attachment as plain text, making it impossible to comment on |
| 396 | your code. A MIME attachment also takes a bit more time to |
| 397 | process. This does not decrease the likelihood of your |
| 398 | MIME-attached change being accepted, but it makes it more likely |
| 399 | that it will be postponed. |
| 400 | |
| 401 | Exception: If your mailer is mangling patches then someone may ask |
Junio C Hamano | 9847f7e | 2005-08-28 17:54:18 -0700 | [diff] [blame] | 402 | you to re-send them using MIME, that is OK. |
Junio C Hamano | 3140825 | 2005-08-12 23:48:09 -0700 | [diff] [blame] | 403 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 404 | [[pgp-signature]] |
Cornelius Weig | eafd5d9 | 2017-01-27 21:01:36 +0100 | [diff] [blame] | 405 | Do not PGP sign your patch. Most likely, your maintainer or other people on the |
| 406 | list would not have your PGP key and would not bother obtaining it anyway. |
| 407 | Your patch is not judged by who you are; a good patch from an unknown origin |
| 408 | has a far better chance of being accepted than a patch from a known, respected |
| 409 | origin that is done poorly or does incorrect things. |
Junio C Hamano | 9847f7e | 2005-08-28 17:54:18 -0700 | [diff] [blame] | 410 | |
| 411 | If you really really really really want to do a PGP signed |
| 412 | patch, format it as "multipart/signed", not a text/plain message |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 413 | that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
Junio C Hamano | 9847f7e | 2005-08-28 17:54:18 -0700 | [diff] [blame] | 414 | not a text/plain, it's something else. |
| 415 | |
Thomas Gummerer | 2a00502 | 2018-05-30 21:52:55 +0100 | [diff] [blame] | 416 | :security-ml-ref: footnoteref:[security-ml] |
| 417 | |
| 418 | As mentioned at the beginning of the section, patches that may be |
| 419 | security relevant should not be submitted to the public mailing list |
| 420 | mentioned below, but should instead be sent privately to the Git |
| 421 | Security mailing list{security-ml-ref}. |
| 422 | |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 423 | Send your patch with "To:" set to the mailing list, with "cc:" listing |
Thomas Gummerer | 92a5dbb | 2018-04-11 21:20:00 +0100 | [diff] [blame] | 424 | people who are involved in the area you are touching (the `git |
| 425 | contacts` command in `contrib/contacts/` can help to |
Junio C Hamano | fdfae83 | 2021-12-30 12:18:35 -0800 | [diff] [blame] | 426 | identify them), to solicit comments and reviews. Also, when you made |
| 427 | trial merges of your topic to `next` and `seen`, you may have noticed |
| 428 | work by others conflicting with your changes. There is a good possibility |
| 429 | that these people may know the area you are touching well. |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 430 | |
Thomas Gummerer | a27cd1a | 2018-05-30 21:52:54 +0100 | [diff] [blame] | 431 | :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] |
| 432 | :git-ml: footnote:[The mailing list: git@vger.kernel.org] |
Junio C Hamano | 7d5bf87 | 2013-01-01 15:19:00 -0800 | [diff] [blame] | 433 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 434 | After the list reached a consensus that it is a good idea to apply the |
Junio C Hamano | d95b192 | 2020-10-09 11:56:52 -0700 | [diff] [blame] | 435 | patch, re-send it with "To:" set to the maintainer{current-maintainer} |
| 436 | and "cc:" the list{git-ml} for inclusion. This is especially relevant |
| 437 | when the maintainer did not heavily participate in the discussion and |
| 438 | instead left the review to trusted others. |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 439 | |
| 440 | Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and |
| 441 | `Tested-by:` lines as necessary to credit people who helped your |
Junio C Hamano | d95b192 | 2020-10-09 11:56:52 -0700 | [diff] [blame] | 442 | patch, and "cc:" them when sending such a final version for inclusion. |
Junio C Hamano | 04d2445 | 2006-10-24 01:29:27 -0700 | [diff] [blame] | 443 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 444 | == Subsystems with dedicated maintainers |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 445 | |
| 446 | Some parts of the system have dedicated maintainers with their own |
| 447 | repositories. |
| 448 | |
Junio C Hamano | 253bfe4 | 2019-09-18 13:57:13 -0700 | [diff] [blame] | 449 | - `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 450 | |
Junio C Hamano | 253bfe4 | 2019-09-18 13:57:13 -0700 | [diff] [blame] | 451 | https://github.com/prati0100/git-gui.git |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 452 | |
Corentin BOMPARD | 68ed71b | 2019-03-06 14:04:46 +0100 | [diff] [blame] | 453 | - `gitk-git/` comes from Paul Mackerras's gitk project: |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 454 | |
Junio C Hamano | b014cee | 2022-05-11 08:10:12 -0700 | [diff] [blame] | 455 | git://git.ozlabs.org/~paulus/gitk |
| 456 | |
| 457 | Those who are interested in improve gitk can volunteer to help Paul |
| 458 | in maintaining it cf. <YntxL/fTplFm8lr6@cleo>. |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 459 | |
Corentin BOMPARD | 68ed71b | 2019-03-06 14:04:46 +0100 | [diff] [blame] | 460 | - `po/` comes from the localization coordinator, Jiang Xin: |
Junio C Hamano | e6da8ee | 2013-01-01 14:37:56 -0800 | [diff] [blame] | 461 | |
| 462 | https://github.com/git-l10n/git-po/ |
| 463 | |
| 464 | Patches to these parts should be based on their trees. |
| 465 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 466 | [[patch-flow]] |
| 467 | == An ideal patch flow |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 468 | |
| 469 | Here is an ideal patch flow for this project the current maintainer |
| 470 | suggests to the contributors: |
| 471 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 472 | . You come up with an itch. You code it up. |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 473 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 474 | . Send it to the list and cc people who may need to know about |
| 475 | the change. |
| 476 | + |
| 477 | The people who may need to know are the ones whose code you |
| 478 | are butchering. These people happen to be the ones who are |
| 479 | most likely to be knowledgeable enough to help you, but |
| 480 | they have no obligation to help you (i.e. you ask for help, |
| 481 | don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would |
| 482 | help you find out who they are. |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 483 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 484 | . You get comments and suggestions for improvements. You may |
Ville Skyttä | 928f0ab | 2018-06-22 09:50:37 +0300 | [diff] [blame] | 485 | even get them in an "on top of your change" patch form. |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 486 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 487 | . Polish, refine, and re-send to the list and the people who |
| 488 | spend their time to improve your patch. Go back to step (2). |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 489 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 490 | . The list forms consensus that the last round of your patch is |
| 491 | good. Send it to the maintainer and cc the list. |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 492 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 493 | . A topic branch is created with the patch and is merged to `next`, |
| 494 | and cooked further and eventually graduates to `master`. |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 495 | |
| 496 | In any time between the (2)-(3) cycle, the maintainer may pick it up |
Johannes Schindelin | 828197d | 2020-06-25 12:18:57 +0000 | [diff] [blame] | 497 | from the list and queue it to `seen`, in order to make it easier for |
Junio C Hamano | a941fb4 | 2008-02-10 14:09:52 -0800 | [diff] [blame] | 498 | people play with it without having to pick up and apply the patch to |
| 499 | their trees themselves. |
| 500 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 501 | [[patch-status]] |
| 502 | == Know the status of your patch after submission |
Matthieu Moy | 63cb821 | 2009-12-30 15:51:22 +0100 | [diff] [blame] | 503 | |
| 504 | * You can use Git itself to find out when your patch is merged in |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 505 | master. `git pull --rebase` will automatically skip already-applied |
Matthieu Moy | 63cb821 | 2009-12-30 15:51:22 +0100 | [diff] [blame] | 506 | patches, and will let you know. This works only if you rebase on top |
| 507 | of the branch in which your patch has been merged (i.e. it will not |
Johannes Schindelin | 828197d | 2020-06-25 12:18:57 +0000 | [diff] [blame] | 508 | tell you if your patch is merged in `seen` if you rebase on top of |
Matthieu Moy | 63cb821 | 2009-12-30 15:51:22 +0100 | [diff] [blame] | 509 | master). |
| 510 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 511 | * Read the Git mailing list, the maintainer regularly posts messages |
Matthieu Moy | 63cb821 | 2009-12-30 15:51:22 +0100 | [diff] [blame] | 512 | entitled "What's cooking in git.git" and "What's in git.git" giving |
| 513 | the status of various proposed changes. |
| 514 | |
Philippe Blain | edbd9f3 | 2021-11-13 20:38:05 +0000 | [diff] [blame] | 515 | == GitHub CI[[GHCI]] |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 516 | |
Ævar Arnfjörð Bjarmason | f003a91 | 2021-07-22 14:11:24 +0200 | [diff] [blame] | 517 | With an account at GitHub, you can use GitHub CI to test your changes |
| 518 | on Linux, Mac and Windows. See |
| 519 | https://github.com/git/git/actions/workflows/main.yml for examples of |
| 520 | recent CI runs. |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 521 | |
| 522 | Follow these steps for the initial setup: |
| 523 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 524 | . Fork https://github.com/git/git to your GitHub account. |
| 525 | You can find detailed instructions how to fork here: |
| 526 | https://help.github.com/articles/fork-a-repo/ |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 527 | |
Ævar Arnfjörð Bjarmason | f003a91 | 2021-07-22 14:11:24 +0200 | [diff] [blame] | 528 | After the initial setup, CI will run whenever you push new changes |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 529 | to your fork of Git on GitHub. You can monitor the test state of all your |
Philippe Blain | edbd9f3 | 2021-11-13 20:38:05 +0000 | [diff] [blame] | 530 | branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 531 | |
| 532 | If a branch did not pass all test cases then it is marked with a red |
Ævar Arnfjörð Bjarmason | f003a91 | 2021-07-22 14:11:24 +0200 | [diff] [blame] | 533 | cross. In that case you can click on the failing job and navigate to |
| 534 | "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You |
| 535 | can also download "Artifacts" which are tarred (or zipped) archives |
| 536 | with test data relevant for debugging. |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 537 | |
Ævar Arnfjörð Bjarmason | f003a91 | 2021-07-22 14:11:24 +0200 | [diff] [blame] | 538 | Then fix the problem and push your fix to your GitHub fork. This will |
| 539 | trigger a new CI build to ensure all tests pass. |
Lars Schneider | 0e5d028 | 2016-05-02 10:12:12 +0200 | [diff] [blame] | 540 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 541 | [[mua]] |
| 542 | == MUA specific hints |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 543 | |
| 544 | Some of patches I receive or pick up from the list share common |
| 545 | patterns of breakage. Please make sure your MUA is set up |
Jonathan Nieder | 5775616 | 2011-04-14 21:24:01 -0500 | [diff] [blame] | 546 | properly not to corrupt whitespaces. |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 547 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 548 | See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
Jonathan Nieder | 5775616 | 2011-04-14 21:24:01 -0500 | [diff] [blame] | 549 | checking your patch by mailing it to yourself and applying with |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 550 | linkgit:git-am[1]. |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 551 | |
Jonathan Nieder | 5775616 | 2011-04-14 21:24:01 -0500 | [diff] [blame] | 552 | While you are at it, check the resulting commit log message from |
| 553 | a trial run of applying the patch. If what is in the resulting |
| 554 | commit is not exactly what you would want to see, it is very |
| 555 | likely that your maintainer would end up hand editing the log |
| 556 | message when he applies your patch. Things like "Hi, this is my |
| 557 | first patch.\n", if you really want to put in the patch e-mail, |
| 558 | should come after the three-dash line that signals the end of the |
| 559 | commit message. |
Junio C Hamano | 9847f7e | 2005-08-28 17:54:18 -0700 | [diff] [blame] | 560 | |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 561 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 562 | === Pine |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 563 | |
| 564 | (Johannes Schindelin) |
| 565 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 566 | .... |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 567 | I don't know how many people still use pine, but for those poor |
| 568 | souls it may be good to mention that the quell-flowed-text is |
| 569 | needed for recent versions. |
| 570 | |
| 571 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it |
| 572 | was introduced in 4.60. |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 573 | .... |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 574 | |
| 575 | (Linus Torvalds) |
| 576 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 577 | .... |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 578 | And 4.58 needs at least this. |
| 579 | |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 580 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
| 581 | Author: Linus Torvalds <torvalds@g5.osdl.org> |
| 582 | Date: Mon Aug 15 17:23:51 2005 -0700 |
| 583 | |
| 584 | Fix pine whitespace-corruption bug |
| 585 | |
| 586 | There's no excuse for unconditionally removing whitespace from |
| 587 | the pico buffers on close. |
| 588 | |
| 589 | diff --git a/pico/pico.c b/pico/pico.c |
| 590 | --- a/pico/pico.c |
| 591 | +++ b/pico/pico.c |
| 592 | @@ -219,7 +219,9 @@ PICO *pm; |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 593 | switch(pico_all_done){ /* prepare for/handle final events */ |
| 594 | case COMP_EXIT : /* already confirmed */ |
| 595 | packheader(); |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 596 | +#if 0 |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 597 | stripwhitespace(); |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 598 | +#endif |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 599 | c |= COMP_EXIT; |
| 600 | break; |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 601 | .... |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 602 | |
Junio C Hamano | 1eb446f | 2005-08-31 11:48:41 -0700 | [diff] [blame] | 603 | (Daniel Barkalow) |
| 604 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 605 | .... |
Junio C Hamano | 1eb446f | 2005-08-31 11:48:41 -0700 | [diff] [blame] | 606 | > A patch to SubmittingPatches, MUA specific help section for |
| 607 | > users of Pine 4.63 would be very much appreciated. |
| 608 | |
| 609 | Ah, it looks like a recent version changed the default behavior to do the |
| 610 | right thing, and inverted the sense of the configuration option. (Either |
| 611 | that or Gentoo did it.) So you need to set the |
| 612 | "no-strip-whitespace-before-send" option, unless the option you have is |
| 613 | "strip-whitespace-before-send", in which case you should avoid checking |
| 614 | it. |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 615 | .... |
Junio C Hamano | 1eb446f | 2005-08-31 11:48:41 -0700 | [diff] [blame] | 616 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 617 | === Thunderbird, KMail, GMail |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 618 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 619 | See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
Junio C Hamano | 9740d28 | 2005-08-26 23:53:07 -0700 | [diff] [blame] | 620 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 621 | === Gnus |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 622 | |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 623 | "|" in the `*Summary*` buffer can be used to pipe the current |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 624 | message to an external program, and this is a handy way to drive |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 625 | `git am`. However, if the message is MIME encoded, what is |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 626 | piped into the program is the representation you see in your |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 627 | `*Article*` buffer after unwrapping MIME. This is often not what |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 628 | you would want for two reasons. It tends to screw up non ASCII |
| 629 | characters (most notably in people's names), and also |
brian m. carlson | 049e64a | 2017-11-12 22:07:18 +0000 | [diff] [blame] | 630 | whitespaces (fatal in patches). Running "C-u g" to display the |
| 631 | message in raw form before using "|" to run the pipe can work |
Junio C Hamano | e30b217 | 2007-01-17 01:07:27 -0800 | [diff] [blame] | 632 | this problem around. |