@matheusbsbs / matheus-bagliano / commits / 3abd4a67d9

Documentation: stylistically normalize references to Signed-off-by:

Ted reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article. Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to `Signed-off-by`. First, very few places used a definite or indefinite article with the phrase "Signed-off-by line", but that was the initial typo that led to this investigation. So, normalize using either an indefinite or definite article consistently. The original phrasing, in Commit 3f971fc425b (Documentation updates, 2005-08-14), is "Add Signed-off-by line". Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add `Signed-off-by:` line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent. Junio stated on the git mailing list in <xmqqy2k1dfoh.fsf@gitster.c.googlers.com> a preference to leave off the colon. Thus, prefer `Signed-off-by` (with backticks) for the documentation files and Signed-off-by (without backticks) for option help strings. Additionally, Junio argued that "trailer" is now the standard term to refer to `Signed-off-by`, saying that "becomes plenty clear that we are not talking about any random line in the log message". As such, prefer "trailer" over "line" anywhere the former word fits. However, leave alone those few places in documentation that use Signed-off-by to refer to the process (rather than the specific trailer), or in places where mail headers are generally discussed in comparison with Signed-off-by. Reported-by: "Theodore Y. Ts'o" <tytso@mit.edu> Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org> Acked-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Bradley M. Kuhn committed Oct 19, 2020 at 18:03 UTC 3abd4a67d912e0c0980aa34def6ea55ebde84947

20 files changed +26 -26

Documentation/MyFirstContribution.txt

+1 -1

@@ -249,7 +249,7 @@ component you're working on, followed by a blank line (always required) and then

249 the body of your commit message, which should provide the bulk of the context.

250 Remember to be explicit and provide the "Why" of your change, especially if it

251 couldn't easily be understood from your diff. When editing your commit message,

252 -don't remove the Signed-off-by line which was added by `-s` above.

252 +don't remove the `Signed-off-by` trailer which was added by `-s` above.

253

254 ----

255 psuh: add a built-in by popular demand

Documentation/SubmittingPatches

+5 -5

@@ -209,7 +209,7 @@ send them as replies to either an additional "cover letter" message

209 (see below), the first patch, or the respective preceding patch.

210

211 If your log message (including your name on the

212 -Signed-off-by line) is not writable in ASCII, make sure that

212 +`Signed-off-by` trailer) is not writable in ASCII, make sure that

213 you send off a message in the correct encoding.

214

215 WARNING: Be wary of your MUAs word-wrap

@@ -229,7 +229,7 @@ previously sent.

229 The `git format-patch` command follows the best current practice to

230 format the body of an e-mail message. At the beginning of the

231 patch should come your commit message, ending with the

232 -Signed-off-by: lines, and a line that consists of three dashes,

232 +`Signed-off-by` trailers, and a line that consists of three dashes,

233 followed by the diffstat information and the patch itself. If

234 you are forwarding a patch from somebody else, optionally, at

235 the beginning of the e-mail message just before the commit

@@ -298,7 +298,7 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and

298 patch.

299

300 [[sign-off]]

301 -=== Certify your work by adding your "Signed-off-by: " line

301 +=== Certify your work by adding your `Signed-off-by` trailer

302

303 To improve tracking of who did what, we ask you to certify that you

304 wrote the patch or have the right to pass it on under the same license

@@ -345,7 +345,7 @@ this:

345 This line can be added by Git if you run the git-commit command with

346 the -s option.

347

348 -Notice that you can place your own Signed-off-by: line when

348 +Notice that you can place your own `Signed-off-by` trailer when

349 forwarding somebody else's patch with the above rules for

350 D-C-O. Indeed you are encouraged to do so. Do not forget to

351 place an in-body "From: " line at the beginning to properly attribute

@@ -357,7 +357,7 @@ your patch differs from project to project, so it may be different

357 from that of the project you are accustomed to.

358

359 [[real-name]]

360 -Also notice that a real name is used in the Signed-off-by: line. Please

360 +Also notice that a real name is used in the `Signed-off-by` trailer. Please

361 don't hide your real name.

362

363 [[commit-trailers]]

Documentation/config/format.txt

+1 -1

@@ -79,7 +79,7 @@ format.thread::

80 format.signOff::

81 A boolean value which lets you enable the `-s/--signoff` option of

82 - format-patch by default. *Note:* Adding the Signed-off-by: line to a

82 + format-patch by default. *Note:* Adding the `Signed-off-by` trailer to a

83 patch should be a conscious act and means that you certify you have

84 the rights to submit this work under the same open source license.

85 Please see the 'SubmittingPatches' document for further discussion.

Documentation/git-am.txt

+1 -1

@@ -33,7 +33,7 @@ OPTIONS

34 -s::

35 --signoff::

36 - Add a `Signed-off-by:` line to the commit message, using

36 + Add a `Signed-off-by` trailer to the commit message, using

37 the committer identity of yourself.

38 See the signoff option in linkgit:git-commit[1] for more information.

Documentation/git-cherry-pick.txt

+1 -1

@@ -104,7 +104,7 @@ effect to your index in a row.

