- check for unnecessary whitespace with "git diff --check"
before committing
- do not check in commented out code or unneeded files
- - provide a meaningful commit message
- the first line of the commit message should be a short
- description and should skip the full stop
- - if you want your work included in git.git, add a
- "Signed-off-by: Your Name <your@email.com>" line to the
- commit message (or just use the option "-s" when
- committing) to confirm that you agree to the Developer's
- Certificate of Origin
+ description (50 characters is the soft limit, see DISCUSSION
+ in git-commit(1)), and should skip the full stop
+ - the body should provide a meaningful commit message, which:
+ - uses the imperative, present tense: "change",
+ not "changed" or "changes".
+ - includes motivation for the change, and contrasts
+ its implementation with previous behaviour
+ - add a "Signed-off-by: Your Name <you@example.com>" line to the
+ commit message (or just use the option "-s" when committing)
+ to confirm that you agree to the Developer's Certificate of Origin
+ - make sure that you have tests for the bug you are fixing
+ - make sure that the test suite passes after your commit
Patch:
- use "git format-patch -M" to create the patch
- - send your patch to <git@vger.kernel.org>. If you use
- git-send-email(1), please test it first by sending
- email to yourself.
- do not PGP sign your patch
- do not attach your patch, but read in the mail
body, unless you cannot teach your mailer to
corrupt whitespaces.
- provide additional information (which is unsuitable for
the commit message) between the "---" and the diffstat
- - send the patch to the list _and_ the maintainer
- if you change, add, or remove a command line option or
make some other user interface change, the associated
documentation should be updated as well.
+ - if your name is not writable in ASCII, make sure that
+ you send off a message in the correct encoding.
+ - send the patch to the list (git@vger.kernel.org) and the
+ maintainer (gitster@pobox.com) if (and only if) the patch
+ is ready for inclusion. If you use git-send-email(1),
+ please test it first by sending email to yourself.
+ - see below for instructions specific to your mailer
Long version:
here on the technical/contents front, because the core GIT is
thousand times smaller ;-). So here is only the relevant bits.
+(0) 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 a topic that is in 'pu', but not in 'master',
+ base your work on the tip of that topic.
+
+ - 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 'pu' privately and send
+ out patches for discussion. Before the final merge, you may have to
+ wait until some of the dependent topics graduate to 'master', and
+ rebase your work.
+
+To find the tip of a topic branch, run "git log --first-parent
+master..pu" and look for the merge commit. The second parent of this
+commit is the tip of the topic branch.
(1) Make separate commits for logically separate changes.
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 summarise
+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, can be found on Usenet
+archives back into the late 80's. Consider it like good Netiquette,
+but for code.
Oh, another thing. I am picky about whitespaces. Make sure your
changes do not trigger errors with the sample pre-commit hook shipped
(1a) Try to be nice to older C compilers
-We try to support wide range of C compilers to compile
+We try to support a wide range of C compilers to compile
git with. That means that you should not use C99 initializers, even
if a lot of compilers grok it.
It is a common convention to prefix your subject line with
[PATCH]. This lets people easily distinguish patches from other
-e-mail discussions.
+e-mail discussions. Use of additional markers after PATCH and
+the closing bracket to mark the nature of the patch is also
+encouraged. E.g. [PATCH/RFC] is often used when the patch is
+not ready to be applied but it is for discussion, [PATCH v2],
+[PATCH v3] etc. are often seen when you are sending an update to
+what you have previously sent.
"git format-patch" command follows the best current practice to
format the body of an e-mail message. At the beginning of the
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
not a text/plain, it's something else.
-Note that your maintainer does not necessarily read everything
-on the git mailing list. If your patch is for discussion first,
-send it "To:" the mailing list, and optionally "cc:" him. If it
-is trivially correct or after the list reached a consensus, send
-it "To:" the maintainer and optionally "cc:" the list.
-
-Also note that your maintainer does not actively involve himself in
-maintaining what are in contrib/ hierarchy. When you send fixes and
-enhancements to them, do not forget to "cc: " the person who primarily
-worked on that hierarchy in contrib/.
+Unless your patch is a very trivial and an obviously correct one,
+first send it with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the output from
+"git blame $path" and "git shortlog --no-merges $path" would help to
+identify them), to solicit comments and reviews. 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 and optionally "cc:" the list for
+inclusion. Do not forget to add trailers such as "Acked-by:",
+"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
+necessary.
(4) Sign your work
This line can be automatically added by git if you run the git-commit
command with the -s option.
-Some people also put extra tags at the end. They'll just be ignored for
-now, but you can do this to mark internal company procedures or just
-point out some special detail about the sign-off.
+Notice that you can place your own Signed-off-by: line 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).
+
+Also notice that a real name is used in the Signed-off-by: line. Please
+don't hide your real name.
+
+If you like, you can put extra tags at the end:
+
+1. "Reported-by:" is used to to credit someone who found the bug that
+ the patch attempts to fix.
+2. "Acked-by:" says that the person who is more familiar with the area
+ the patch attempts to modify liked the patch.
+3. "Reviewed-by:", unlike the other tags, can only be offered by the
+ reviewer and means that she is completely satisfied that the patch
+ is ready for application. It is usually offered only after a
+ detailed review.
+4. "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:".
+
+------------------------------------------------
+An ideal patch flow
+
+Here is an ideal patch flow for this project the current maintainer
+suggests to the contributors:
+
+ (0) You come up with an itch. You code it up.
+
+ (1) 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 -- $area_you_are_modifying" would
+ help you find out who they are.
+
+ (2) You get comments and suggestions for improvements. You may
+ even get them in a "on top of your change" patch form.
+
+ (3) Polish, refine, and re-send to the list and the people who
+ spend their time to improve your patch. Go back to step (2).
+
+ (4) The list forms consensus that the last round of your patch is
+ good. Send it to the list and cc the maintainer.
+
+ (5) 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 'pu', in order to make it easier for
+people play with it without having to pick up and apply the patch to
+their trees themselves.
+
+------------------------------------------------
+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 pu 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.
------------------------------------------------
MUA specific hints
$ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
$ git checkout test-apply
$ git reset --hard
- $ git applymbox a.patch
+ $ git am a.patch
If it does not apply correctly, there can be various reasons.
does not have much to do with your MUA. Please rebase the
patch appropriately.
-* Your MUA corrupted your patch; applymbox would complain that
- the patch does not apply. Look at .dotest/ subdirectory and
+* Your MUA corrupted your patch; "am" would complain that
+ the patch does not apply. Look at .git/rebase-apply/ subdirectory and
see what 'patch' file contains and check for the common
corruption patterns mentioned above.
--- 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();
+ switch(pico_all_done){ /* prepare for/handle final events */
+ case COMP_EXIT : /* already confirmed */
+ packheader();
+#if 0
- stripwhitespace();
+ stripwhitespace();
+#endif
- c |= COMP_EXIT;
- break;
-
+ c |= COMP_EXIT;
+ break;
+
(Daniel Barkalow)
(A Large Angry SCM)
+By default, Thunderbird will both wrap emails as well as flag them as
+being 'format=flowed', both of which will make the resulting email unusable
+by git.
+
Here are some hints on how to successfully submit patches inline using
Thunderbird.
+There are two different approaches. One approach is to configure
+Thunderbird to not mangle patches. The second approach is to use
+an external editor to keep Thunderbird from mangling the patches.
+
+Approach #1 (configuration):
+
+This recipe is current as of Thunderbird 2.0.0.19. Three steps:
+ 1. Configure your mail server composition as plain text
+ Edit...Account Settings...Composition & Addressing,
+ uncheck 'Compose Messages in HTML'.
+ 2. Configure your general composition window to not wrap
+ Edit..Preferences..Composition, wrap plain text messages at 0
+ 3. Disable the use of format=flowed
+ Edit..Preferences..Advanced..Config Editor. Search for:
+ mailnews.send_plaintext_flowed
+ toggle it to make sure it is set to 'false'.
+
+After that is done, you should be able to compose email as you
+otherwise would (cut + paste, git-format-patch | git-imap-send, etc),
+and the patches should not be mangled.
+
+Approach #2 (external editor):
+
This recipe appears to work with the current [*1*] Thunderbird from Suse.
The following Thunderbird extensions are needed:
mail.identity.default.compose_html => false
mail.identity.id?.compose_html => false
+(Lukas Sandström)
+
+There is a script in contrib/thunderbird-patch-inline which can help
+you include patches with Thunderbird in an easy way. To use it, do the
+steps above and then use the script as the external editor.
Gnus
----
5) Back in the compose window: add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.
+
+
+Gmail
+-----
+
+GMail does not appear to have any way to turn off line wrapping in the web
+interface, so this will mangle any emails that you send. You can however
+use "git send-email" and send your patches through the GMail SMTP server, or
+use any IMAP email client to connect to the google IMAP server and forward
+the emails through that.
+
+To use "git send-email" and send your patches through the GMail SMTP server,
+edit ~/.gitconfig to specify your account settings:
+
+[sendemail]
+ smtpencryption = tls
+ smtpserver = smtp.gmail.com
+ smtpuser = user@gmail.com
+ smtppass = p4ssw0rd
+ smtpserverport = 587
+
+Once your commits are ready to be sent to the mailing list, run the
+following commands:
+
+ $ git format-patch --cover-letter -M origin/master -o outgoing/
+ $ edit outgoing/0000-*
+ $ git send-email outgoing/*
+
+To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your
+account settings:
+
+[imap]
+ folder = "[Gmail]/Drafts"
+ host = imaps://imap.gmail.com
+ user = user@gmail.com
+ pass = p4ssw0rd
+ port = 993
+ sslverify = false
+
+You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
+that the "Folder doesn't exist".
+
+Once your commits are ready to be sent to the mailing list, run the
+following commands:
+
+ $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+Just make sure to disable line wrapping in the email client (GMail web
+interface will line wrap no matter what, so you need to use a real
+IMAP client).
+