linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] Documentation: Document how to get links with git am
@ 2019-11-15 13:30 Linus Walleij
  2019-11-15 20:00 ` Jonathan Corbet
  0 siblings, 1 reply; 6+ messages in thread
From: Linus Walleij @ 2019-11-15 13:30 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: linux-doc, Linus Walleij, Kees Cook

This adds Kees' clever apply hook to the kernel documentation so
it can be easily references when needed.

Cc: Kees Cook <keescook@chromium.org>
Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 .../process/applying-patches-using-git.rst    | 43 +++++++++++++++++++
 Documentation/process/index.rst               |  1 +
 2 files changed, 44 insertions(+)
 create mode 100644 Documentation/process/applying-patches-using-git.rst

diff --git a/Documentation/process/applying-patches-using-git.rst b/Documentation/process/applying-patches-using-git.rst
new file mode 100644
index 000000000000..60955aa62d42
--- /dev/null
+++ b/Documentation/process/applying-patches-using-git.rst
@@ -0,0 +1,43 @@
+.. _applying_patches_using_git:
+
+Applying Patches to the Linux Kernel Using git
+++++++++++++++++++++++++++++++++++++++++++++++
+
+For the most part, using git to apply patches comes down to just following
+the established usage already documented in the git documentation. This is
+pretty intuitive since git was developed initially for Linux kernel
+development.
+
+In some cases the Linux kernel development has special quirks and usage
+patterns that are not an intrinsic part of git.
+
+This file documents some best practices.
+
+
+Creating commit links to lore.kernel.org
+========================================
+
+The web site http://lore.kernel.org is meant as a grand archive of all mail
+list traffic concerning or influencing the kernel development. Storing archives
+of patches here is a recommended practice, and when a maintainer applies a
+patch to a subsystem tree, it is a good idea to provide a Link: tag with a
+reference back to the lore archive so that people that browse the commit
+history can find related discussions and rationale behind a certain change.
+The link tag will look like this:
+
+    Link: https://lore.kernel.org/r/<message-id>
+
+This can be achieved by adding the following hook into your git:
+
+.. code-block:: none
+
+	$ git config am.messageid true
+	$ cat >.git/hooks/applypatch-msg <<'EOF'
+	#!/bin/sh
+	. git-sh-setup
+	perl -pi -e 's|^Message-Id:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1"
+	test -x "$GIT_DIR/hooks/commit-msg" &&
+		exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"}
+	:
+	EOF
+	$ chmod a+x .git/hooks/applypatch-msg
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index e2c9ffc682c5..482b07402836 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -46,6 +46,7 @@ Other guides to the community that are of interest to most developers are:
    kernel-docs
    deprecated
    embargoed-hardware-issues
+   applying-patches-using-git
 
 These are some overall technical guides that have been put here for now for
 lack of a better place.
-- 
2.21.0


^ permalink raw reply related	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-11-18 18:52 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-11-15 13:30 [PATCH] Documentation: Document how to get links with git am Linus Walleij
2019-11-15 20:00 ` Jonathan Corbet
2019-11-15 23:18   ` Kees Cook
2019-11-18 18:46     ` Jonathan Corbet
2019-11-15 23:32   ` Linus Walleij
2019-11-18 18:52     ` Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).