mirror of
https://github.com/git/git
synced 2024-08-27 19:49:21 +00:00
![Daniel Watson](/assets/img/avatar_default.png)
Without the word "the", the sentence is a little harder to read. The word "the" makes it clearer that the comment refers to discrete patches, and not portions of individual patches. Signed-off-by: Daniel Watson <ozzloy@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
635 lines
26 KiB
Plaintext
635 lines
26 KiB
Plaintext
Submitting Patches
|
|
==================
|
|
|
|
== Guidelines
|
|
|
|
Here are some guidelines for people who want to contribute their code to this
|
|
software. There is also a link:MyFirstContribution.html[step-by-step tutorial]
|
|
available which covers many of these same guidelines.
|
|
|
|
[[base-branch]]
|
|
=== Decide what to base your work on.
|
|
|
|
In general, always base your work on the oldest branch that your
|
|
change is relevant to.
|
|
|
|
* A bugfix should be based on `maint` in general. If the bug is not
|
|
present in `maint`, base it on `master`. For a bug that's not yet
|
|
in `master`, find the topic that introduces the regression, and
|
|
base your work on the tip of the topic.
|
|
|
|
* A new feature should be based on `master` in general. If the new
|
|
feature depends on other topics that are in `next`, but not in
|
|
`master`, fork a branch from the tip of `master`, merge these topics
|
|
to the branch, and work on that branch. You can remind yourself of
|
|
how you prepared the base with `git log --first-parent master..`.
|
|
|
|
* Corrections and enhancements to a topic not yet in `master` should
|
|
be based on the tip of that topic. If the topic has not been merged
|
|
to `next`, it's alright to add a note to squash minor corrections
|
|
into the series.
|
|
|
|
* In the exceptional case that a new feature depends on several topics
|
|
not in `master`, start working on `next` or `seen` privately and
|
|
send out patches only for discussion. Once your new feature starts
|
|
to stabilize, you would have to rebase it (see the "depends on other
|
|
topics" above).
|
|
|
|
* Some parts of the system have dedicated maintainers with their own
|
|
repositories (see the section "Subsystems" below). Changes to
|
|
these parts should be based on their trees.
|
|
|
|
To find the tip of a topic branch, run `git log --first-parent
|
|
master..seen` and look for the merge commit. The second parent of this
|
|
commit is the tip of the topic branch.
|
|
|
|
[[separate-commits]]
|
|
=== Make separate commits for logically separate changes.
|
|
|
|
Unless your patch is really trivial, you should not be sending
|
|
out a patch that was generated between your working tree and
|
|
your commit head. Instead, always make a commit with complete
|
|
commit message and generate a series of patches from your
|
|
repository. It is a good discipline.
|
|
|
|
Give an explanation for the change(s) that is detailed enough so
|
|
that people can judge if it is good thing to do, without reading
|
|
the actual patch text to determine how well the code does what
|
|
the explanation promises to do.
|
|
|
|
If your description starts to get too long, that's a sign that you
|
|
probably need to split up your commit to finer grained pieces.
|
|
That being said, patches which plainly describe the things that
|
|
help reviewers check the patch, and future maintainers understand
|
|
the code, are the most beautiful patches. Descriptions that summarize
|
|
the point in the subject well, and describe the motivation for the
|
|
change, the approach taken by the change, and if relevant how this
|
|
differs substantially from the prior version, are all good things
|
|
to have.
|
|
|
|
Make sure that you have tests for the bug you are fixing. See
|
|
`t/README` for guidance.
|
|
|
|
[[tests]]
|
|
When adding a new feature, make sure that you have new tests to show
|
|
the feature triggers the new behavior when it should, and to show the
|
|
feature does not trigger when it shouldn't. After any code change,
|
|
make sure that the entire test suite passes. When fixing a bug, make
|
|
sure you have new tests that break if somebody else breaks what you
|
|
fixed by accident to avoid regression. Also, try merging your work to
|
|
'next' and 'seen' and make sure the tests still pass; topics by others
|
|
that are still in flight may have unexpected interactions with what
|
|
you are trying to do in your topic.
|
|
|
|
Pushing to a fork of https://github.com/git/git will use their CI
|
|
integration to test your changes on Linux, Mac and Windows. See the
|
|
<<GHCI,GitHub CI>> section for details.
|
|
|
|
Do not forget to update the documentation to describe the updated
|
|
behavior and make sure that the resulting documentation set formats
|
|
well (try the Documentation/doc-diff script).
|
|
|
|
We currently have a liberal mixture of US and UK English norms for
|
|
spelling and grammar, which is somewhat unfortunate. A huge patch that
|
|
touches the files all over the place only to correct the inconsistency
|
|
is not welcome, though. Potential clashes with other changes that can
|
|
result from such a patch are not worth it. We prefer to gradually
|
|
reconcile the inconsistencies in favor of US English, with small and
|
|
easily digestible patches, as a side effect of doing some other real
|
|
work in the vicinity (e.g. rewriting a paragraph for clarity, while
|
|
turning en_UK spelling to en_US). Obvious typographical fixes are much
|
|
more welcomed ("teh -> "the"), preferably submitted as independent
|
|
patches separate from other documentation changes.
|
|
|
|
[[whitespace-check]]
|
|
Oh, another thing. We are picky about whitespaces. Make sure your
|
|
changes do not trigger errors with the sample pre-commit hook shipped
|
|
in `templates/hooks--pre-commit`. To help ensure this does not happen,
|
|
run `git diff --check` on your changes before you commit.
|
|
|
|
[[describe-changes]]
|
|
=== Describe your changes well.
|
|
|
|
The log message that explains your changes is just as important as the
|
|
changes themselves. Your code may be clearly written with in-code
|
|
comment to sufficiently explain how it works with the surrounding
|
|
code, but those who need to fix or enhance your code in the future
|
|
will need to know _why_ your code does what it does, for a few
|
|
reasons:
|
|
|
|
. Your code may be doing something differently from what you wanted it
|
|
to do. Writing down what you actually wanted to achieve will help
|
|
them fix your code and make it do what it should have been doing
|
|
(also, you often discover your own bugs yourself, while writing the
|
|
log message to summarize the thought behind it).
|
|
|
|
. Your code may be doing things that were only necessary for your
|
|
immediate needs (e.g. "do X to directories" without implementing or
|
|
even designing what is to be done on files). Writing down why you
|
|
excluded what the code does not do will help guide future developers.
|
|
Writing down "we do X to directories, because directories have
|
|
characteristic Y" would help them infer "oh, files also have the same
|
|
characteristic Y, so perhaps doing X to them would also make sense?".
|
|
Saying "we don't do the same X to files, because ..." will help them
|
|
decide if the reasoning is sound (in which case they do not waste
|
|
time extending your code to cover files), or reason differently (in
|
|
which case, they can explain why they extend your code to cover
|
|
files, too).
|
|
|
|
The goal of your log message is to convey the _why_ behind your
|
|
change to help future developers.
|
|
|
|
The first line of the commit message should be a short description (50
|
|
characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
|
|
and should skip the full stop. It is also conventional in most cases to
|
|
prefix the first line with "area: " where the area is a filename or
|
|
identifier for the general area of the code being modified, e.g.
|
|
|
|
* doc: clarify distinction between sign-off and pgp-signing
|
|
* githooks.txt: improve the intro section
|
|
|
|
If in doubt which identifier to use, run `git log --no-merges` on the
|
|
files you are modifying to see the current conventions.
|
|
|
|
[[summary-section]]
|
|
The title sentence after the "area:" prefix omits the full stop at the
|
|
end, and its first word is not capitalized (the omission
|
|
of capitalization applies only to the word after the "area:"
|
|
prefix of the title) unless there is a reason to
|
|
capitalize it other than because it is the first word in the sentence.
|
|
E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
|
|
improve...", not "githooks.txt: Improve...". But "refs: HEAD is also
|
|
treated as a ref" is correct, as we spell `HEAD` in all caps even when
|
|
it appears in the middle of a sentence.
|
|
|
|
[[meaningful-message]]
|
|
The body should provide a meaningful commit message, which:
|
|
|
|
. explains the problem the change tries to solve, i.e. what is wrong
|
|
with the current code without the change.
|
|
|
|
. justifies the way the change solves the problem, i.e. why the
|
|
result with the change is better.
|
|
|
|
. alternate solutions considered but discarded, if any.
|
|
|
|
[[present-tense]]
|
|
The problem statement that describes the status quo is written in the
|
|
present tense. Write "The code does X when it is given input Y",
|
|
instead of "The code used to do Y when given input X". You do not
|
|
have to say "Currently"---the status quo in the problem statement is
|
|
about the code _without_ your change, by project convention.
|
|
|
|
[[imperative-mood]]
|
|
Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
|
|
instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
|
|
to do frotz", as if you are giving orders to the codebase to change
|
|
its behavior. Try to make sure your explanation can be understood
|
|
without external resources. Instead of giving a URL to a mailing list
|
|
archive, summarize the relevant points of the discussion.
|
|
|
|
[[commit-reference]]
|
|
|
|
There are a few reasons why you may want to refer to another commit in
|
|
the "more stable" part of the history (i.e. on branches like `maint`,
|
|
`master`, and `next`):
|
|
|
|
. A commit that introduced the root cause of a bug you are fixing.
|
|
|
|
. A commit that introduced a feature that you are enhancing.
|
|
|
|
. A commit that conflicts with your work when you made a trial merge
|
|
of your work into `next` and `seen` for testing.
|
|
|
|
When you reference a commit on a more stable branch (like `master`,
|
|
`maint` and `next`), use the format "abbreviated hash (subject,
|
|
date)", like this:
|
|
|
|
....
|
|
Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
|
|
noticed that ...
|
|
....
|
|
|
|
The "Copy commit summary" command of gitk can be used to obtain this
|
|
format (with the subject enclosed in a pair of double-quotes), or this
|
|
invocation of `git show`:
|
|
|
|
....
|
|
git show -s --pretty=reference <commit>
|
|
....
|
|
|
|
or, on an older version of Git without support for --pretty=reference:
|
|
|
|
....
|
|
git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
|
|
....
|
|
|
|
[[sign-off]]
|
|
=== Certify your work by adding your `Signed-off-by` trailer
|
|
|
|
To improve tracking of who did what, we ask you to certify that you
|
|
wrote the patch or have the right to pass it on under the same license
|
|
as ours, by "signing off" your patch. Without sign-off, we cannot
|
|
accept your patches.
|
|
|
|
If (and only if) you certify the below D-C-O:
|
|
|
|
[[dco]]
|
|
.Developer's Certificate of Origin 1.1
|
|
____
|
|
By making a contribution to this project, I certify that:
|
|
|
|
a. The contribution was created in whole or in part by me and I
|
|
have the right to submit it under the open source license
|
|
indicated in the file; or
|
|
|
|
b. The contribution is based upon previous work that, to the best
|
|
of my knowledge, is covered under an appropriate open source
|
|
license and I have the right under that license to submit that
|
|
work with modifications, whether created in whole or in part
|
|
by me, under the same open source license (unless I am
|
|
permitted to submit under a different license), as indicated
|
|
in the file; or
|
|
|
|
c. The contribution was provided directly to me by some other
|
|
person who certified (a), (b) or (c) and I have not modified
|
|
it.
|
|
|
|
d. I understand and agree that this project and the contribution
|
|
are public and that a record of the contribution (including all
|
|
personal information I submit with it, including my sign-off) is
|
|
maintained indefinitely and may be redistributed consistent with
|
|
this project or the open source license(s) involved.
|
|
____
|
|
|
|
you add a "Signed-off-by" trailer to your commit, that looks like
|
|
this:
|
|
|
|
....
|
|
Signed-off-by: Random J Developer <random@developer.example.org>
|
|
....
|
|
|
|
This line can be added by Git if you run the git-commit command with
|
|
the -s option.
|
|
|
|
Notice that you can place your own `Signed-off-by` trailer when
|
|
forwarding somebody else's patch with the above rules for
|
|
D-C-O. Indeed you are encouraged to do so. Do not forget to
|
|
place an in-body "From: " line at the beginning to properly attribute
|
|
the change to its true author (see (2) above).
|
|
|
|
This procedure originally came from the Linux kernel project, so our
|
|
rule is quite similar to theirs, but what exactly it means to sign-off
|
|
your patch differs from project to project, so it may be different
|
|
from that of the project you are accustomed to.
|
|
|
|
[[real-name]]
|
|
Also notice that a real name is used in the `Signed-off-by` trailer. Please
|
|
don't hide your real name.
|
|
|
|
[[commit-trailers]]
|
|
If you like, you can put extra tags at the end:
|
|
|
|
. `Reported-by:` is used to credit someone who found the bug that
|
|
the patch attempts to fix.
|
|
. `Acked-by:` says that the person who is more familiar with the area
|
|
the patch attempts to modify liked the patch.
|
|
. `Reviewed-by:`, unlike the other tags, can only be offered by the
|
|
reviewers themselves when they are completely satisfied with the
|
|
patch after a detailed analysis.
|
|
. `Tested-by:` is used to indicate that the person applied the patch
|
|
and found it to have the desired effect.
|
|
|
|
You can also create your own tag or use one that's in common usage
|
|
such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
|
|
|
|
[[git-tools]]
|
|
=== Generate your patch using Git tools out of your commits.
|
|
|
|
Git based diff tools generate unidiff which is the preferred format.
|
|
|
|
You do not have to be afraid to use `-M` option to `git diff` or
|
|
`git format-patch`, if your patch involves file renames. The
|
|
receiving end can handle them just fine.
|
|
|
|
[[review-patch]]
|
|
Please make sure your patch does not add commented out debugging code,
|
|
or include any extra files which do not relate to what your patch
|
|
is trying to achieve. Make sure to review
|
|
your patch after generating it, to ensure accuracy. Before
|
|
sending out, please make sure it cleanly applies to the base you
|
|
have chosen in the "Decide what to base your work on" section,
|
|
and unless it targets the `master` branch (which is the default),
|
|
mark your patches as such.
|
|
|
|
|
|
[[send-patches]]
|
|
=== Sending your patches.
|
|
|
|
:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
|
|
|
|
Before sending any patches, please note that patches that may be
|
|
security relevant should be submitted privately to the Git Security
|
|
mailing list{security-ml}, instead of the public mailing list.
|
|
|
|
Learn to use format-patch and send-email if possible. These commands
|
|
are optimized for the workflow of sending patches, avoiding many ways
|
|
your existing e-mail client that is optimized for "multipart/*" mime
|
|
type e-mails to corrupt and render your patches unusable.
|
|
|
|
People on the Git mailing list need to be able to read and
|
|
comment on the changes you are submitting. It is important for
|
|
a developer to be able to "quote" your changes, using standard
|
|
e-mail tools, so that they may comment on specific portions of
|
|
your code. For this reason, each patch should be submitted
|
|
"inline" in a separate message.
|
|
|
|
Multiple related patches should be grouped into their own e-mail
|
|
thread to help readers find all parts of the series. To that end,
|
|
send them as replies to either an additional "cover letter" message
|
|
(see below), the first patch, or the respective preceding patch.
|
|
|
|
If your log message (including your name on the
|
|
`Signed-off-by` trailer) is not writable in ASCII, make sure that
|
|
you send off a message in the correct encoding.
|
|
|
|
WARNING: Be wary of your MUAs word-wrap
|
|
corrupting your patch. Do not cut-n-paste your patch; you can
|
|
lose tabs that way if you are not careful.
|
|
|
|
It is a common convention to prefix your subject line with
|
|
[PATCH]. This lets people easily distinguish patches from other
|
|
e-mail discussions. Use of markers in addition to PATCH within
|
|
the brackets to describe the nature of the patch is also
|
|
encouraged. E.g. [RFC PATCH] (where RFC stands for "request for
|
|
comments") is often used to indicate a patch needs further
|
|
discussion before being accepted, [PATCH v2], [PATCH v3] etc.
|
|
are often seen when you are sending an update to what you have
|
|
previously sent.
|
|
|
|
The `git format-patch` command follows the best current practice to
|
|
format the body of an e-mail message. At the beginning of the
|
|
patch should come your commit message, ending with the
|
|
`Signed-off-by` trailers, and a line that consists of three dashes,
|
|
followed by the diffstat information and the patch itself. If
|
|
you are forwarding a patch from somebody else, optionally, at
|
|
the beginning of the e-mail message just before the commit
|
|
message starts, you can put a "From: " line to name that person.
|
|
To change the default "[PATCH]" in the subject to "[<text>]", use
|
|
`git format-patch --subject-prefix=<text>`. As a shortcut, you
|
|
can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or
|
|
`-v <n>` instead of `--subject-prefix="PATCH v<n>"`.
|
|
|
|
You often want to add additional explanation about the patch,
|
|
other than the commit message itself. Place such "cover letter"
|
|
material between the three-dash line and the diffstat. For
|
|
patches requiring multiple iterations of review and discussion,
|
|
an explanation of changes between each iteration can be kept in
|
|
Git-notes and inserted automatically following the three-dash
|
|
line via `git format-patch --notes`.
|
|
|
|
[[attachment]]
|
|
Do not attach the patch as a MIME attachment, compressed or not.
|
|
Do not let your e-mail client send quoted-printable. Do not let
|
|
your e-mail client send format=flowed which would destroy
|
|
whitespaces in your patches. Many
|
|
popular e-mail applications will not always transmit a MIME
|
|
attachment as plain text, making it impossible to comment on
|
|
your code. A MIME attachment also takes a bit more time to
|
|
process. This does not decrease the likelihood of your
|
|
MIME-attached change being accepted, but it makes it more likely
|
|
that it will be postponed.
|
|
|
|
Exception: If your mailer is mangling patches then someone may ask
|
|
you to re-send them using MIME, that is OK.
|
|
|
|
[[pgp-signature]]
|
|
Do not PGP sign your patch. Most likely, your maintainer or other people on the
|
|
list would not have your PGP key and would not bother obtaining it anyway.
|
|
Your patch is not judged by who you are; a good patch from an unknown origin
|
|
has a far better chance of being accepted than a patch from a known, respected
|
|
origin that is done poorly or does incorrect things.
|
|
|
|
If you really really really really want to do a PGP signed
|
|
patch, format it as "multipart/signed", not a text/plain message
|
|
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
|
|
not a text/plain, it's something else.
|
|
|
|
:security-ml-ref: footnoteref:[security-ml]
|
|
|
|
As mentioned at the beginning of the section, patches that may be
|
|
security relevant should not be submitted to the public mailing list
|
|
mentioned below, but should instead be sent privately to the Git
|
|
Security mailing list{security-ml-ref}.
|
|
|
|
Send your patch with "To:" set to the mailing list, with "cc:" listing
|
|
people who are involved in the area you are touching (the `git
|
|
contacts` command in `contrib/contacts/` can help to
|
|
identify them), to solicit comments and reviews. Also, when you made
|
|
trial merges of your topic to `next` and `seen`, you may have noticed
|
|
work by others conflicting with your changes. There is a good possibility
|
|
that these people may know the area you are touching well.
|
|
|
|
:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
|
|
:git-ml: footnote:[The mailing list: git@vger.kernel.org]
|
|
|
|
After the list reached a consensus that it is a good idea to apply the
|
|
patch, re-send it with "To:" set to the maintainer{current-maintainer}
|
|
and "cc:" the list{git-ml} for inclusion. This is especially relevant
|
|
when the maintainer did not heavily participate in the discussion and
|
|
instead left the review to trusted others.
|
|
|
|
Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
|
|
`Tested-by:` lines as necessary to credit people who helped your
|
|
patch, and "cc:" them when sending such a final version for inclusion.
|
|
|
|
== Subsystems with dedicated maintainers
|
|
|
|
Some parts of the system have dedicated maintainers with their own
|
|
repositories.
|
|
|
|
- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav:
|
|
|
|
https://github.com/prati0100/git-gui.git
|
|
|
|
- `gitk-git/` comes from Paul Mackerras's gitk project:
|
|
|
|
git://git.ozlabs.org/~paulus/gitk
|
|
|
|
Those who are interested in improve gitk can volunteer to help Paul
|
|
in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
|
|
|
|
- `po/` comes from the localization coordinator, Jiang Xin:
|
|
|
|
https://github.com/git-l10n/git-po/
|
|
|
|
Patches to these parts should be based on their trees.
|
|
|
|
[[patch-flow]]
|
|
== An ideal patch flow
|
|
|
|
Here is an ideal patch flow for this project the current maintainer
|
|
suggests to the contributors:
|
|
|
|
. You come up with an itch. You code it up.
|
|
|
|
. Send it to the list and cc people who may need to know about
|
|
the change.
|
|
+
|
|
The people who may need to know are the ones whose code you
|
|
are butchering. These people happen to be the ones who are
|
|
most likely to be knowledgeable enough to help you, but
|
|
they have no obligation to help you (i.e. you ask for help,
|
|
don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
|
|
help you find out who they are.
|
|
|
|
. You get comments and suggestions for improvements. You may
|
|
even get them in an "on top of your change" patch form.
|
|
|
|
. Polish, refine, and re-send to the list and the people who
|
|
spend their time to improve your patch. Go back to step (2).
|
|
|
|
. The list forms consensus that the last round of your patch is
|
|
good. Send it to the maintainer and cc the list.
|
|
|
|
. A topic branch is created with the patch and is merged to `next`,
|
|
and cooked further and eventually graduates to `master`.
|
|
|
|
In any time between the (2)-(3) cycle, the maintainer may pick it up
|
|
from the list and queue it to `seen`, in order to make it easier for
|
|
people play with it without having to pick up and apply the patch to
|
|
their trees themselves.
|
|
|
|
[[patch-status]]
|
|
== Know the status of your patch after submission
|
|
|
|
* You can use Git itself to find out when your patch is merged in
|
|
master. `git pull --rebase` will automatically skip already-applied
|
|
patches, and will let you know. This works only if you rebase on top
|
|
of the branch in which your patch has been merged (i.e. it will not
|
|
tell you if your patch is merged in `seen` if you rebase on top of
|
|
master).
|
|
|
|
* Read the Git mailing list, the maintainer regularly posts messages
|
|
entitled "What's cooking in git.git" and "What's in git.git" giving
|
|
the status of various proposed changes.
|
|
|
|
== GitHub CI[[GHCI]]
|
|
|
|
With an account at GitHub, you can use GitHub CI to test your changes
|
|
on Linux, Mac and Windows. See
|
|
https://github.com/git/git/actions/workflows/main.yml for examples of
|
|
recent CI runs.
|
|
|
|
Follow these steps for the initial setup:
|
|
|
|
. Fork https://github.com/git/git to your GitHub account.
|
|
You can find detailed instructions how to fork here:
|
|
https://help.github.com/articles/fork-a-repo/
|
|
|
|
After the initial setup, CI will run whenever you push new changes
|
|
to your fork of Git on GitHub. You can monitor the test state of all your
|
|
branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
|
|
|
|
If a branch did not pass all test cases then it is marked with a red
|
|
cross. In that case you can click on the failing job and navigate to
|
|
"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
|
|
can also download "Artifacts" which are tarred (or zipped) archives
|
|
with test data relevant for debugging.
|
|
|
|
Then fix the problem and push your fix to your GitHub fork. This will
|
|
trigger a new CI build to ensure all tests pass.
|
|
|
|
[[mua]]
|
|
== MUA specific hints
|
|
|
|
Some of the patches I receive or pick up from the list share common
|
|
patterns of breakage. Please make sure your MUA is set up
|
|
properly not to corrupt whitespaces.
|
|
|
|
See the DISCUSSION section of linkgit:git-format-patch[1] for hints on
|
|
checking your patch by mailing it to yourself and applying with
|
|
linkgit:git-am[1].
|
|
|
|
While you are at it, check the resulting commit log message from
|
|
a trial run of applying the patch. If what is in the resulting
|
|
commit is not exactly what you would want to see, it is very
|
|
likely that your maintainer would end up hand editing the log
|
|
message when he applies your patch. Things like "Hi, this is my
|
|
first patch.\n", if you really want to put in the patch e-mail,
|
|
should come after the three-dash line that signals the end of the
|
|
commit message.
|
|
|
|
|
|
=== Pine
|
|
|
|
(Johannes Schindelin)
|
|
|
|
....
|
|
I don't know how many people still use pine, but for those poor
|
|
souls it may be good to mention that the quell-flowed-text is
|
|
needed for recent versions.
|
|
|
|
... the "no-strip-whitespace-before-send" option, too. AFAIK it
|
|
was introduced in 4.60.
|
|
....
|
|
|
|
(Linus Torvalds)
|
|
|
|
....
|
|
And 4.58 needs at least this.
|
|
|
|
diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
|
|
Author: Linus Torvalds <torvalds@g5.osdl.org>
|
|
Date: Mon Aug 15 17:23:51 2005 -0700
|
|
|
|
Fix pine whitespace-corruption bug
|
|
|
|
There's no excuse for unconditionally removing whitespace from
|
|
the pico buffers on close.
|
|
|
|
diff --git a/pico/pico.c b/pico/pico.c
|
|
--- a/pico/pico.c
|
|
+++ b/pico/pico.c
|
|
@@ -219,7 +219,9 @@ PICO *pm;
|
|
switch(pico_all_done){ /* prepare for/handle final events */
|
|
case COMP_EXIT : /* already confirmed */
|
|
packheader();
|
|
+#if 0
|
|
stripwhitespace();
|
|
+#endif
|
|
c |= COMP_EXIT;
|
|
break;
|
|
....
|
|
|
|
(Daniel Barkalow)
|
|
|
|
....
|
|
> A patch to SubmittingPatches, MUA specific help section for
|
|
> users of Pine 4.63 would be very much appreciated.
|
|
|
|
Ah, it looks like a recent version changed the default behavior to do the
|
|
right thing, and inverted the sense of the configuration option. (Either
|
|
that or Gentoo did it.) So you need to set the
|
|
"no-strip-whitespace-before-send" option, unless the option you have is
|
|
"strip-whitespace-before-send", in which case you should avoid checking
|
|
it.
|
|
....
|
|
|
|
=== Thunderbird, KMail, GMail
|
|
|
|
See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1].
|
|
|
|
=== Gnus
|
|
|
|
"|" in the `*Summary*` buffer can be used to pipe the current
|
|
message to an external program, and this is a handy way to drive
|
|
`git am`. However, if the message is MIME encoded, what is
|
|
piped into the program is the representation you see in your
|
|
`*Article*` buffer after unwrapping MIME. This is often not what
|
|
you would want for two reasons. It tends to screw up non ASCII
|
|
characters (most notably in people's names), and also
|
|
whitespaces (fatal in patches). Running "C-u g" to display the
|
|
message in raw form before using "|" to run the pipe can work
|
|
this problem around.
|