logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-interpret-trailers.1 (22320B)


  1. '\" t
  2. .\" Title: git-interpret-trailers
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-INTERPRET\-TRAILERS" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. git-interpret-trailers \- Add or parse structured information in commit messages
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit interpret\-trailers\fR [\-\-in\-place] [\-\-trim\-empty]
  36. [(\-\-trailer (<key>|<key\-alias>)[(=|:)<value>])\&...\:]
  37. [\-\-parse] [<file>\&...\:]
  38. .fi
  39. .SH "DESCRIPTION"
  40. .sp
  41. Add or parse \fItrailer\fR lines that look similar to RFC 822 e\-mail headers, at the end of the otherwise free\-form part of a commit message\&. For example, in the following commit message
  42. .sp
  43. .if n \{\
  44. .RS 4
  45. .\}
  46. .nf
  47. subject
  48. Lorem ipsum dolor sit amet, consectetur adipiscing elit\&.
  49. Signed\-off\-by: Alice <alice@example\&.com>
  50. Signed\-off\-by: Bob <bob@example\&.com>
  51. .fi
  52. .if n \{\
  53. .RE
  54. .\}
  55. .sp
  56. the last two lines starting with "Signed\-off\-by" are trailers\&.
  57. .sp
  58. This command reads commit messages from either the <file> arguments or the standard input if no <file> is specified\&. If \fB\-\-parse\fR is specified, the output consists of the parsed trailers coming from the input, without influencing them with any command line options or configuration variables\&.
  59. .sp
  60. Otherwise, this command applies \fBtrailer\&.\fR* configuration variables (which could potentially add new trailers, as well as reposition them), as well as any command line arguments that can override configuration variables (such as \fB\-\-trailer=\&.\&.\fR\&. which could also add new trailers), to each input file\&. The result is emitted on the standard output\&.
  61. .sp
  62. This command can also operate on the output of \fBgit-format-patch\fR(1), which is more elaborate than a plain commit message\&. Namely, such output includes a commit message (as above), a "\-\-\-" divider line, and a patch part\&. For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless \fB\-\-no\-divider\fR is specified\&.
  63. .sp
  64. Some configuration variables control the way the \fB\-\-trailer\fR arguments are applied to each input and the way any existing trailer in the input is changed\&. They also make it possible to automatically add some trailers\&.
  65. .sp
  66. By default, a \fI<key>=<value>\fR or \fI<key>:<value>\fR argument given using \fB\-\-trailer\fR will be appended after the existing trailers only if the last trailer has a different (<key>, <value>) pair (or if there is no existing trailer)\&. The <key> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <key> and <value> will appear in the output like this:
  67. .sp
  68. .if n \{\
  69. .RS 4
  70. .\}
  71. .nf
  72. key: value
  73. .fi
  74. .if n \{\
  75. .RE
  76. .\}
  77. .sp
  78. This means that the trimmed <key> and <value> will be separated by \*(Aq: \*(Aq (one colon followed by one space)\&.
  79. .sp
  80. For convenience, a <key\-alias> can be configured to make using \fB\-\-trailer\fR shorter to type on the command line\&. This can be configured using the \fItrailer\&.<key\-alias>\&.key\fR configuration variable\&. The <keyAlias> must be a prefix of the full <key> string, although case sensitivity does not matter\&. For example, if you have
  81. .sp
  82. .if n \{\
  83. .RS 4
  84. .\}
  85. .nf
  86. trailer\&.sign\&.key "Signed\-off\-by: "
  87. .fi
  88. .if n \{\
  89. .RE
  90. .\}
  91. .sp
  92. in your configuration, you only need to specify \fB\-\-trailer=\fR"sign: \fBfoo\fR" on the command line instead of \fB\-\-trailer=\fR"Signed\-off\-by: \fBfoo\fR"\&.
  93. .sp
  94. By default the new trailer will appear at the end of all the existing trailers\&. If there is no existing trailer, the new trailer will appear at the end of the input\&. A blank line will be added before the new trailer if there isn\(cqt one already\&.
  95. .sp
  96. Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git\-generated or user\-configured trailer and consists of at least 25% trailers\&. The group must be preceded by one or more empty (or whitespace\-only) lines\&. The group must either be at the end of the input or be the last non\-whitespace lines before a line that starts with \fI\-\-\-\fR (followed by a space or the end of the line)\&.
  97. .sp
  98. When reading trailers, there can be no whitespace before or inside the <key>, but any number of regular space and tab characters are allowed between the <key> and the separator\&. There can be whitespaces before, inside or after the <value>\&. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822\&. Example:
  99. .sp
  100. .if n \{\
  101. .RS 4
  102. .\}
  103. .nf
  104. key: This is a very long value, with spaces and
  105. newlines in it\&.
  106. .fi
  107. .if n \{\
  108. .RE
  109. .\}
  110. .sp
  111. Note that trailers do not follow (nor are they intended to follow) many of the rules for RFC 822 headers\&. For example they do not follow the encoding rule\&.
  112. .SH "OPTIONS"
  113. .PP
  114. \-\-in\-place
  115. .RS 4
  116. Edit the files in place\&.
  117. .RE
  118. .PP
  119. \-\-trim\-empty
  120. .RS 4
  121. If the <value> part of any trailer contains only whitespace, the whole trailer will be removed from the output\&. This applies to existing trailers as well as new trailers\&.
  122. .RE
  123. .PP
  124. \-\-trailer <key>[(=|:)<value>]
  125. .RS 4
  126. Specify a (<key>, <value>) pair that should be applied as a trailer to the inputs\&. See the description of this command\&.
  127. .RE
  128. .PP
  129. \-\-where <placement>, \-\-no\-where
  130. .RS 4
  131. Specify where all new trailers will be added\&. A setting provided with
  132. \fI\-\-where\fR
  133. overrides the
  134. \fBtrailer\&.where\fR
  135. and any applicable
  136. \fBtrailer\&.\fR\fI<keyAlias>\fR\fB\&.where\fR
  137. configuration variables and applies to all
  138. \fI\-\-trailer\fR
  139. options until the next occurrence of
  140. \fI\-\-where\fR
  141. or
  142. \fI\-\-no\-where\fR\&. Upon encountering
  143. \fI\-\-no\-where\fR, clear the effect of any previous use of
  144. \fI\-\-where\fR, such that the relevant configuration variables are no longer overridden\&. Possible placements are
  145. \fBafter\fR,
  146. \fBbefore\fR,
  147. \fBend\fR
  148. or
  149. \fBstart\fR\&.
  150. .RE
  151. .PP
  152. \-\-if\-exists <action>, \-\-no\-if\-exists
  153. .RS 4
  154. Specify what action will be performed when there is already at least one trailer with the same <key> in the input\&. A setting provided with
  155. \fI\-\-if\-exists\fR
  156. overrides the
  157. \fBtrailer\&.ifExists\fR
  158. and any applicable
  159. \fBtrailer\&.\fR\fI<keyAlias>\fR\fB\&.ifExists\fR
  160. configuration variables and applies to all
  161. \fI\-\-trailer\fR
  162. options until the next occurrence of
  163. \fI\-\-if\-exists\fR
  164. or
  165. \fI\-\-no\-if\-exists\fR\&. Upon encountering \*(Aq\-\-no\-if\-exists, clear the effect of any previous use of \*(Aq\-\-if\-exists, such that the relevant configuration variables are no longer overridden\&. Possible actions are
  166. \fBaddIfDifferent\fR,
  167. \fBaddIfDifferentNeighbor\fR,
  168. \fBadd\fR,
  169. \fBreplace\fR
  170. and
  171. \fBdoNothing\fR\&.
  172. .RE
  173. .PP
  174. \-\-if\-missing <action>, \-\-no\-if\-missing
  175. .RS 4
  176. Specify what action will be performed when there is no other trailer with the same <key> in the input\&. A setting provided with
  177. \fI\-\-if\-missing\fR
  178. overrides the
  179. \fBtrailer\&.ifMissing\fR
  180. and any applicable
  181. \fBtrailer\&.\fR\fI<keyAlias>\fR\fB\&.ifMissing\fR
  182. configuration variables and applies to all
  183. \fI\-\-trailer\fR
  184. options until the next occurrence of
  185. \fI\-\-if\-missing\fR
  186. or
  187. \fI\-\-no\-if\-missing\fR\&. Upon encountering \*(Aq\-\-no\-if\-missing, clear the effect of any previous use of \*(Aq\-\-if\-missing, such that the relevant configuration variables are no longer overridden\&. Possible actions are
  188. \fBdoNothing\fR
  189. or
  190. \fBadd\fR\&.
  191. .RE
  192. .PP
  193. \-\-only\-trailers
  194. .RS 4
  195. Output only the trailers, not any other parts of the input\&.
  196. .RE
  197. .PP
  198. \-\-only\-input
  199. .RS 4
  200. Output only trailers that exist in the input; do not add any from the command\-line or by applying
  201. \fBtrailer\&.\fR* configuration variables\&.
  202. .RE
  203. .PP
  204. \-\-unfold
  205. .RS 4
  206. If a trailer has a value that runs over multiple lines (aka "folded"), reformat the value into a single line\&.
  207. .RE
  208. .PP
  209. \-\-parse
  210. .RS 4
  211. A convenience alias for
  212. \fB\-\-only\-trailers\fR
  213. \fB\-\-only\-input\fR
  214. \fB\-\-unfold\fR\&. This makes it easier to only see the trailers coming from the input without influencing them with any command line options or configuration variables, while also making the output machine\-friendly with \-\-unfold\&.
  215. .RE
  216. .PP
  217. \-\-no\-divider
  218. .RS 4
  219. Do not treat
  220. \fB\-\-\-\fR
  221. as the end of the commit message\&. Use this when you know your input contains just the commit message itself (and not an email or the output of
  222. \fBgit\fR
  223. \fBformat\-patch\fR)\&.
  224. .RE
  225. .SH "CONFIGURATION VARIABLES"
  226. .sp
  227. Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
  228. .PP
  229. trailer\&.separators
  230. .RS 4
  231. This option tells which characters are recognized as trailer separators\&. By default only
  232. \fI:\fR
  233. is recognized as a trailer separator, except that
  234. \fI=\fR
  235. is always accepted on the command line for compatibility with other git commands\&.
  236. .sp
  237. The first character given by this option will be the default character used when another separator is not specified in the config for this trailer\&.
  238. .sp
  239. For example, if the value for this option is "%=$", then only lines using the format
  240. \fI<key><sep><value>\fR
  241. with <sep> containing
  242. \fI%\fR,
  243. \fI=\fR
  244. or
  245. \fI$\fR
  246. and then spaces will be considered trailers\&. And
  247. \fI%\fR
  248. will be the default separator used, so by default trailers will appear like:
  249. \fI<key>% <value>\fR
  250. (one percent sign and one space will appear between the key and the value)\&.
  251. .RE
  252. .PP
  253. trailer\&.where
  254. .RS 4
  255. This option tells where a new trailer will be added\&.
  256. .sp
  257. This can be
  258. \fBend\fR, which is the default,
  259. \fBstart\fR,
  260. \fBafter\fR
  261. or
  262. \fBbefore\fR\&.
  263. .sp
  264. If it is
  265. \fBend\fR, then each new trailer will appear at the end of the existing trailers\&.
  266. .sp
  267. If it is
  268. \fBstart\fR, then each new trailer will appear at the start, instead of the end, of the existing trailers\&.
  269. .sp
  270. If it is
  271. \fBafter\fR, then each new trailer will appear just after the last trailer with the same <key>\&.
  272. .sp
  273. If it is
  274. \fBbefore\fR, then each new trailer will appear just before the first trailer with the same <key>\&.
  275. .RE
  276. .PP
  277. trailer\&.ifexists
  278. .RS 4
  279. This option makes it possible to choose what action will be performed when there is already at least one trailer with the same <key> in the input\&.
  280. .sp
  281. The valid values for this option are:
  282. \fBaddIfDifferentNeighbor\fR
  283. (this is the default),
  284. \fBaddIfDifferent\fR,
  285. \fBadd\fR,
  286. \fBreplace\fR
  287. or
  288. \fBdoNothing\fR\&.
  289. .sp
  290. With
  291. \fBaddIfDifferentNeighbor\fR, a new trailer will be added only if no trailer with the same (<key>, <value>) pair is above or below the line where the new trailer will be added\&.
  292. .sp
  293. With
  294. \fBaddIfDifferent\fR, a new trailer will be added only if no trailer with the same (<key>, <value>) pair is already in the input\&.
  295. .sp
  296. With
  297. \fBadd\fR, a new trailer will be added, even if some trailers with the same (<key>, <value>) pair are already in the input\&.
  298. .sp
  299. With
  300. \fBreplace\fR, an existing trailer with the same <key> will be deleted and the new trailer will be added\&. The deleted trailer will be the closest one (with the same <key>) to the place where the new one will be added\&.
  301. .sp
  302. With
  303. \fBdoNothing\fR, nothing will be done; that is no new trailer will be added if there is already one with the same <key> in the input\&.
  304. .RE
  305. .PP
  306. trailer\&.ifmissing
  307. .RS 4
  308. This option makes it possible to choose what action will be performed when there is not yet any trailer with the same <key> in the input\&.
  309. .sp
  310. The valid values for this option are:
  311. \fBadd\fR
  312. (this is the default) and
  313. \fBdoNothing\fR\&.
  314. .sp
  315. With
  316. \fBadd\fR, a new trailer will be added\&.
  317. .sp
  318. With
  319. \fBdoNothing\fR, nothing will be done\&.
  320. .RE
  321. .PP
  322. trailer\&.<keyAlias>\&.key
  323. .RS 4
  324. Defines a <keyAlias> for the <key>\&. The <keyAlias> must be a prefix (case does not matter) of the <key>\&. For example, in
  325. \fBgit\fR
  326. \fBconfig\fR
  327. \fBtrailer\&.ack\&.key\fR
  328. "Acked\-by" the "Acked\-by" is the <key> and the "ack" is the <keyAlias>\&. This configuration allows the shorter
  329. \fB\-\-trailer\fR
  330. "ack:\fB\&.\&.\&.\fR" invocation on the command line using the "ack" <keyAlias> instead of the longer
  331. \fB\-\-trailer\fR
  332. "Acked\-by:\fB\&.\&.\&.\fR"\&.
  333. .sp
  334. At the end of the <key>, a separator can appear and then some space characters\&. By default the only valid separator is
  335. \fI:\fR, but this can be changed using the
  336. \fBtrailer\&.separators\fR
  337. config variable\&.
  338. .sp
  339. If there is a separator in the key, then it overrides the default separator when adding the trailer\&.
  340. .RE
  341. .PP
  342. trailer\&.<keyAlias>\&.where
  343. .RS 4
  344. This option takes the same values as the
  345. \fItrailer\&.where\fR
  346. configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
  347. .RE
  348. .PP
  349. trailer\&.<keyAlias>\&.ifexists
  350. .RS 4
  351. This option takes the same values as the
  352. \fItrailer\&.ifexists\fR
  353. configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
  354. .RE
  355. .PP
  356. trailer\&.<keyAlias>\&.ifmissing
  357. .RS 4
  358. This option takes the same values as the
  359. \fItrailer\&.ifmissing\fR
  360. configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
  361. .RE
  362. .PP
  363. trailer\&.<keyAlias>\&.command
  364. .RS 4
  365. Deprecated in favor of
  366. \fItrailer\&.<keyAlias>\&.cmd\fR\&. This option behaves in the same way as
  367. \fItrailer\&.<keyAlias>\&.cmd\fR, except that it doesn\(cqt pass anything as argument to the specified command\&. Instead the first occurrence of substring $ARG is replaced by the <value> that would be passed as argument\&.
  368. .sp
  369. Note that $ARG in the user\(cqs command is only replaced once and that the original way of replacing $ARG is not safe\&.
  370. .sp
  371. When both
  372. \fItrailer\&.<keyAlias>\&.cmd\fR
  373. and
  374. \fItrailer\&.<keyAlias>\&.command\fR
  375. are given for the same <keyAlias>,
  376. \fItrailer\&.<keyAlias>\&.cmd\fR
  377. is used and
  378. \fItrailer\&.<keyAlias>\&.command\fR
  379. is ignored\&.
  380. .RE
  381. .PP
  382. trailer\&.<keyAlias>\&.cmd
  383. .RS 4
  384. This option can be used to specify a shell command that will be called once to automatically add a trailer with the specified <keyAlias>, and then called each time a
  385. \fI\-\-trailer <keyAlias>=<value>\fR
  386. argument is specified to modify the <value> of the trailer that this option would produce\&.
  387. .sp
  388. When the specified command is first called to add a trailer with the specified <keyAlias>, the behavior is as if a special
  389. \fI\-\-trailer <keyAlias>=<value>\fR
  390. argument was added at the beginning of the "git interpret\-trailers" command, where <value> is taken to be the standard output of the command with any leading and trailing whitespace trimmed off\&.
  391. .sp
  392. If some
  393. \fI\-\-trailer <keyAlias>=<value>\fR
  394. arguments are also passed on the command line, the command is called again once for each of these arguments with the same <keyAlias>\&. And the <value> part of these arguments, if any, will be passed to the command as its first argument\&. This way the command can produce a <value> computed from the <value> passed in the
  395. \fI\-\-trailer <keyAlias>=<value>\fR
  396. argument\&.
  397. .RE
  398. .SH "EXAMPLES"
  399. .sp
  400. .RS 4
  401. .ie n \{\
  402. \h'-04'\(bu\h'+03'\c
  403. .\}
  404. .el \{\
  405. .sp -1
  406. .IP \(bu 2.3
  407. .\}
  408. Configure a
  409. \fIsign\fR
  410. trailer with a
  411. \fISigned\-off\-by\fR
  412. key, and then add two of these trailers to a commit message file:
  413. .sp
  414. .if n \{\
  415. .RS 4
  416. .\}
  417. .nf
  418. $ git config trailer\&.sign\&.key "Signed\-off\-by"
  419. $ cat msg\&.txt
  420. subject
  421. body text
  422. $ git interpret\-trailers \-\-trailer \*(Aqsign: Alice <alice@example\&.com>\*(Aq \-\-trailer \*(Aqsign: Bob <bob@example\&.com>\*(Aq <msg\&.txt
  423. subject
  424. body text
  425. Signed\-off\-by: Alice <alice@example\&.com>
  426. Signed\-off\-by: Bob <bob@example\&.com>
  427. .fi
  428. .if n \{\
  429. .RE
  430. .\}
  431. .RE
  432. .sp
  433. .RS 4
  434. .ie n \{\
  435. \h'-04'\(bu\h'+03'\c
  436. .\}
  437. .el \{\
  438. .sp -1
  439. .IP \(bu 2.3
  440. .\}
  441. Use the
  442. \fB\-\-in\-place\fR
  443. option to edit a commit message file in place:
  444. .sp
  445. .if n \{\
  446. .RS 4
  447. .\}
  448. .nf
  449. $ cat msg\&.txt
  450. subject
  451. body text
  452. Signed\-off\-by: Bob <bob@example\&.com>
  453. $ git interpret\-trailers \-\-trailer \*(AqAcked\-by: Alice <alice@example\&.com>\*(Aq \-\-in\-place msg\&.txt
  454. $ cat msg\&.txt
  455. subject
  456. body text
  457. Signed\-off\-by: Bob <bob@example\&.com>
  458. Acked\-by: Alice <alice@example\&.com>
  459. .fi
  460. .if n \{\
  461. .RE
  462. .\}
  463. .RE
  464. .sp
  465. .RS 4
  466. .ie n \{\
  467. \h'-04'\(bu\h'+03'\c
  468. .\}
  469. .el \{\
  470. .sp -1
  471. .IP \(bu 2.3
  472. .\}
  473. Extract the last commit as a patch, and add a
  474. \fICc\fR
  475. and a
  476. \fIReviewed\-by\fR
  477. trailer to it:
  478. .sp
  479. .if n \{\
  480. .RS 4
  481. .\}
  482. .nf
  483. $ git format\-patch \-1
  484. 0001\-foo\&.patch
  485. $ git interpret\-trailers \-\-trailer \*(AqCc: Alice <alice@example\&.com>\*(Aq \-\-trailer \*(AqReviewed\-by: Bob <bob@example\&.com>\*(Aq 0001\-foo\&.patch >0001\-bar\&.patch
  486. .fi
  487. .if n \{\
  488. .RE
  489. .\}
  490. .RE
  491. .sp
  492. .RS 4
  493. .ie n \{\
  494. \h'-04'\(bu\h'+03'\c
  495. .\}
  496. .el \{\
  497. .sp -1
  498. .IP \(bu 2.3
  499. .\}
  500. Configure a
  501. \fIsign\fR
  502. trailer with a command to automatically add a \*(AqSigned\-off\-by: \*(Aq with the author information only if there is no \*(AqSigned\-off\-by: \*(Aq already, and show how it works:
  503. .sp
  504. .if n \{\
  505. .RS 4
  506. .\}
  507. .nf
  508. $ cat msg1\&.txt
  509. subject
  510. body text
  511. $ git config trailer\&.sign\&.key "Signed\-off\-by: "
  512. $ git config trailer\&.sign\&.ifmissing add
  513. $ git config trailer\&.sign\&.ifexists doNothing
  514. $ git config trailer\&.sign\&.cmd \*(Aqecho "$(git config user\&.name) <$(git config user\&.email)>"\*(Aq
  515. $ git interpret\-trailers \-\-trailer sign <msg1\&.txt
  516. subject
  517. body text
  518. Signed\-off\-by: Bob <bob@example\&.com>
  519. $ cat msg2\&.txt
  520. subject
  521. body text
  522. Signed\-off\-by: Alice <alice@example\&.com>
  523. $ git interpret\-trailers \-\-trailer sign <msg2\&.txt
  524. subject
  525. body text
  526. Signed\-off\-by: Alice <alice@example\&.com>
  527. .fi
  528. .if n \{\
  529. .RE
  530. .\}
  531. .RE
  532. .sp
  533. .RS 4
  534. .ie n \{\
  535. \h'-04'\(bu\h'+03'\c
  536. .\}
  537. .el \{\
  538. .sp -1
  539. .IP \(bu 2.3
  540. .\}
  541. Configure a
  542. \fIfix\fR
  543. trailer with a key that contains a
  544. \fI#\fR
  545. and no space after this character, and show how it works:
  546. .sp
  547. .if n \{\
  548. .RS 4
  549. .\}
  550. .nf
  551. $ git config trailer\&.separators ":#"
  552. $ git config trailer\&.fix\&.key "Fix #"
  553. $ echo "subject" | git interpret\-trailers \-\-trailer fix=42
  554. subject
  555. Fix #42
  556. .fi
  557. .if n \{\
  558. .RE
  559. .\}
  560. .RE
  561. .sp
  562. .RS 4
  563. .ie n \{\
  564. \h'-04'\(bu\h'+03'\c
  565. .\}
  566. .el \{\
  567. .sp -1
  568. .IP \(bu 2.3
  569. .\}
  570. Configure a
  571. \fIhelp\fR
  572. trailer with a cmd use a script
  573. \fBglog\-find\-author\fR
  574. which search specified author identity from git log in git repository and show how it works:
  575. .sp
  576. .if n \{\
  577. .RS 4
  578. .\}
  579. .nf
  580. $ cat ~/bin/glog\-find\-author
  581. #!/bin/sh
  582. test \-n "$1" && git log \-\-author="$1" \-\-pretty="%an <%ae>" \-1 || true
  583. $ cat msg\&.txt
  584. subject
  585. body text
  586. $ git config trailer\&.help\&.key "Helped\-by: "
  587. $ git config trailer\&.help\&.ifExists "addIfDifferentNeighbor"
  588. $ git config trailer\&.help\&.cmd "~/bin/glog\-find\-author"
  589. $ git interpret\-trailers \-\-trailer="help:Junio" \-\-trailer="help:Couder" <msg\&.txt
  590. subject
  591. body text
  592. Helped\-by: Junio C Hamano <gitster@pobox\&.com>
  593. Helped\-by: Christian Couder <christian\&.couder@gmail\&.com>
  594. .fi
  595. .if n \{\
  596. .RE
  597. .\}
  598. .RE
  599. .sp
  600. .RS 4
  601. .ie n \{\
  602. \h'-04'\(bu\h'+03'\c
  603. .\}
  604. .el \{\
  605. .sp -1
  606. .IP \(bu 2.3
  607. .\}
  608. Configure a
  609. \fIref\fR
  610. trailer with a cmd use a script
  611. \fBglog\-grep\fR
  612. to grep last relevant commit from git log in the git repository and show how it works:
  613. .sp
  614. .if n \{\
  615. .RS 4
  616. .\}
  617. .nf
  618. $ cat ~/bin/glog\-grep
  619. #!/bin/sh
  620. test \-n "$1" && git log \-\-grep "$1" \-\-pretty=reference \-1 || true
  621. $ cat msg\&.txt
  622. subject
  623. body text
  624. $ git config trailer\&.ref\&.key "Reference\-to: "
  625. $ git config trailer\&.ref\&.ifExists "replace"
  626. $ git config trailer\&.ref\&.cmd "~/bin/glog\-grep"
  627. $ git interpret\-trailers \-\-trailer="ref:Add copyright notices\&." <msg\&.txt
  628. subject
  629. body text
  630. Reference\-to: 8bc9a0c769 (Add copyright notices\&., 2005\-04\-07)
  631. .fi
  632. .if n \{\
  633. .RE
  634. .\}
  635. .RE
  636. .sp
  637. .RS 4
  638. .ie n \{\
  639. \h'-04'\(bu\h'+03'\c
  640. .\}
  641. .el \{\
  642. .sp -1
  643. .IP \(bu 2.3
  644. .\}
  645. Configure a
  646. \fIsee\fR
  647. trailer with a command to show the subject of a commit that is related, and show how it works:
  648. .sp
  649. .if n \{\
  650. .RS 4
  651. .\}
  652. .nf
  653. $ cat msg\&.txt
  654. subject
  655. body text
  656. see: HEAD~2
  657. $ cat ~/bin/glog\-ref
  658. #!/bin/sh
  659. git log \-1 \-\-oneline \-\-format="%h (%s)" \-\-abbrev\-commit \-\-abbrev=14
  660. $ git config trailer\&.see\&.key "See\-also: "
  661. $ git config trailer\&.see\&.ifExists "replace"
  662. $ git config trailer\&.see\&.ifMissing "doNothing"
  663. $ git config trailer\&.see\&.cmd "glog\-ref"
  664. $ git interpret\-trailers \-\-trailer=see <msg\&.txt
  665. subject
  666. body text
  667. See\-also: fe3187489d69c4 (subject of related commit)
  668. .fi
  669. .if n \{\
  670. .RE
  671. .\}
  672. .RE
  673. .sp
  674. .RS 4
  675. .ie n \{\
  676. \h'-04'\(bu\h'+03'\c
  677. .\}
  678. .el \{\
  679. .sp -1
  680. .IP \(bu 2.3
  681. .\}
  682. Configure a commit template with some trailers with empty values (using sed to show and keep the trailing spaces at the end of the trailers), then configure a commit\-msg hook that uses
  683. \fIgit interpret\-trailers\fR
  684. to remove trailers with empty values and to add a
  685. \fIgit\-version\fR
  686. trailer:
  687. .sp
  688. .if n \{\
  689. .RS 4
  690. .\}
  691. .nf
  692. $ cat temp\&.txt
  693. ***subject***
  694. ***message***
  695. Fixes: Z
  696. Cc: Z
  697. Reviewed\-by: Z
  698. Signed\-off\-by: Z
  699. $ sed \-e \*(Aqs/ Z$/ /\*(Aq temp\&.txt > commit_template\&.txt
  700. $ git config commit\&.template commit_template\&.txt
  701. $ cat \&.git/hooks/commit\-msg
  702. #!/bin/sh
  703. git interpret\-trailers \-\-trim\-empty \-\-trailer "git\-version: \e$(git describe)" "\e$1" > "\e$1\&.new"
  704. mv "\e$1\&.new" "\e$1"
  705. $ chmod +x \&.git/hooks/commit\-msg
  706. .fi
  707. .if n \{\
  708. .RE
  709. .\}
  710. .RE
  711. .SH "SEE ALSO"
  712. .sp
  713. \fBgit-commit\fR(1), \fBgit-format-patch\fR(1), \fBgit-config\fR(1)
  714. .SH "GIT"
  715. .sp
  716. Part of the \fBgit\fR(1) suite