104

105 -s::

106 --signoff::

107 - Add Signed-off-by line at the end of the commit message.

107 + Add a `Signed-off-by` trailer at the end of the commit message.

108 See the signoff option in linkgit:git-commit[1] for more information.

109

110 -S[<keyid>]::

Documentation/git-format-patch.txt

+1 -1

@@ -119,7 +119,7 @@ include::diff-options.txt[]

119

120 -s::

121 --signoff::

122 - Add `Signed-off-by:` line to the commit message, using

122 + Add a `Signed-off-by` trailer to the commit message, using

123 the committer identity of yourself.

124 See the signoff option in linkgit:git-commit[1] for more information.

125

Documentation/git-rebase.txt

+1 -1

@@ -496,7 +496,7 @@ See also INCOMPATIBLE OPTIONS below.

496 See also INCOMPATIBLE OPTIONS below.

497

498 --signoff::

499 - Add a Signed-off-by: trailer to all the rebased commits. Note

499 + Add a `Signed-off-by` trailer to all the rebased commits. Note

500 that if `--interactive` is given then only commits marked to be

501 picked, edited or reworded will have the trailer added.

502 +

Documentation/git-revert.txt

+1 -1

@@ -99,7 +99,7 @@ effect to your index in a row.

100 -s::

101 --signoff::

102 - Add Signed-off-by line at the end of the commit message.

102 + Add a `Signed-off-by` trailer at the end of the commit message.

103 See the signoff option in linkgit:git-commit[1] for more information.

104

105 --strategy=<strategy>::

Documentation/git-send-email.txt

+2 -2

@@ -313,7 +313,7 @@ Automating

313 the value of `sendemail.identity`.

314

315 --[no-]signed-off-by-cc::

316 - If this is set, add emails found in Signed-off-by: or Cc: lines to the

316 + If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the

317 cc list. Default is the value of `sendemail.signedoffbycc` configuration

318 value; if that is unspecified, default to --signed-off-by-cc.

319

@@ -340,7 +340,7 @@ Automating

340 except for self (use 'self' for that).

341 - 'bodycc' will avoid including anyone mentioned in Cc lines in the

342 patch body (commit message) except for self (use 'self' for that).

343 -- 'sob' will avoid including anyone mentioned in Signed-off-by lines except

343 +- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except

344 for self (use 'self' for that).

345 - 'misc-by' will avoid including anyone mentioned in Acked-by,

346 Reviewed-by, Tested-by and other "-by" lines in the patch body,

Documentation/git-svn.txt

+2 -2

@@ -701,7 +701,7 @@ creating the branch or tag.

701

702 --use-log-author::

703 When retrieving svn commits into Git (as part of 'fetch', 'rebase', or

704 - 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line

704 + 'dcommit' operations), look for the first `From:` line or `Signed-off-by` trailer

705 in the log message and use that as the author string.

706 +

707 [verse]

@@ -710,7 +710,7 @@ config key: svn.useLogAuthor

710 --add-author-from::

711 When committing to svn from Git (as part of 'set-tree' or 'dcommit'

712 operations), if the existing log message doesn't already have a

713 - `From:` or `Signed-off-by:` line, append a `From:` line based on the

713 + `From:` or `Signed-off-by` trailer, append a `From:` line based on the

714 Git commit's author string. If you use this, then `--use-log-author`

715 will retrieve a valid author string for all commits.

716 +

Documentation/githooks.txt

+1 -1

@@ -164,7 +164,7 @@ can also be used to refuse the commit after inspecting the message

164 file.

165

166 The default 'commit-msg' hook, when enabled, detects duplicate

167 -"Signed-off-by" lines, and aborts the commit if one is found.

167 +`Signed-off-by` trailers, and aborts the commit if one is found.

168

169 post-commit

170 ~~~~~~~~~~~

Documentation/signoff-option.txt

+1 -1

@@ -3,7 +3,7 @@ ifdef::git-commit[]

3 endif::git-commit[]

4 --signoff::

5 --no-signoff::

6 - Add a Signed-off-by trailer by the committer at the end of the commit

6 + Add a `Signed-off-by` trailer by the committer at the end of the commit

7 log message. The meaning of a signoff depends on the project

8 to which you're committing. For example, it may certify that

9 the committer has the rights to submit the work under the

builtin/am.c

+1 -1

@@ -2237,7 +2237,7 @@ int cmd_am(int argc, const char **argv, const char *prefix)

2237 N_("allow fall back on 3way merging if needed")),

2238 OPT__QUIET(&state.quiet, N_("be quiet")),

2239 OPT_SET_INT('s', "signoff", &state.signoff,

2240 - N_("add a Signed-off-by line to the commit message"),

2240 + N_("add a Signed-off-by trailer to the commit message"),

2241 SIGNOFF_EXPLICIT),

2242 OPT_BOOL('u', "utf8", &state.utf8,

2243 N_("recode into utf8 (default)")),

builtin/commit.c

+1 -1

@@ -1507,7 +1507,7 @@ int cmd_commit(int argc, const char **argv, const char *prefix)

