documentation: add some commas where they are helpful

newren · gitster · commit 4d542687fcea · 2023-10-09T12:06:44.000-07:00
Diff best viewed with --color-diff.

Signed-off-by: Elijah Newren &lt;newren@gmail.com&gt;
Signed-off-by: Junio C Hamano &lt;gitster@pobox.com&gt;
diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt
@@ -5,7 +5,7 @@ Tools for developing Git
 [[summary]]
 == Summary
 
-This document gathers tips, scripts and configuration files to help people
+This document gathers tips, scripts, and configuration files to help people
 working on Git's codebase use their favorite tools while following Git's
 coding style.
 
diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt
@@ -1,3 +1,3 @@
 clean.requireForce::
 	A boolean to make git-clean do nothing unless given -f,
-	-i or -n.   Defaults to true.
+	-i, or -n.  Defaults to true.
diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt
@@ -106,7 +106,7 @@ color.grep.<slot>::
 	matching text in context lines
 `matchSelected`;;
 	matching text in selected lines. Also, used to customize the following
-	linkgit:git-log[1] subcommands: `--grep`, `--author` and `--committer`.
+	linkgit:git-log[1] subcommands: `--grep`, `--author`, and `--committer`.
 `selected`;;
 	non-matching text in selected lines. Also, used to customize the
 	following linkgit:git-log[1] subcommands: `--grep`, `--author` and
diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt
@@ -21,7 +21,7 @@ credential.username::
 
 credential.<url>.*::
 	Any of the credential.* options above can be applied selectively to
-	some credentials. For example "credential.https://example.com.username"
+	some credentials. For example, "credential.https://example.com.username"
 	would set the default username only for https connections to
 	example.com. See linkgit:gitcredentials[7] for details on how URLs are
 	matched.
diff --git a/Documentation/config/fastimport.txt b/Documentation/config/fastimport.txt
@@ -1,8 +1,8 @@
 fastimport.unpackLimit::
 	If the number of objects imported by linkgit:git-fast-import[1]
 	is below this limit, then the objects will be unpacked into
-	loose object files.  However if the number of imported objects
-	equals or exceeds this limit then the pack will be stored as a
+	loose object files.  However, if the number of imported objects
+	equals or exceeds this limit, then the pack will be stored as a
 	pack.  Storing the pack from a fast-import can make the import
 	operation complete faster, especially on slow filesystems.  If
 	not set, the value of `transfer.unpackLimit` is used instead.
diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt
@@ -13,10 +13,10 @@ The rest of the documentation discusses `fsck.*` for brevity, but the
 same applies for the corresponding `receive.fsck.*` and
 `fetch.fsck.*`. variables.
 +
-Unlike variables like `color.ui` and `core.editor` the
+Unlike variables like `color.ui` and `core.editor`, the
 `receive.fsck.<msg-id>` and `fetch.fsck.<msg-id>` variables will not
 fall back on the `fsck.<msg-id>` configuration if they aren't set. To
-uniformly configure the same fsck settings in different circumstances
+uniformly configure the same fsck settings in different circumstances,
 all three of them must be set to the same values.
 +
 When `fsck.<msg-id>` is set, errors can be switched to warnings and
@@ -43,12 +43,12 @@ values of `<msg-id>`.
 fsck.skipList::
 	The path to a list of object names (i.e. one unabbreviated SHA-1 per
 	line) that are known to be broken in a non-fatal way and should
-	be ignored. On versions of Git 2.20 and later comments ('#'), empty
+	be ignored. On versions of Git 2.20 and later, comments ('#'), empty
 	lines, and any leading and trailing whitespace are ignored. Everything
 	but a SHA-1 per line will error out on older versions.
 +
 This feature is useful when an established project should be accepted
-despite early commits containing errors that can be safely ignored
+despite early commits containing errors that can be safely ignored,
 such as invalid committer email addresses.  Note: corrupt objects
 cannot be skipped with this setting.
 +
@@ -58,7 +58,7 @@ Like `fsck.<msg-id>` this variable has corresponding
 Unlike variables like `color.ui` and `core.editor` the
 `receive.fsck.skipList` and `fetch.fsck.skipList` variables will not
 fall back on the `fsck.skipList` configuration if they aren't set. To
-uniformly configure the same fsck settings in different circumstances
+uniformly configure the same fsck settings in different circumstances,
 all three of them must be set to the same values.
 +
 Older versions of Git (before 2.20) documented that the object names
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
@@ -9,7 +9,7 @@ log.date::
 	`--date` option.  See linkgit:git-log[1] for details.
 +
 If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be used for the date format. Otherwise "default" will
