git/Documentation
Kristoffer Haugsbakk d0c6ecea23 SubmittingPatches: encourage trailer use for substantial help
Trailers beyond the mandatory s-o-b are regularly used based on my
last two years of reading the mailing list. Moreover, reviewers might
encourage it.[1]

This is also in line with the project crediting both commit authors and
people mentioned in trailers each release; “Nobody is THE one making
contribution”.[2]

Adding trailers is already encouraged, but in the section `send-patches`.
Let’s replace “If you like” with outright encouragement in this section
so that all trailer discussion (except s-o-b; see `sign-off` section) is
contained in this section; a link to from `send-patches` makes this
information equally visible.

Now we need to make a heading for `commit-trailers` in order for the
HTML output to make sense.

At the same time, it is important to temper this recommendation to a
significant enough contribution; in my experience beginners can be eager
to add a trailer for everyone who replies with an action point that is
followed up on.

Let’s also spell out that these trailers should follow the Git author/
committer format. One might naturally just write the name, but in that
case it will not be picked up by:

    git shortlog --group=trailer:<key>

and normalization via `.mailmap` will not work.

Also introduce the list of common trailers as such. Granted, this is
already implied by the later paragraph about “create your own trailer”,
so this just frontloads this information.

† 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least
† 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2026-06-19 09:13:25 -07:00
..
RelNotes Git 2.55-rc0 2026-06-11 04:31:19 -07:00
config Merge branch 'ib/doc-push-default-simple' 2026-06-09 10:04:51 +09:00
howto meson: make GIT_HTML_PATH configurable 2025-11-06 09:58:56 -08:00
includes
mergetools doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
technical path-walk: always emit directly-requested objects 2026-05-24 18:41:06 +09:00
.gitignore
BreakingChanges.adoc safe.bareRepository: default to "explicit" with WITH_BREAKING_CHANGES 2026-04-27 14:50:54 +09:00
CodingGuidelines Merge branch 'jc/doc-timestamps-in-stat' 2026-05-11 10:05:54 +09:00
DecisionMaking.adoc
Makefile Merge branch 'en/xdiff-cleanup-2' 2025-12-05 14:49:56 +09:00
MyFirstContribution.adoc Merge branch 'sd/doc-my1c-api-config-reference-fix' 2026-02-13 13:39:26 -08:00
MyFirstObjectWalk.adoc Merge branch 'jc/you-still-use-whatchanged' 2025-06-25 14:07:35 -07:00
ReviewingGuidelines.adoc
SubmittingPatches SubmittingPatches: encourage trailer use for substantial help 2026-06-19 09:13:25 -07:00
ToolsForGit.adoc
asciidoc.conf.in doc: convert git-bisect to synopsis style 2026-05-25 20:05:44 +09:00
asciidoctor-extensions.rb.in doc: git-log: convert rev list options to new doc format 2025-07-07 13:45:00 -07:00
blame-options.adoc doc: blame-options: convert to new doc format 2026-01-09 06:15:31 -08:00
build-docdep.perl
cat-texi.perl
cmd-list.sh Documentation: stop depending on Perl to generate command list 2025-04-16 07:30:30 -07:00
config.adoc doc: config: include existing git-hook(1) section 2026-05-22 09:36:20 +09:00
date-formats.adoc
diff-algorithm-option.adoc blame: make diff algorithm configurable 2025-11-17 09:31:59 -08:00
diff-context-options.adoc diff: document -U without <n> as using default context 2026-03-10 06:17:59 -07:00
diff-format.adoc diff-format.adoc: mode and hash are 0* for unmerged paths from index only 2026-05-16 22:21:37 +09:00
diff-generate-patch.adoc Merge branch 'ma/doc-diff-cc-headers' 2025-06-18 13:53:34 -07:00
diff-options.adoc Merge branch 'mm/doc-word-diff' 2026-06-11 04:31:19 -07:00
doc-diff
docbook-xsl.css
docbook.xsl
docinfo-html.in
everyday.adoco
fetch-options.adoc remote: add remote.*.negotiationInclude config 2026-05-20 11:33:24 +09:00
fix-texi.sh Documentation: stop depending on Perl to massage user manual 2025-04-16 07:30:29 -07:00
for-each-ref-options.adoc doc: fix some style issues in git-clone and for-each-ref-options 2026-02-05 21:14:05 -08:00
format-patch-caveats.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
format-patch-end-of-commit-message.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
fsck-msgids.adoc builtin/fsck: move generic HEAD check into `refs_fsck()` 2026-01-12 06:55:41 -08:00
generate-mergetool-list.sh
git-add.adoc Documentation: update add --force option + ignore=all config 2026-02-06 09:43:26 -08:00
git-am.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-annotate.adoc
git-apply.adoc doc: convert git-apply synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-archimport.adoc
git-archive.adoc archive: document --prefix handling of absolute and parent paths 2026-04-08 11:13:52 -07:00
git-backfill.adoc pack-objects: support sparse:oid filter with path-walk 2026-05-24 18:41:06 +09:00
git-bisect-lk2009.adoc
git-bisect.adoc doc: git bisect: clarify the usage of the synopsis vs actual command 2026-05-25 20:05:44 +09:00
git-blame.adoc doc: git-blame: convert to new doc format 2026-01-09 06:15:53 -08:00
git-branch.adoc doc: branch: fix inline-verbatim 2025-05-05 10:48:07 -07:00
git-bugreport.adoc
git-bundle.adoc
git-cat-file.adoc cat-file: add mailmap subcommand to --batch-command 2026-04-15 20:42:08 -07:00
git-check-attr.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-check-ignore.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-check-mailmap.adoc
git-check-ref-format.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-checkout-index.adoc
git-checkout.adoc checkout -m: autostash when switching branches 2026-04-29 21:46:03 +09:00
git-cherry-pick.adoc
git-cherry.adoc
git-citool.adoc
git-clean.adoc
git-clone.adoc Merge branch 'cc/lop-filter-auto' 2026-02-25 11:54:17 -08:00
git-column.adoc doc: column: fix blank lines around block delimiters 2025-06-01 17:20:16 -07:00
git-commit-graph.adoc doc: add caveat about turning off commit-graph 2026-05-08 10:22:33 +09:00
git-commit-tree.adoc
git-commit.adoc doc: commit: link to git-status(1) on all format options 2025-11-14 08:56:35 -08:00
git-config.adoc Merge branch 'gi/doc-boolean-config-typofix' 2026-03-27 11:00:02 -07:00
git-count-objects.adoc Merge branch 'ds/doc-count-objects-fix' into maint-2.51 2025-10-14 13:40:54 -07:00
git-credential-cache--daemon.adoc
git-credential-cache.adoc
git-credential-store.adoc
git-credential.adoc
git-cvsexportcommit.adoc
git-cvsimport.adoc
git-cvsserver.adoc
git-daemon.adoc git-daemon doc: update mark-up of synopsis option descriptions 2025-05-12 09:25:26 -07:00
git-describe.adoc doc: convert git-describe manual page to synopsis style 2026-04-06 09:38:19 -07:00
git-diagnose.adoc
git-diff-files.adoc
git-diff-index.adoc
git-diff-pairs.adoc
git-diff-tree.adoc
git-diff.adoc diff --no-index: support limiting by pathspec 2025-05-22 14:20:11 -07:00
git-difftool.adoc doc: convert git-difftool manual page to synopsis style 2026-04-06 09:38:18 -07:00
git-fast-export.adoc fast-(import|export): improve on commit signature output format 2025-07-09 16:08:29 -07:00
git-fast-import.adoc fast-import: add 'strip-if-invalid' mode to '--signed-tags=<mode>' 2026-03-26 12:42:57 -07:00
git-fetch-pack.adoc
git-fetch.adoc doc: convert git fetch to synopsis style 2025-11-19 15:00:37 -08:00
git-filter-branch.adoc
git-fmt-merge-msg.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-for-each-ref.adoc Merge branch 'ja/doc-lint-sections-and-synopsis' 2025-08-25 14:22:02 -07:00
git-for-each-repo.adoc
git-format-patch.adoc Merge branch 'mf/format-patch-cover-letter-format' 2026-04-03 13:01:08 -07:00
git-format-rev.adoc format-rev: introduce builtin for on-demand pretty formatting 2026-05-12 09:09:51 +09:00
git-fsck-objects.adoc
git-fsck.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-fsmonitor--daemon.adoc fsmonitor: implement filesystem change listener for Linux 2026-04-15 08:44:33 -07:00
git-gc.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-get-tar-commit-id.adoc
git-grep.adoc doc: convert git-grep synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-gui.adoc
git-hash-object.adoc
git-help.adoc
git-history.adoc builtin/history: introduce "fixup" subcommand 2026-04-27 22:20:57 +09:00
git-hook.adoc doc: hook: don’t self-link via config include 2026-05-22 09:36:20 +09:00
git-http-backend.adoc
git-http-fetch.adoc doc: check for absence of multiple terms in each entry of desc list 2025-08-11 14:16:04 -07:00
git-http-push.adoc
git-imap-send.adoc doc: convert git-imap-send synopsis and options to new style 2026-05-25 20:05:45 +09:00
git-index-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-init-db.adoc
git-init.adoc breaking-changes: switch default branch to main 2025-09-10 13:34:58 -07:00
git-instaweb.adoc
git-interpret-trailers.adoc doc: interpret-trailers: normalize and fill out options 2026-03-16 15:04:37 -07:00
git-last-modified.adoc last-modified: change default max-depth to 0 2026-01-20 14:13:04 -08:00
git-log.adoc doc: log: use the same delimiter in description list 2026-04-28 09:46:26 +09:00
git-ls-files.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
git-ls-remote.adoc
git-ls-tree.adoc
git-mailinfo.adoc
git-mailsplit.adoc
git-maintenance.adoc maintenance: add 'is-needed' subcommand 2025-11-10 09:28:48 -08:00
git-merge-base.adoc
git-merge-file.adoc merge-file: honor merge.conflictStyle outside of a repository 2026-02-07 17:04:26 -08:00
git-merge-index.adoc
git-merge-one-file.adoc
git-merge-tree.adoc Merge branch 'en/doc-merge-tree-describe-merge-base' 2025-10-10 12:51:46 -07:00
git-merge.adoc Merge branch 'ts/merge-orig-head-doc-fix' 2025-07-14 11:19:28 -07:00
git-mergetool--lib.adoc
git-mergetool.adoc doc: convert git-mergetool manpage to new synopsis style 2025-05-27 07:51:01 -07:00
git-mktag.adoc
git-mktree.adoc
git-multi-pack-index.adoc midx: support custom `--base` for incremental MIDX writes 2026-05-20 11:31:13 +09:00
git-mv.adoc doc: convert git-mv to new documentation format 2025-04-14 14:43:52 -07:00
git-name-rev.adoc
git-notes.adoc doc: notes: use stuck form throughout 2025-05-27 15:31:08 -07:00
git-p4.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
git-pack-objects.adoc path-walk: support `combine` filter 2026-05-24 18:41:07 +09:00
git-pack-redundant.adoc
git-pack-refs.adoc doc: pack-refs: factor out common options 2025-09-19 10:02:56 -07:00
git-patch-id.adoc doc: patch-id: see also git-cherry(1) 2026-02-17 10:49:51 -08:00
git-prune-packed.adoc
git-prune.adoc
git-pull.adoc Merge branch 'je/doc-pull' 2025-12-14 17:04:37 +09:00
git-push.adoc push: support pushing to a remote group 2026-05-04 10:11:17 +09:00
git-quiltimport.adoc
git-range-diff.adoc Merge branch 'sp/doc-range-diff-takes-notes' 2026-05-31 10:00:39 +09:00
git-read-tree.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-rebase.adoc rebase: support --trailer 2026-03-06 13:02:20 -08:00
git-receive-pack.adoc builtin/receive-pack: add option to skip connectivity check 2025-05-20 11:43:36 -07:00
git-reflog.adoc builtin/reflog: implement subcommand to write new entries 2025-08-06 07:36:30 -07:00
git-refs.adoc Merge branch 'ms/refs-optimize' 2025-10-02 12:26:12 -07:00
git-remote-ext.adoc
git-remote-fd.adoc
git-remote-helpers.adoco
git-remote.adoc doc: convert git-remote to synopsis style 2025-12-21 11:33:10 +09:00
git-repack.adoc repack: allow `--write-midx=incremental` without `--geometric` 2026-05-20 11:31:14 +09:00
git-replace.adoc doc: add caveat about turning off commit-graph 2026-05-08 10:22:33 +09:00
git-replay.adoc replay: allow to specify a ref with option --ref 2026-04-01 21:34:25 -07:00
git-repo.adoc Merge branch 'jt/repo-structure-extrema' 2026-03-16 10:48:14 -07:00
git-request-pull.adoc
git-rerere.adoc doc: fix singular/plural mismatch in git-rerere 2026-04-16 21:22:01 -07:00
git-reset.adoc doc: git-reset: clarify `git reset <pathspec>` 2026-01-06 08:10:14 +09:00
git-restore.adoc Merge branch 'kh/doc-restore-double-underscores-fix' 2026-05-19 09:57:45 +09:00
git-rev-list.adoc
git-rev-parse.adoc Merge branch 'bc/sha1-256-interop-01' 2025-10-22 11:38:58 -07:00
git-revert.adoc
git-rm.adoc doc: convert git-rm to new documentation format 2025-04-14 14:43:52 -07:00
git-send-email.adoc Merge branch 'dt/send-email-client-cert' 2026-03-12 10:56:05 -07:00
git-send-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-sh-i18n--envsubst.adoc
git-sh-i18n.adoc
git-sh-setup.adoc
git-shell.adoc
git-shortlog.adoc doc: convert git-shortlog manual page to synopsis style 2026-04-06 09:38:19 -07:00
git-show-branch.adoc
git-show-index.adoc
git-show-ref.adoc
git-show.adoc doc: convert git-show to synopsis style 2026-02-05 21:14:05 -08:00
git-sparse-checkout.adoc Merge branch 'ds/sparse-checkout-clean' 2025-10-28 10:29:09 -07:00
git-stage.adoc doc: convert git stage to use synopsis block 2025-12-21 11:33:10 +09:00
git-stash.adoc stash: add --label-ours, --label-theirs, --label-base for apply 2026-04-29 21:46:02 +09:00
git-status.adoc doc: convert git-status tables to AsciiDoc format 2025-12-21 11:33:10 +09:00
git-stripspace.adoc doc: stripspace: mention where the default comes from 2025-05-27 15:31:05 -07:00
git-submodule.adoc doc: convert git-submodule to synopsis style 2026-02-05 21:14:05 -08:00
git-svn.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
git-switch.adoc checkout -m: autostash when switching branches 2026-04-29 21:46:03 +09:00
git-symbolic-ref.adoc
git-tag.adoc Merge branch 'cc/fast-import-strip-signed-tags' 2025-10-28 10:29:09 -07:00
git-tools.adoc
git-unpack-file.adoc
git-unpack-objects.adoc
git-update-index.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-update-ref.adoc Merge branch 'sb/doc-update-ref-markup-fix' 2026-01-23 13:34:35 -08:00
git-update-server-info.adoc
git-upload-archive.adoc
git-upload-pack.adoc doc: check for absence of the form --[no-]parameter 2025-08-11 14:16:04 -07:00
git-url-parse.adoc doc: describe the url-parse builtin 2026-05-06 09:48:29 +09:00
git-var.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00
git-verify-commit.adoc git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-12 09:25:27 -07:00
git-verify-pack.adoc git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-12 09:25:27 -07:00
git-verify-tag.adoc git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-12 09:25:27 -07:00
git-version.adoc help: include unsafe SHA-1 build info in version 2025-04-07 14:39:27 -07:00
git-web--browse.adoc
git-whatchanged.adoc whatchanged: remove not-even-shorter clause 2025-09-17 13:47:24 -07:00
git-worktree.adoc Merge branch 'sb/doc-worktree-prune-expire-improvement' 2026-02-09 12:09:10 -08:00
git-write-tree.adoc git-{var,write-tree} docs: update mark-up of synopsis option descriptions 2025-05-12 09:25:26 -07:00
git.adoc Merge branch 'os/doc-git-custom-commands' 2026-03-16 10:48:14 -07:00
gitattributes.adoc userdiff: extend Scheme support to cover other Lisp dialects 2026-04-15 08:43:33 -07:00
gitcli.adoc doc: clarify command equivalence comment 2025-11-04 09:25:51 -08:00
gitcore-tutorial.adoc
gitcredentials.adoc Merge branch 'mh/doc-credential-url-prefix' into maint-2.51 2025-10-15 10:29:35 -07:00
gitcvs-migration.adoc doc: gitcvs-migration: rephrase “man page” 2026-04-06 09:57:07 -07:00
gitdatamodel.adoc doc: remove stray text in Git data model 2025-12-03 00:17:07 -08:00
gitdiffcore.adoc
giteveryday.adoc
gitfaq.adoc Merge branch 'bc/doc-stash-import-export' 2026-01-16 12:40:27 -08:00
gitformat-bundle.adoc
gitformat-chunk.adoc
gitformat-commit-graph.adoc
gitformat-index.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
gitformat-loose.adoc rust: add a new binary object map format 2026-02-07 17:41:03 -08:00
gitformat-pack.adoc midx: do not require packs to be sorted in lexicographic order 2026-02-24 11:16:33 -08:00
gitformat-signature.adoc
gitglossary.adoc
githooks.adoc refs: add 'preparing' phase to the reference-transaction hook 2026-03-16 21:00:44 -07:00
gitignore.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
gitk.adoc Merge branch 'js/doc-gitk-history' into maint-2.51 2025-10-14 13:40:53 -07:00
gitmailmap.adoc
gitmodules.adoc doc: fix grammar errors in submodule description 2026-04-16 21:22:01 -07:00
gitnamespaces.adoc
gitpacking.adoc Documentation: fix broken `sampleRate` in gitpacking(7) 2026-05-12 10:36:18 +09:00
gitprotocol-capabilities.adoc
gitprotocol-common.adoc
gitprotocol-http.adoc doc: clarify server behavior for invalid 'want' lines in HTTP protocol 2025-11-06 09:45:38 -08:00
gitprotocol-pack.adoc doc: gitprotocol-pack: normalize italic formatting 2026-03-02 21:35:05 -08:00
gitprotocol-v2.adoc Merge branch 'cc/promisor-auto-config-url' 2026-05-11 10:05:53 +09:00
gitremote-helpers.adoc Merge branch 'bs/remote-helpers-doc-markup-fix' 2025-07-14 11:19:22 -07:00
gitrepository-layout.adoc
gitrevisions.adoc
gitsubmodules.adoc doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
gittutorial-2.adoc
gittutorial.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00
gitweb.adoc
gitweb.conf.adoc doc: test linkgit macros for well-formedness 2025-08-11 14:16:03 -07:00
gitworkflows.adoc
glossary-content.adoc gitglossary: fix indentation of sub-lists 2026-04-13 11:50:06 -07:00
i18n.adoc
install-doc-quick.sh
install-webdoc.sh
line-range-format.adoc doc: git-log: convert line range format to new doc format 2025-07-07 13:45:00 -07:00
line-range-options.adoc line-log: allow non-patch diff formats with -L 2026-05-29 14:06:21 +09:00
lint-delimited-sections.perl doc: check well-formedness of delimited sections 2025-08-11 14:16:03 -07:00
lint-documentation-style.perl doc lint: check that synopsis manpages have synopsis inlines 2025-08-11 14:16:04 -07:00
lint-fsck-msgids.perl
lint-gitlink.perl lint-gitlink: preemptively ignore all /ifn?def|endif/ macros 2026-01-21 08:26:00 -08:00
lint-man-end-blurb.perl
lint-man-section-order.perl
lint-manpages.sh
manpage-bold-literal.xsl
manpage-normal.xsl
manpage.xsl
merge-options.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
merge-strategies.adoc doc: convert merge strategies to synopsis format 2025-05-27 07:51:00 -07:00
meson.build Merge branch 'mm/git-url-parse' 2026-05-21 12:06:48 +09:00
object-format-disclaimer.adoc
pack-refs-options.adoc doc: pack-refs: factor out common options 2025-09-19 10:02:56 -07:00
pretty-formats.adoc docs/pretty-formats: add %(count) and %(total) 2026-03-23 13:06:58 -07:00
pretty-options.adoc doc: do not break sentences into "lego" pieces 2025-10-05 16:10:53 -07:00
pull-fetch-param.adoc doc: pull-fetch-param typofix 2025-11-24 10:55:48 -08:00
ref-reachability-filters.adoc
ref-storage-format.adoc docs: correct information about reftable 2026-04-08 07:18:56 -07:00
rerere-options.adoc doc: rerere-options.adoc: link to git-rerere(1) 2026-02-10 12:27:07 -08:00
rev-list-description.adoc doc: git-log convert rev-list-description to new doc format 2025-07-07 13:45:00 -07:00
rev-list-options.adoc Merge branch 'ta/approxidate-noon-fix' 2026-06-02 16:15:29 +09:00
revisions.adoc
scalar.adoc scalar: document config settings 2025-12-16 09:42:44 +09:00
sequencer.adoc
signoff-option.adoc signoff-option: linkify the reference to gitfaq 2025-12-19 21:51:01 +09:00
texi.xsl
trace2-target-values.adoc
transfer-data-leaks.adoc
urls-remotes.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
urls.adoc
user-manual.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00