1507 OPT_STRING(0, "fixup", &fixup_message, N_("commit"), N_("use autosquash formatted message to fixup specified commit")),

1508 OPT_STRING(0, "squash", &squash_message, N_("commit"), N_("use autosquash formatted message to squash specified commit")),

1509 OPT_BOOL(0, "reset-author", &renew_authorship, N_("the commit is authored by me now (used with -C/-c/--amend)")),

1510 - OPT_BOOL('s', "signoff", &signoff, N_("add Signed-off-by:")),

1510 + OPT_BOOL('s', "signoff", &signoff, N_("add a Signed-off-by trailer")),

1511 OPT_FILENAME('t', "template", &template_file, N_("use specified template file")),

1512 OPT_BOOL('e', "edit", &edit_flag, N_("force edit of commit")),

1513 OPT_CLEANUP(&cleanup_arg),

builtin/log.c

+1 -1

@@ -1738,7 +1738,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)

1738 OPT_CALLBACK_F('N', "no-numbered", &numbered, NULL,

1739 N_("use [PATCH] even with multiple patches"),

1740 PARSE_OPT_NOARG | PARSE_OPT_NONEG, no_numbered_callback),

1741 - OPT_BOOL('s', "signoff", &do_signoff, N_("add Signed-off-by:")),

1741 + OPT_BOOL('s', "signoff", &do_signoff, N_("add a Signed-off-by trailer")),

1742 OPT_BOOL(0, "stdout", &use_stdout,

1743 N_("print patches to standard out")),

1744 OPT_BOOL(0, "cover-letter", &cover_letter,

builtin/merge.c

+1 -1

@@ -289,7 +289,7 @@ static struct option builtin_merge_options[] = {

289 N_("GPG sign commit"), PARSE_OPT_OPTARG, NULL, (intptr_t) "" },

290 OPT_AUTOSTASH(&autostash),

291 OPT_BOOL(0, "overwrite-ignore", &overwrite_ignore, N_("update ignored files (default)")),

292 - OPT_BOOL(0, "signoff", &signoff, N_("add Signed-off-by:")),

292 + OPT_BOOL(0, "signoff", &signoff, N_("add a Signed-off-by trailer")),

293 OPT_BOOL(0, "no-verify", &no_verify, N_("bypass pre-merge-commit and commit-msg hooks")),

294 OPT_END()

295 };

builtin/pull.c

+1 -1

@@ -142,7 +142,7 @@ static struct option pull_options[] = {

142 N_("add (at most <n>) entries from shortlog to merge commit message"),

143 PARSE_OPT_OPTARG),

144 OPT_PASSTHRU(0, "signoff", &opt_signoff, NULL,

145 - N_("add Signed-off-by:"),

145 + N_("add a Signed-off-by trailer"),

146 PARSE_OPT_OPTARG),

147 OPT_PASSTHRU(0, "squash", &opt_squash, NULL,

148 N_("create a single commit instead of doing a merge"),

builtin/rebase.c

+1 -1

@@ -1324,7 +1324,7 @@ int cmd_rebase(int argc, const char **argv, const char *prefix)

1324 N_("do not show diffstat of what changed upstream"),

1325 PARSE_OPT_NOARG, NULL, REBASE_DIFFSTAT },

1326 OPT_BOOL(0, "signoff", &options.signoff,

1327 - N_("add a Signed-off-by: line to each commit")),

1327 + N_("add a Signed-off-by trailer to each commit")),

1328 OPT_BOOL(0, "committer-date-is-author-date",

1329 &options.committer_date_is_author_date,

1330 N_("make committer date match author date")),

builtin/revert.c

+1 -1

@@ -107,7 +107,7 @@ static int run_sequencer(int argc, const char **argv, struct replay_opts *opts)

107 OPT_BOOL('n', "no-commit", &opts->no_commit, N_("don't automatically commit")),

108 OPT_BOOL('e', "edit", &opts->edit, N_("edit the commit message")),

109 OPT_NOOP_NOARG('r', NULL),

110 - OPT_BOOL('s', "signoff", &opts->signoff, N_("add Signed-off-by:")),

110 + OPT_BOOL('s', "signoff", &opts->signoff, N_("add a Signed-off-by trailer")),

111 OPT_CALLBACK('m', "mainline", opts, N_("parent-number"),

112 N_("select mainline parent"), option_parse_m),

113 OPT_RERERE_AUTOUPDATE(&opts->allow_rerere_auto),

commit.c

+1 -1

@@ -1586,7 +1586,7 @@ const char *find_commit_header(const char *msg, const char *key, size_t *out_len

1586

1587 /*

1588 * Inspect the given string and determine the true "end" of the log message, in

1589 - * order to find where to put a new Signed-off-by: line. Ignored are

1589 + * order to find where to put a new Signed-off-by trailer. Ignored are

1590 * trailing comment lines and blank lines. To support "git commit -s

1591 * --amend" on an existing commit, we also ignore "Conflicts:". To

1592 * support "git commit -v", we truncate at cut lines.