+"foo" will be used for the date format. Otherwise, "default" will
 be used.
 
 log.decorate::
diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt
@@ -7,7 +7,7 @@ merge.conflictStyle::
 	marker and the original text before the `=======` marker.  The
 	"merge" style tends to produce smaller conflict regions than diff3,
 	both because of the exclusion of the original text, and because
-	when a subset of lines match on the two sides they are just pulled
+	when a subset of lines match on the two sides, they are just pulled
 	out of the conflict region.  Another alternate style, "zdiff3", is
 	similar to diff3 but removes matching lines on the two sides from
 	the conflict region when those matching lines appear near either
diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt
@@ -22,8 +22,8 @@ mergetool.<tool>.trustExitCode::
 	For a custom merge command, specify whether the exit code of
 	the merge command can be used to determine whether the merge was
 	successful.  If this is not set to true then the merge target file
-	timestamp is checked and the merge is assumed to have been successful
-	if the file has been updated, otherwise the user is prompted to
+	timestamp is checked, and the merge is assumed to have been successful
+	if the file has been updated; otherwise, the user is prompted to
 	indicate the success of the merge.
 
 mergetool.meld.hasOutput::
@@ -37,7 +37,7 @@ mergetool.meld.hasOutput::
 
 mergetool.meld.useAutoMerge::
 	When the `--auto-merge` is given, meld will merge all non-conflicting
-	parts automatically, highlight the conflicting parts and wait for
+	parts automatically, highlight the conflicting parts, and wait for
 	user decision.  Setting `mergetool.meld.useAutoMerge` to `true` tells
 	Git to unconditionally use the `--auto-merge` option with `meld`.
 	Setting this value to `auto` makes git detect whether `--auto-merge`
@@ -55,7 +55,7 @@ endif::[]
 	for details.
 
 mergetool.hideResolved::
-	During a merge Git will automatically resolve as many conflicts as
+	During a merge, Git will automatically resolve as many conflicts as
 	possible and write the 'MERGED' file containing conflict markers around
 	any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
 	represent the versions of the file from before Git's conflict
@@ -74,7 +74,7 @@ mergetool.keepTemporaries::
 	When invoking a custom merge tool, Git uses a set of temporary
 	files to pass to the tool. If the tool returns an error and this
 	variable is set to `true`, then these temporary files will be
-	preserved, otherwise they will be removed after the tool has
+	preserved; otherwise, they will be removed after the tool has
 	exited. Defaults to `false`.
 
 mergetool.writeToTemp::
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
@@ -67,7 +67,7 @@ new default).
 --
 
 push.followTags::
-	If set to true enable `--follow-tags` option by default.  You
+	If set to true, enable `--follow-tags` option by default.  You
 	may override this configuration at time of push by specifying
 	`--no-follow-tags`.
 
diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.txt
@@ -2,4 +2,4 @@ sequence.editor::
 	Text editor used by `git rebase -i` for editing the rebase instruction file.
 	The value is meant to be interpreted by the shell when it is used.
 	It can be overridden by the `GIT_SEQUENCE_EDITOR` environment variable.
-	When not configured the default commit message editor is used instead.
+	When not configured, the default commit message editor is used instead.
diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.txt
@@ -3,10 +3,10 @@ splitIndex.maxPercentChange::
 	percent of entries the split index can contain compared to the
 	total number of entries in both the split index and the shared
 	index before a new shared index is written.
-	The value should be between 0 and 100. If the value is 0 then
-	a new shared index is always written, if it is 100 a new
+	The value should be between 0 and 100. If the value is 0, then
+	a new shared index is always written; if it is 100, a new
 	shared index is never written.
-	By default the value is 20, so a new shared index is written
+	By default, the value is 20, so a new shared index is written
 	if the number of entries in the split index would be greater
 	than 20 percent of the total number of entries.
 	See linkgit:git-update-index[1].
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
@@ -8,11 +8,11 @@ committer.email::
 	up in the `author` and `committer` fields of commit
 	objects.
 	If you need the `author` or `committer` to be different, the
-	`author.name`, `author.email`, `committer.name` or
+	`author.name`, `author.email`, `committer.name`, or
 	`committer.email` variables can be set.
 	All of these can be overridden by the `GIT_AUTHOR_NAME`,
 	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
-	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
+	`GIT_COMMITTER_EMAIL`, and `EMAIL` environment variables.
 +
 Note that the `name` forms of these variables conventionally refer to
 some form of a personal name.  See linkgit:git-commit[1] and the
diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.txt
@@ -19,7 +19,7 @@ with those suffixes.  E.g. if "-pre" appears before "-rc" in the
 configuration, then all "1.0-preX" tags will be listed before any
 "1.0-rcX" tags.  The placement of the main release tag relative to tags
 with various suffixes can be determined by specifying the empty suffix
-among those other suffixes.  E.g. if the suffixes "-rc", "", "-ck" and
+among those other suffixes.  E.g. if the suffixes "-rc", "", "-ck", and
 "-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags
 are listed first, followed by "v4.8", then "v4.8-ckX" and finally
 "v4.8-bfsX".
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
@@ -156,7 +156,7 @@ format, `/dev/null` is used to signal created or deleted
 files.
 +
 However, if the --combined-all-paths option is provided, instead of a
-two-line from-file/to-file you get an N+1 line from-file/to-file header,
+two-line from-file/to-file, you get an N+1 line from-file/to-file header,
 where N is the number of parents in the merge commit:
 
        --- a/file
@@ -197,7 +197,7 @@ added, from the point of view of that parent).
 In the above example output, the function signature was changed
 from both files (hence two `-` removals from both file1 and
 file2, plus `++` to mean one line that was added does not appear
-in either file1 or file2).  Also eight other lines are the same
+in either file1 or file2).  Also, eight other lines are the same
 from file1 but do not appear in file2 (hence prefixed with `+`).
 
 When shown by `git diff-tree -c`, it compares the parents of a
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
@@ -96,7 +96,7 @@ endif::git-pull[]
 
 -f::
 --force::
-	When 'git fetch' is used with `<src>:<dst>` refspec it may
+	When 'git fetch' is used with `<src>:<dst>` refspec, it may
 	refuse to update the local branch as discussed
 ifdef::git-pull[]
 	in the `<refspec>` part of the linkgit:git-fetch[1]
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
@@ -23,7 +23,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Splits mail messages in a mailbox into commit log messages,
-authorship information and patches, and applies them to the
+authorship information, and patches, and applies them to the
 current branch. You could think of it as a reverse operation
 of linkgit:git-format-patch[1] run on a branch with a straight
 history without merges.
@@ -134,7 +134,7 @@ include::rerere-options.txt[]
 	automatically. This option allows the user to bypass the automatic
 	detection and specify the patch format that the patch(es) should be
 	interpreted as. Valid formats are mbox, mboxrd,
-	stgit, stgit-series and hg.
+	stgit, stgit-series, and hg.
 
 -i::
 --interactive::
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
@@ -23,8 +23,8 @@ DESCRIPTION
 Reads the supplied diff output (i.e. "a patch") and applies it to files.
 When running from a subdirectory in a repository, patched paths
 outside the directory are ignored.
-With the `--index` option the patch is also applied to the index, and
-with the `--cached` option the patch is only applied to the index.
+With the `--index` option, the patch is also applied to the index, and
+with the `--cached` option, the patch is only applied to the index.
 Without these options, the command applies the patch only to files,
 and does not require them to be in a Git repository.
 
@@ -52,7 +52,7 @@ OPTIONS
 --summary::
 	Instead of applying the patch, output a condensed
 	summary of information obtained from git diff extended
-	headers, such as creations, renames and mode changes.
+	headers, such as creations, renames, and mode changes.
 	Turns off "apply".
 
 --check::
@@ -140,7 +140,7 @@ linkgit:git-config[1]).
 	applying a diff generated with `--unified=0`. To bypass these
 	checks use `--unidiff-zero`.
 +
-Note, for the reasons stated above the usage of context-free patches is
+Note, for the reasons stated above, the usage of context-free patches is
 discouraged.
 
 --apply::
@@ -161,7 +161,7 @@ discouraged.
 --binary::
 	Historically we did not allow binary patch application
 	without an explicit permission from the user, and this
-	flag was the way to do so.  Currently we always allow binary
+	flag was the way to do so.  Currently, we always allow binary
 	patch application, so this is a no-op.
 
 --exclude=<path-pattern>::
diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
@@ -38,7 +38,7 @@ OPTIONS
 
 --source=<tree-ish>::
 	Check attributes against the specified tree-ish. It is common to
-	specify the source tree by naming a commit, branch or tag associated
+	specify the source tree by naming a commit, branch, or tag associated
 	with it.
 
 \--::
@@ -60,7 +60,7 @@ unless `-z` is in effect, in which case NUL is used as delimiter:
 
 
 <path> is the path of a file being queried, <attribute> is an attribute
