Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

docs: process: Add base-commit trailer usage

One of the recurring complaints from both maintainers and CI system
operators is that performing git-am on received patches is difficult
without knowing the parent object in the git history on which the
patches are based. Without this information, there is a high likelihood
that git-am will fail due to conflicts, which is particularly
frustrating to CI operators.

Git versions starting with v2.9.0 are able to automatically include
base-commit information using the --base flag of git-format-patch.
Document this usage in process/submitting-patches, and add the rationale
for its inclusion, plus instructions for those not using git on where
the "base-commit:" trailer should go.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

authored by

Konstantin Ryabitsev and committed by
Jonathan Corbet
e8686a40 36bc683d

+52 -1
+52 -1
Documentation/process/submitting-patches.rst
··· 782 782 the cover email text) to link to an earlier version of the patch series. 783 783 784 784 785 - 16) Sending ``git pull`` requests 785 + 16) Providing base tree information 786 + ----------------------------------- 787 + 788 + When other developers receive your patches and start the review process, 789 + it is often useful for them to know where in the tree history they 790 + should place your work. This is particularly useful for automated CI 791 + processes that attempt to run a series of tests in order to establish 792 + the quality of your submission before the maintainer starts the review. 793 + 794 + If you are using ``git format-patch`` to generate your patches, you can 795 + automatically include the base tree information in your submission by 796 + using the ``--base`` flag. The easiest and most convenient way to use 797 + this option is with topical branches:: 798 + 799 + $ git checkout -t -b my-topical-branch master 800 + Branch 'my-topical-branch' set up to track local branch 'master'. 801 + Switched to a new branch 'my-topical-branch' 802 + 803 + [perform your edits and commits] 804 + 805 + $ git format-patch --base=auto --cover-letter -o outgoing/ master 806 + outgoing/0000-cover-letter.patch 807 + outgoing/0001-First-Commit.patch 808 + outgoing/... 809 + 810 + When you open ``outgoing/0000-cover-letter.patch`` for editing, you will 811 + notice that it will have the ``base-commit:`` trailer at the very 812 + bottom, which provides the reviewer and the CI tools enough information 813 + to properly perform ``git am`` without worrying about conflicts:: 814 + 815 + $ git checkout -b patch-review [base-commit-id] 816 + Switched to a new branch 'patch-review' 817 + $ git am patches.mbox 818 + Applying: First Commit 819 + Applying: ... 820 + 821 + Please see ``man git-format-patch`` for more information about this 822 + option. 823 + 824 + .. note:: 825 + 826 + The ``--base`` feature was introduced in git version 2.9.0. 827 + 828 + If you are not using git to format your patches, you can still include 829 + the same ``base-commit`` trailer to indicate the commit hash of the tree 830 + on which your work is based. You should add it either in the cover 831 + letter or in the first patch of the series and it should be placed 832 + either below the ``---`` line or at the very bottom of all other 833 + content, right before your email signature. 834 + 835 + 836 + 17) Sending ``git pull`` requests 786 837 --------------------------------- 787 838 788 839 If you have a series of patches, it may be most convenient to have the