1 files changed, 414 insertions, 0 deletions
diff --git a/man5/gitformat-signature.5 b/man5/gitformat-signature.5
new file mode 100644
index 000000000..142b7ae4f
--- /dev/null
+++ b/man5/gitformat-signature.5
@@ -0,0 +1,414 @@
+'\" t
+.\"     Title: gitformat-signature
+.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 08/18/2022
+.\"    Manual: Git Manual
+.\"    Source: Git 2.37.2.382.g795ea8776b
+.\"  Language: English
+.\"
+.TH "GITFORMAT\-SIGNATURE" "5" "08/18/2022" "Git 2\&.37\&.2\&.382\&.g795ea8" "Git Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+gitformat-signature \- Git cryptographic signature formats
+.SH "SYNOPSIS"
+.sp
+.nf
+<[tag|commit] object header(s)>
+<over\-the\-wire protocol>
+.fi
+.sp
+.SH "DESCRIPTION"
+.sp
+Git uses cryptographic signatures in various places, currently objects (tags, commits, mergetags) and transactions (pushes)\&. In every case, the command which is about to create an object or transaction determines a payload from that, calls gpg to obtain a detached signature for the payload (\fBgpg \-bsa\fR) and embeds the signature into the object or transaction\&.
+.sp
+Signatures always begin with \fB\-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-\fR and end with \fB\-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-\fR, unless gpg is told to produce RFC1991 signatures which use \fBMESSAGE\fR instead of \fBSIGNATURE\fR\&.
+.sp
+Signatures sometimes appear as a part of the normal payload (e\&.g\&. a signed tag has the signature block appended after the payload that the signature applies to), and sometimes appear in the value of an object header (e\&.g\&. a merge commit that merged a signed tag would have the entire tag contents on its "mergetag" header)\&. In the case of the latter, the usual multi\-line formatting rule for object headers applies\&. I\&.e\&. the second and subsequent lines are prefixed with a SP to signal that the line is continued from the previous line\&.
+.sp
+This is even true for an originally empty line\&. In the following examples, the end of line that ends with a whitespace letter is highlighted with a \fB$\fR sign; if you are trying to recreate these example by hand, do not cut and paste them\-\-\-they are there primarily to highlight extra whitespace at the end of some lines\&.
+.sp
+The signed payload and the way the signature is embedded depends on the type of the object resp\&. transaction\&.
+.SH "TAG SIGNATURES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+created by:
+\fBgit tag \-s\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+payload: annotated tag object
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+embedding: append the signature to the unsigned tag object
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+example: tag
+\fBsignedtag\fR
+with subject
+\fBsigned tag\fR
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example\&.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
+\-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
+Version: GnuPG v1
+
+iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+=jpXa
+\-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+verify with:
+\fBgit verify\-tag [\-v]\fR
+or
+\fBgit tag \-v\fR
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example\&.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner\&.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example\&.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "COMMIT SIGNATURES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+created by:
+\fBgit commit \-S\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+payload: commit object
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+embedding: header entry
+\fBgpgsig\fR
+(content is preceded by a space)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+example: commit with subject
+\fBsigned commit\fR
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example\&.com> 1465981137 +0000
+committer C O Mitter <committer@example\&.com> 1465981137 +0000
+gpgsig \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
+ Version: GnuPG v1
+ $
+ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
+ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
+ DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
+ zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
+ HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
+ EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
+ =jKHM
+ \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
+
+signed commit
+
+signed commit message body
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+verify with:
+\fBgit verify\-commit [\-v]\fR
+(or
+\fBgit show \-\-show\-signature\fR)
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example\&.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner\&.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example\&.com> 1465981137 +0000
+committer C O Mitter <committer@example\&.com> 1465981137 +0000
+
+signed commit
+
+signed commit message body
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "MERGETAG SIGNATURES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+created by:
+\fBgit merge\fR
+on signed tag
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+payload/embedding: the whole signed tag object is embedded into the (merge) commit object as header entry
+\fBmergetag\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+example: merge of the signed tag
+\fBsignedtag\fR
+as above
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+tree c7b1cff039a93f3600a1d18b82d26688668c7dea
+parent c33429be94b5f2d3ee9b0adad223f877f174b05d
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example\&.com> 1465982009 +0000
+committer C O Mitter <committer@example\&.com> 1465982009 +0000
+mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
+ type commit
+ tag signedtag
+ tagger C O Mitter <committer@example\&.com> 1465981006 +0000
+ $
+ signed tag
+ $
+ signed tag message body
+ \-\-\-\-\-BEGIN PGP SIGNATURE\-\-\-\-\-
+ Version: GnuPG v1
+ $
+ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+ rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+ 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+ q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+ rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+ lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+ =jpXa
+ \-\-\-\-\-END PGP SIGNATURE\-\-\-\-\-
+
+Merge tag \(aqsignedtag\(aq into downstream
+
+signed tag
+
+signed tag message body
+
+# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+# gpg: Good signature from "Eris Discordia <discord@example\&.net>"
+# gpg: WARNING: This key is not certified with a trusted signature!
+# gpg:          There is no indication that the signature belongs to the owner\&.
+# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+verify with: verification is embedded in merge commit message by default, alternatively with
+\fBgit show \-\-show\-signature\fR:
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
+merged tag \(aqsignedtag\(aq
+gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example\&.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner\&.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+Merge: c33429b 04b8717
+Author: A U Thor <author@example\&.com>
+Date:   Wed Jun 15 09:13:29 2016 +0000
+
+    Merge tag \(aqsignedtag\(aq into downstream
+
+    signed tag
+
+    signed tag message body
+
+    # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+    # gpg: Good signature from "Eris Discordia <discord@example\&.net>"
+    # gpg: WARNING: This key is not certified with a trusted signature!
+    # gpg:          There is no indication that the signature belongs to the owner\&.
+    # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "GIT"
+.sp
+Part of the \fBgit\fR(1) suite