-being queried and <info> can be either:
+being queried, and <info> can be either:
 
 'unspecified';; when the attribute is not defined for the path.
 'unset';;	when the attribute is defined as false.
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
@@ -57,7 +57,7 @@ OPTIONS
 	Note: --stage=all automatically implies --temp.
 
 --temp::
-	Instead of copying the files to the working directory
+	Instead of copying the files to the working directory,
 	write the content to temporary files.  The temporary name
 	associations will be written to stdout.
 
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
@@ -26,7 +26,7 @@ include::diff-options.txt[]
 -2 --ours::
 -3 --theirs::
 -0::
-	Diff against the "base" version, "our branch" or "their
+	Diff against the "base" version, "our branch", or "their
 	branch" respectively.  With these options, diffs for
 	merged entries are not shown.
 +
@@ -37,7 +37,7 @@ omit diff output for unmerged entries and just show "Unmerged".
 -c::
 --cc::
 	This compares stage 2 (our branch), stage 3 (their
-	branch) and the working tree file and outputs a combined
+	branch), and the working tree file and outputs a combined
 	diff, similar to the way 'diff-tree' shows a merge
 	commit with these flags.
 
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
@@ -1353,7 +1353,7 @@ the marks back to the source repository, it is easy to verify the
 accuracy and completeness of the import by comparing each Git
 commit to the corresponding source revision.
 
-Coming from a system such as Perforce or Subversion this should be
+Coming from a system such as Perforce or Subversion, this should be
 quite simple, as the fast-import mark can also be the Perforce changeset
 number or the Subversion revision number.
 
diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
@@ -73,7 +73,7 @@ but it will not cause an incorrect result.
 By default, the fsmonitor daemon refuses to work with network-mounted
 repositories; this may be overridden by setting `fsmonitor.allowRemote` to
 `true`. Note, however, that the fsmonitor daemon is not guaranteed to work
-correctly with all network-mounted repositories and such use is considered
+correctly with all network-mounted repositories, so such use is considered
 experimental.
 
 On Mac OS, the inter-process communication (IPC) between various Git
@@ -86,7 +86,7 @@ to work with these filesystems and such use is considered experimental.
 By default, the socket is created in the `.git` directory.  However, if the
 `.git` directory is on a network-mounted filesystem, it will instead be
 created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
-network-mounted filesystem in which case you must set the configuration
+network-mounted filesystem, in which case you must set the configuration
 variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native
 filesystem in which to create the socket file.
 
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
@@ -59,7 +59,7 @@ OPTIONS
 	aliases.
 
 --verbose::
-	When used with `--all` print description for all recognized
+	When used with `--all`, print description for all recognized
 	commands. This is the default.
 
 -c::
@@ -129,8 +129,8 @@ line option:
 * "info" corresponds to '-i|--info',
 * "web" or "html" correspond to '-w|--web'.
 
-help.browser, web.browser and browser.<tool>.path
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+help.browser, web.browser, and browser.<tool>.path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The `help.browser`, `web.browser` and `browser.<tool>.path` will also
 be checked if the 'web' format is chosen (either by command-line
diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt
@@ -44,7 +44,7 @@ OPTIONS
 -d::
 -D::
 	Remove <ref> from remote repository.  The specified branch
-	cannot be the remote HEAD.  If -d is specified the following
+	cannot be the remote HEAD.  If -d is specified, the following
 	other conditions must also be met:
 
 	- Remote HEAD must resolve to an object that exists locally
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
@@ -88,7 +88,7 @@ For example, with this topology:
 
 the merge base between 'A' and 'B' is '1'.
 
-Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
+Given three commits 'A', 'B', and 'C', `git merge-base A B C` will compute the
 merge base between 'A' and a hypothetical commit 'M', which is a merge
 between 'B' and 'C'.  For example, with this topology:
 
@@ -204,7 +204,7 @@ will find B0, and
 
     $ git rebase --onto origin/master $fork_point topic
 
-will replay D0, D1 and D on top of B to create a new history of this
+will replay D0, D1, and D on top of B to create a new history of this
 shape:
 
 ....
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.txt
diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ log.date::`
`9`	`9`	`--date` option. See linkgit:git-log[1] for details.
`10`	`10`	`+`
`11`	`11`	`If the format is set to "auto:foo" and the pager is in use, format`
`12`		`-"foo" will be used for the date format. Otherwise "default" will`
	`12`	`+"foo" will be used for the date format. Otherwise, "default" will`
`13`	`13`	`be used.`
`14`	`14`
`15`	`15`	`log.decorate::`