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 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
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.
+run "git diff --check" on your changes before you commit.
(2) Describe your changes well.
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.
- . archive: ustar header checksum is computed unsigned
- . git-cherry-pick.txt: clarify the use of revision range notation
+ . 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.
+It's customary to start the remainder of the first line after "area: "
+with a lower-case letter. E.g. "doc: clarify...", not "doc:
+Clarify...", or "githooks.txt: improve...", not "githooks.txt:
+Improve...".
+
The body should provide a meaningful commit message, which:
- . explains the problem the change tries to solve, iow, what is wrong
+ . 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, iow, why the
+ . 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.
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 behaviour. Try to make sure your explanation can be understood
+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.
noticed that ...
The "Copy commit summary" command of gitk can be used to obtain this
-format.
+format, or this invocation of "git show":
+ git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
(3) Generate your patch using Git tools out of your commits.
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 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
+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: lines, and a line that consists of three dashes,
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"
The sign-off is a simple line at the end of the explanation for
the patch, which certifies that you wrote it or otherwise have
the right to pass it on as a open-source patch. The rules are
-pretty simple: if you can certify the below:
+pretty simple: if you can certify the below D-C-O:
Developer's Certificate of Origin 1.1