[PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[Štěpán Němec]

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/SubmittingPatches  | 10 +++++-----
 Documentation/diff-options.txt   |  2 +-
 Documentation/git-branch.txt     |  2 +-
 Documentation/git-range-diff.txt |  2 +-
 Documentation/git.txt            |  2 +-
 Documentation/gitattributes.txt  |  2 +-
 Documentation/giteveryday.txt    |  2 +-
 contrib/README                   |  4 ++--
 strbuf.h                         |  8 ++++----
 t/README                         | 30 ++++++++++++++----------------
 10 files changed, 31 insertions(+), 33 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 973d7a81d449..1259549cd488 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -393,8 +393,8 @@ mailing list{security-ml}, instead of the public mailing list.
 
 Learn to use format-patch and send-email if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
-your existing e-mail client that is optimized for "multipart/*" mime
-type e-mails to corrupt and render your patches unusable.
+your existing e-mail client (often optimized for "multipart/*" MIME
+type e-mails) might render your patches unusable.
 
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
@@ -515,8 +515,8 @@ repositories.
 
 	git://git.ozlabs.org/~paulus/gitk
 
-   Those who are interested in improve gitk can volunteer to help Paul
-   in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
+   Those who are interested in improving gitk can volunteer to help Paul
+   maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
 
 - `po/` comes from the localization coordinator, Jiang Xin:
 
@@ -556,7 +556,7 @@ help you find out who they are.
 
 In any time between the (2)-(3) cycle, the maintainer may pick it up
 from the list and queue it to `seen`, in order to make it easier for
-people play with it without having to pick up and apply the patch to
+people to play with it without having to pick up and apply the patch to
 their trees themselves.
 
 [[patch-status]]
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 35fae7c87c8a..ee256ec077be 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -301,7 +301,7 @@ ifndef::git-format-patch[]
 
 -z::
 ifdef::git-log[]
-	Separate the commits with NULs instead of with new newlines.
+	Separate the commits with NULs instead of newlines.
 +
 Also, when `--raw` or `--numstat` has been given, do not munge
 pathnames and use NULs as output field terminators.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d207da9101a5..4395aa935438 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -324,7 +324,7 @@ superproject's "origin/main", but tracks the submodule's "origin/main".
 	multiple times, in which case the last key becomes the primary
 	key. The keys supported are the same as those in `git
 	for-each-ref`. Sort order defaults to the value configured for the
-	`branch.sort` variable if exists, or to sorting based on the
+	`branch.sort` variable if it exists, or to sorting based on the
 	full refname (including `refs/...` prefix). This lists
 	detached HEAD (if present) first, then local branches and
 	finally remote-tracking branches. See linkgit:git-config[1].
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index 0b393715d707..6c728dbe44b2 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -166,7 +166,7 @@ A typical output of `git range-diff` would look like this:
 
 In this example, there are 3 old and 3 new commits, where the developer
 removed the 3rd, added a new one before the first two, and modified the
-commit message of the 2nd commit as well its diff.
+commit message of the 2nd commit as well as its diff.
 
 When the output goes to a terminal, it is color-coded by default, just
 like regular `git diff`'s output. In addition, the first line (adding a
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 11228956cd5e..b246dc86c3f3 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -96,7 +96,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 	to avoid ambiguity with `<name>` containing one.
 +
 This is useful for cases where you want to pass transitory
-configuration options to git, but are doing so on OS's where
+configuration options to git, but are doing so on OSes where
 other processes might be able to read your cmdline
 (e.g. `/proc/self/cmdline`), but not your environ
 (e.g. `/proc/self/environ`). That behavior is the default on
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 6deb89a29677..7cdc68f54a5c 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -1151,7 +1151,7 @@ will be stored via placeholder `%P`.
 ^^^^^^^^^^^^^^^^^^^^^^
 
 This attribute controls the length of conflict markers left in
-the work tree file during a conflicted merge.  Only setting to
+the work tree file during a conflicted merge.  Only setting
 the value to a positive integer has any meaningful effect.
 
 For example, this line in `.gitattributes` can be used to tell the merge
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index faba2ef0881c..f74a33fb35b9 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -229,7 +229,7 @@ without a formal "merging". Or longhand +
   git am -3 -k`
 
 An alternate participant submission mechanism is using the
-`git request-pull` or pull-request mechanisms (e.g as used on
+`git request-pull` or pull-request mechanisms (e.g. as used on
 GitHub (www.github.com) to notify your upstream of your
 contribution.
 
diff --git a/contrib/README b/contrib/README
index 05f291c1f1d3..d3a327d04074 100644
--- a/contrib/README
+++ b/contrib/README
@@ -24,14 +24,14 @@ lesser degree various foreign SCM interfaces, so you know the
 drill.
 
 I expect that things that start their life in the contrib/ area
-to graduate out of contrib/ once they mature, either by becoming
+graduate out of contrib/ once they mature, either by becoming
 projects on their own, or moving to the toplevel directory.  On
 the other hand, I expect I'll be proposing removal of disused
 and inactive ones from time to time.
 
 If you have new things to add to this area, please first propose
 it on the git mailing list, and after a list discussion proves
-there are some general interests (it does not have to be a
+there is general interest (it does not have to be a
 list-wide consensus for a tool targeted to a relatively narrow
 audience -- for example I do not work with projects whose
 upstream is svn, so I have no use for git-svn myself, but it is
diff --git a/strbuf.h b/strbuf.h
index fd43c46433a4..e959caca876a 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -12,9 +12,9 @@
 struct string_list;
 
 /**
- * strbuf's are meant to be used with all the usual C string and memory
+ * strbufs are meant to be used with all the usual C string and memory
  * APIs. Given that the length of the buffer is known, it's often better to
- * use the mem* functions than a str* one (memchr vs. strchr e.g.).
+ * use the mem* functions than a str* one (e.g., memchr vs. strchr).
  * Though, one has to be careful about the fact that str* functions often
  * stop on NULs and that strbufs may have embedded NULs.
  *
@@ -24,7 +24,7 @@ struct string_list;
  * strbufs have some invariants that are very important to keep in mind:
  *
  *  - The `buf` member is never NULL, so it can be used in any usual C
- *    string operations safely. strbuf's _have_ to be initialized either by
+ *    string operations safely. strbufs _have_ to be initialized either by
  *    `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
  *
  *    Do *not* assume anything on what `buf` really is (e.g. if it is
@@ -37,7 +37,7 @@ struct string_list;
  *
  *  - The `buf` member is a byte array that has at least `len + 1` bytes
  *    allocated. The extra byte is used to store a `'\0'`, allowing the
- *    `buf` member to be a valid C-string. Every strbuf function ensure this
+ *    `buf` member to be a valid C-string. All strbuf functions ensure this
  *    invariant is preserved.
  *
  *    NOTE: It is OK to "play" with the buffer directly if you work it this
diff --git a/t/README b/t/README
index 61080859899b..a3e87385d065 100644
--- a/t/README
+++ b/t/README
@@ -262,8 +262,8 @@ The argument for --run, <test-selector>, is a list of description
 substrings or globs or individual test numbers or ranges with an
 optional negation prefix (of '!') that define what tests in a test
 suite to include (or exclude, if negated) in the run.  A range is two
-numbers separated with a dash and matches a range of tests with both
-ends been included.  You may omit the first or the second number to
+numbers separated with a dash and matches an inclusive range of tests
+to run.  You may omit the first or the second number to
 mean "from the first test" or "up to the very last test" respectively.
 
 The argument to --run is split on commas into separate strings,
@@ -274,10 +274,10 @@ text that you want to match includes a comma, use the glob character
 on all tests that match either the glob *rebase* or the glob
 *merge?cherry-pick*.
 
-If --run starts with an unprefixed number or range the initial
-set of tests to run is empty. If the first item starts with '!'
+If --run starts with an unprefixed number or range, the initial
+set of tests to run is empty.  If the first item starts with '!',
 all the tests are added to the initial set.  After initial set is
-determined every test number or range is added or excluded from
+determined, every test number or range is added or excluded from
 the set one by one, from left to right.
 
 For example, to run only tests up to a specific test (21), one
@@ -579,11 +579,10 @@ This test harness library does the following things:
 
 Recommended style
 -----------------
-Here are some recommented styles when writing test case.
 
- - Keep test title the same line with test helper function itself.
+ - Keep test titles and helper function invocations on the same line.
 
-   Take test_expect_success helper for example, write it like:
+   For example, with test_expect_success, write it like:
 
   test_expect_success 'test title' '
       ... test body ...
@@ -595,10 +594,9 @@ Here are some recommented styles when writing test case.
       'test title' \
       '... test body ...'
 
+ - End the line with an opening single quote.
 
- - End the line with a single quote.
-
- - Indent the body of here-document, and use "<<-" instead of "<<"
+ - Indent here-document bodies, and use "<<-" instead of "<<"
    to strip leading TABs used for indentation:
 
   test_expect_success 'test something' '
@@ -624,7 +622,7 @@ Here are some recommented styles when writing test case.
   '
 
  - Quote or escape the EOF delimiter that begins a here-document if
-   there is no parameter and other expansion in it, to signal readers
+   there is no parameter or other expansion in it, to signal readers
    that they can skim it more casually:
 
   cmd <<-\EOF
@@ -638,7 +636,7 @@ Do's & don'ts
 Here are a few examples of things you probably should and shouldn't do
 when writing tests.
 
-Here are the "do's:"
+The "do's:"
 
  - Put all code inside test_expect_success and other assertions.
 
@@ -1237,8 +1235,8 @@ and it knows that the object ID of an empty tree is a certain
 because the things the very basic core test tries to achieve is
 to serve as a basis for people who are changing the Git internals
 drastically.  For these people, after making certain changes,
-not seeing failures from the basic test _is_ a failure.  And
-such drastic changes to the core Git that even changes these
+not seeing failures from the basic test _is_ a failure.  Any
+Git core changes so drastic that they change even these
 otherwise supposedly stable object IDs should be accompanied by
 an update to t0000-basic.sh.
 
@@ -1248,7 +1246,7 @@ knowledge of the core Git internals.  If all the test scripts
 hardcoded the object IDs like t0000-basic.sh does, that defeats
 the purpose of t0000-basic.sh, which is to isolate that level of
 validation in one place.  Your test also ends up needing
-updating when such a change to the internal happens, so do _not_
+an update whenever the internals change, so do _not_
 do it and leave the low level of validation to t0000-basic.sh.
 
 Test coverage
-- 
2.42.0

[PATCH 2/5] doc/diff-options: improve wording of the log.diffMerges mention

[Štěpán Němec]

Fix the grammar ("which default value is") and reword to match other
similar descriptions (say "configuration variable" instead of
"parameter", link to git-config(1)).

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/diff-options.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ee256ec077be..48a5012748dd 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -53,9 +53,9 @@ ifdef::git-log[]
 -m:::
 	This option makes diff output for merge commits to be shown in
 	the default format. `-m` will produce the output only if `-p`
-	is given as well. The default format could be changed using
-	`log.diffMerges` configuration parameter, which default value
-	is `separate`.
+	is given as well. The default format can be specified using
+	the configuration variable `log.diffMerges` (see
+	linkgit:git-config[1]). It defaults to `separate`.
 +
 --diff-merges=first-parent:::
 --diff-merges=1:::
-- 
2.42.0

[PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

[Štěpán Němec]

There's even an example of such usage in the README.

Fixes: 67ba13e5a4b2 ("git-jump: pass "merge" arguments to ls-files")
Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 contrib/git-jump/git-jump | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
index 40c4b0d11107..47e0c557e63f 100755
--- a/contrib/git-jump/git-jump
+++ b/contrib/git-jump/git-jump
@@ -9,7 +9,7 @@ The <mode> parameter is one of:
 
 diff: elements are diff hunks. Arguments are given to diff.
 
-merge: elements are merge conflicts. Arguments are ignored.
+merge: elements are merge conflicts. Arguments are given to ls-files -u.
 
 grep: elements are grep hits. Arguments are given to git grep or, if
       configured, to the command in `jump.grepCmd`.
-- 
2.42.0

[PATCH 4/5] doc/gitk: s/sticked/stuck/

[Štěpán Němec]

The terminology was changed in b0d12fc9b23a (Use the word 'stuck'
instead of 'sticked').

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/gitk.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index d50e9ed10e04..c2213bb77b38 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -26,7 +26,7 @@ changes each commit introduces are shown.  Finally, it supports some
 gitk-specific options.
 
 gitk generally only understands options with arguments in the
-'sticked' form (see linkgit:gitcli[7]) due to limitations in the
+'stuck' form (see linkgit:gitcli[7]) due to limitations in the
 command-line parser.
 
 rev-list options and arguments
-- 
2.42.0

[PATCH 5/5] t/README: fix multi-prerequisite example

[Štěpán Němec]

With the broken quoting the test wouldn't even parse correctly, but
there's also the '==' instead of POSIX '=' (of the shells I tested,
busybox ash, bash and ksh (93 and OpenBSD) accept '==', dash and zsh do
not), and 'print 2' from Python 2 days.

(I assume the test failing due to 3 != 4 is intentional or immaterial.)

Fixes: 93a572461386 ("test-lib: Add support for multiple test prerequisites")
Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/README b/t/README
index a3e87385d065..5b6b8eeb2a5f 100644
--- a/t/README
+++ b/t/README
@@ -886,7 +886,7 @@ see test-lib-functions.sh for the full list and their options.
    rare case where your test depends on more than one:
 
 	test_expect_success PERL,PYTHON 'yo dawg' \
-	    ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" '
+	    ' test $(perl -E '\''print eval "1 +" . qx[python -c "print(2)"]'\'') = "4" '
 
  - test_expect_failure [<prereq>] <message> <script>
 
-- 
2.42.0

Re: [PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[Eric Sunshine]

On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote:
> Fix some typos, grammar or wording issues in the documentation

SubmittingPatches suggests: s/Fix/fix

Overall, these changes are welcome improvements. I've left a few minor
comments below which may or may not be actionable.

> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
> ---
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> @@ -393,8 +393,8 @@ mailing list{security-ml}, instead of the public mailing list.
>  Learn to use format-patch and send-email if possible.  These commands
>  are optimized for the workflow of sending patches, avoiding many ways
> -your existing e-mail client that is optimized for "multipart/*" mime
> -type e-mails to corrupt and render your patches unusable.
> +your existing e-mail client (often optimized for "multipart/*" MIME
> +type e-mails) might render your patches unusable.

A subjective alternative would have been to use commas to set off the
newly-parenthesized comment. Not worth a reroll.

> diff --git a/Documentation/git.txt b/Documentation/git.txt
> @@ -96,7 +96,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
>  This is useful for cases where you want to pass transitory
> -configuration options to git, but are doing so on OS's where
> +configuration options to git, but are doing so on OSes where

Since you're touching this anyhow, it could probably be made clearer
by simply spelling it out: "operating systems"

>  other processes might be able to read your cmdline
>  (e.g. `/proc/self/cmdline`), but not your environ
>  (e.g. `/proc/self/environ`). That behavior is the default on

I wonder if "cmdline" and "environ" would be better spelled out, as
well, since the examples which immediately follow them give the
necessary context.

    other processes might be able to read your command-line
    (e.g. `/proc/self/cmdline`), but not your environment
    (e.g. `/proc/self/environ`).

But perhaps that's outside the scope of this patch?

> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> @@ -1151,7 +1151,7 @@ will be stored via placeholder `%P`.
>  This attribute controls the length of conflict markers left in
> -the work tree file during a conflicted merge.  Only setting to
> +the work tree file during a conflicted merge.  Only setting
>  the value to a positive integer has any meaningful effect.

Or, more simply:

    Only a positive integer has a meaningful effect.

> diff --git a/contrib/README b/contrib/README
> @@ -24,14 +24,14 @@ lesser degree various foreign SCM interfaces, so you know the
>  I expect that things that start their life in the contrib/ area
> -to graduate out of contrib/ once they mature, either by becoming
> +graduate out of contrib/ once they mature, either by becoming

You probably want to add a comma after "area".

Do we want to correct the formatting of this pathname:

    ...in the `contrib/` area...
    ...out of `contrib/` once...

or is that outside the scope of this patch?

> diff --git a/strbuf.h b/strbuf.h
> @@ -12,9 +12,9 @@
> - * strbuf's are meant to be used with all the usual C string and memory
> + * strbufs are meant to be used with all the usual C string and memory

Alternatively:

    strbuf is meant to be used...

>   * APIs. Given that the length of the buffer is known, it's often better to
> - * use the mem* functions than a str* one (memchr vs. strchr e.g.).
> + * use the mem* functions than a str* one (e.g., memchr vs. strchr).
>   * Though, one has to be careful about the fact that str* functions often
>   * stop on NULs and that strbufs may have embedded NULs.

Similar:

    ... and that a strbuf may have...

> diff --git a/t/README b/t/README
> @@ -262,8 +262,8 @@ The argument for --run, <test-selector>, is a list of description
>  suite to include (or exclude, if negated) in the run.  A range is two
> -numbers separated with a dash and matches a range of tests with both
> -ends been included.  You may omit the first or the second number to
> +numbers separated with a dash and matches an inclusive range of tests
> +to run.  You may omit the first or the second number to

Not the fault of this patch, but "matches" seems an odd choice.
Perhaps "specifies" would feel more natural.

>  The argument to --run is split on commas into separate strings,
> @@ -579,11 +579,10 @@ This test harness library does the following things:
> -Here are some recommented styles when writing test case.

Do you want to fix the spelling error while you're here or is that
done in a later patch?

    s/recommented/recommended/

> - - Keep test title the same line with test helper function itself.
> + - Keep test titles and helper function invocations on the same line.

This would be clearer if it was switched around. Either:

    Keep the test_expect_* function call and test title on the same line.

or, more verbosely:

   Place the test title on the same line as the test_expect_* call
   which precedes it.

Re: [PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

[Eric Sunshine]

On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote:
> There's even an example of such usage in the README.
>
> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
> ---
> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
> @@ -9,7 +9,7 @@ The <mode> parameter is one of:
>
>  diff: elements are diff hunks. Arguments are given to diff.
>
> -merge: elements are merge conflicts. Arguments are ignored.
> +merge: elements are merge conflicts. Arguments are given to ls-files -u.

Should "ls-files -u" be formatted with backticks?

    Arguments are passed to `git ls-files -u`.

Re: [PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[Štěpán Němec]

On Tue, 3 Oct 2023 14:30:38 -0400
Eric Sunshine wrote:

> On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote:
>> Fix some typos, grammar or wording issues in the documentation
>
> SubmittingPatches suggests: s/Fix/fix

I think that only applies to subjects of the form "area: description".

Come to think of it, 'doc: fix some typos, grammar and wording issues'
might have made sense to begin with; I don't suppose C header comments
are off-limits to doc:.

>> diff --git a/Documentation/git.txt b/Documentation/git.txt
>> @@ -96,7 +96,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
>>  This is useful for cases where you want to pass transitory
>> -configuration options to git, but are doing so on OS's where
>> +configuration options to git, but are doing so on OSes where
>
> Since you're touching this anyhow, it could probably be made clearer
> by simply spelling it out: "operating systems"

Probably.  Checking for other occurrences now I see I haven't done my
homework, anyway: there are "OS's" as plural in config/transfer.txt and
fsmonitor--daemon.h, too.  I'll include those and use "operating
systems" in the next version, thanks.

>>  other processes might be able to read your cmdline
>>  (e.g. `/proc/self/cmdline`), but not your environ
>>  (e.g. `/proc/self/environ`). That behavior is the default on
>
> I wonder if "cmdline" and "environ" would be better spelled out, as
> well, since the examples which immediately follow them give the
> necessary context.

Agreed.

>     other processes might be able to read your command-line
>     (e.g. `/proc/self/cmdline`), but not your environment
>     (e.g. `/proc/self/environ`).
>
> But perhaps that's outside the scope of this patch?

I don't think so; I'll include those.

>> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
>> @@ -1151,7 +1151,7 @@ will be stored via placeholder `%P`.
>>  This attribute controls the length of conflict markers left in
>> -the work tree file during a conflicted merge.  Only setting to
>> +the work tree file during a conflicted merge.  Only setting
>>  the value to a positive integer has any meaningful effect.
>
> Or, more simply:
>
>     Only a positive integer has a meaningful effect.

That's better, thanks.

>> diff --git a/contrib/README b/contrib/README
>> @@ -24,14 +24,14 @@ lesser degree various foreign SCM interfaces, so you know the
>>  I expect that things that start their life in the contrib/ area
>> -to graduate out of contrib/ once they mature, either by becoming
>> +graduate out of contrib/ once they mature, either by becoming
>
> You probably want to add a comma after "area".

That would read awkward to me.  How about going the other way,

  I expect things that start their life in the contrib/ area
  to graduate out of contrib/ once they mature

instead?

> Do we want to correct the formatting of this pathname:
>
>     ...in the `contrib/` area...
>     ...out of `contrib/` once...
>
> or is that outside the scope of this patch?

I'd prefer not to: this is a plain-text README, no other markup present,
and I don't think the backquotes would help here.

>> diff --git a/strbuf.h b/strbuf.h
>> @@ -12,9 +12,9 @@
>> - * strbuf's are meant to be used with all the usual C string and memory
>> + * strbufs are meant to be used with all the usual C string and memory
>
> Alternatively:
>
>     strbuf is meant to be used...
>
>>   * APIs. Given that the length of the buffer is known, it's often better to
>> - * use the mem* functions than a str* one (memchr vs. strchr e.g.).
>> + * use the mem* functions than a str* one (e.g., memchr vs. strchr).
>>   * Though, one has to be careful about the fact that str* functions often
>>   * stop on NULs and that strbufs may have embedded NULs.
>
> Similar:
>
>     ... and that a strbuf may have...

Hm, not sure about this one.  I think I'd prefer keeping the plurals,
but it's not a strong preference.

>> diff --git a/t/README b/t/README
>> @@ -262,8 +262,8 @@ The argument for --run, <test-selector>, is a list of description
>>  suite to include (or exclude, if negated) in the run.  A range is two
>> -numbers separated with a dash and matches a range of tests with both
>> -ends been included.  You may omit the first or the second number to
>> +numbers separated with a dash and matches an inclusive range of tests
>> +to run.  You may omit the first or the second number to
>
> Not the fault of this patch, but "matches" seems an odd choice.
> Perhaps "specifies" would feel more natural.

Indeed, will fix.

>>  The argument to --run is split on commas into separate strings,
>> @@ -579,11 +579,10 @@ This test harness library does the following things:
>> -Here are some recommented styles when writing test case.
>
> Do you want to fix the spelling error while you're here or is that
> done in a later patch?
>
>     s/recommented/recommended/

You really had me double-checking both the branch and the patch I sent
here. :-D Unless I'm very much missing something, that line is _removed_
by the patch (seemed redundant given the title immediately preceding
it).

>> - - Keep test title the same line with test helper function itself.
>> + - Keep test titles and helper function invocations on the same line.
>
> This would be clearer if it was switched around. Either:
>
>     Keep the test_expect_* function call and test title on the same line.
>
> or, more verbosely:
>
>    Place the test title on the same line as the test_expect_* call
>    which precedes it.

I'll take your first suggestion.

Thank you for the review!

-- 
Štěpán

Re: [PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

[Štěpán Němec]

On Tue, 3 Oct 2023 14:33:39 -0400
Eric Sunshine wrote:

> On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote:
>> There's even an example of such usage in the README.
>>
>> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
>> ---
>> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
>> @@ -9,7 +9,7 @@ The <mode> parameter is one of:
>>
>>  diff: elements are diff hunks. Arguments are given to diff.
>>
>> -merge: elements are merge conflicts. Arguments are ignored.
>> +merge: elements are merge conflicts. Arguments are given to ls-files -u.
>
> Should "ls-files -u" be formatted with backticks?
>
>     Arguments are passed to `git ls-files -u`.

My preference is against this (I don't like markup in plain-text files),
although, unlike the contrib README case in 1/5, here there _are_ some
pre-existing backquotes; but the usage is inconsistent.  If we want to
unify one way or the other, I'd leave that for another patch, in any
case.

Thanks,

  Štěpán

Re: [PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> There's even an example of such usage in the README.
>>
>> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
>> ---
>> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
>> @@ -9,7 +9,7 @@ The <mode> parameter is one of:
>>
>>  diff: elements are diff hunks. Arguments are given to diff.
>>
>> -merge: elements are merge conflicts. Arguments are ignored.
>> +merge: elements are merge conflicts. Arguments are given to ls-files -u.
>
> Should "ls-files -u" be formatted with backticks?
>
>     Arguments are passed to `git ls-files -u`.

Probably not in this case, as this is end-user visible help message
that is not formatted but given to the terminal.

The whole preimage looks like this:

    usage: git jump [--stdout] <mode> [<args>]

    Jump to interesting elements in an editor.
    The <mode> parameter is one of:

    diff: elements are diff hunks. Arguments are given to diff.

    merge: elements are merge conflicts. Arguments are ignored.

    grep: elements are grep hits. Arguments are given to git grep or, if
          configured, to the command in `jump.grepCmd`.

    ws: elements are whitespace errors. Arguments are given to diff --check.

    If the optional argument `--stdout` is given, print the quickfix
    lines to standard output instead of feeding it to the editor.

and it is already a mixture.  "given to `git grep`" is not quoted,
neither is "given to `diff --check`" or "given to `diff`"

I think rule for help/usage messages should be that 

 - anything that the end-user may want to cut&paste should be left
   alone to make it easier to cut, 

 - but at the same time the message should make it clear which part
   of a sentence is what, 

Clicking on `--stdout` or `jump.grepCmd` does not include the
surrounding quotes, at least in my environment, so the use of
backquotes in these places satisfy the two goals, it seems.

Unlike `--stdout` and `jump.grepCmd`, all other things that are not
quoted, including the one that is added by this patch (i.e.,
"ls-files -u"), are something the end-user needs to cut and paste in
reaction to seeing this error message, so as long as they are
understandable in the sentences they appear in, I think they are
fine.

If we wanted to standardize, we may start to encourage consistent
use of quoting, but I do not think it should be part of this topic.

Thanks for being careful and thoughtful.

Re: [PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Unlike `--stdout` and `jump.grepCmd`, all other things that are not
> quoted, including the one that is added by this patch (i.e.,
> "ls-files -u"), are something the end-user needs to cut and paste in

"are" -> "are NOT".  Sorry for the noise.

> reaction to seeing this error message, so as long as they are
> understandable in the sentences they appear in, I think they are
> fine.
>
> If we wanted to standardize, we may start to encourage consistent
> use of quoting, but I do not think it should be part of this topic.
>
> Thanks for being careful and thoughtful.

Re: [PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[Junio C Hamano]

Štěpán Němec <stepnem@smrk.net> writes:

> Come to think of it, 'doc: fix some typos, grammar and wording issues'
> might have made sense to begin with; I don't suppose C header comments
> are off-limits to doc:.

Yup, they do count as part of developer documentation.

>>> diff --git a/contrib/README b/contrib/README
>>> @@ -24,14 +24,14 @@ lesser degree various foreign SCM interfaces, so you know the
>>>  I expect that things that start their life in the contrib/ area
>>> -to graduate out of contrib/ once they mature, either by becoming
>>> +graduate out of contrib/ once they mature, either by becoming
>>
>> You probably want to add a comma after "area".
>
> That would read awkward to me.  How about going the other way,
>
>   I expect things that start their life in the contrib/ area
>   to graduate out of contrib/ once they mature
>
> instead?

That reads well.  I do not recall whom "I" in this sentence refers
to, but if this were me talking about my wish, then yes, I expect
them to graduate once they mature, and the ">>>" quoted change to
drop "to" does not sound grammatical.

Thanks for working on improving the documentation, thanks for
reviewing, and thanks for working well together.

Re: [PATCH 1/5] Fix some typos, grammar or wording issues in the documentation

[Eric Sunshine]

On Tue, Oct 3, 2023 at 4:09 PM Štěpán Němec <stepnem@smrk.net> wrote:
> On Tue, 3 Oct 2023 14:30:38 -0400 Eric Sunshine wrote:
> > On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote:
> >> diff --git a/contrib/README b/contrib/README
> >> @@ -24,14 +24,14 @@ lesser degree various foreign SCM interfaces, so you know the
> >>  I expect that things that start their life in the contrib/ area
> >> -to graduate out of contrib/ once they mature, either by becoming
> >> +graduate out of contrib/ once they mature, either by becoming
> >
> > You probably want to add a comma after "area".
>
> That would read awkward to me.  How about going the other way,
>
>   I expect things that start their life in the contrib/ area
>   to graduate out of contrib/ once they mature
>
> instead?

Sounds fine.

> >> @@ -579,11 +579,10 @@ This test harness library does the following things:
> >> -Here are some recommented styles when writing test case.
> >
> > Do you want to fix the spelling error while you're here or is that
> > done in a later patch?
> >
> >     s/recommented/recommended/
>
> You really had me double-checking both the branch and the patch I sent
> here. :-D Unless I'm very much missing something, that line is _removed_
> by the patch (seemed redundant given the title immediately preceding
> it).

Ugh, so it is. Sorry for the noise.

> >> - - Keep test title the same line with test helper function itself.
> >> + - Keep test titles and helper function invocations on the same line.
> >
> > This would be clearer if it was switched around. Either:
> >
> >     Keep the test_expect_* function call and test title on the same line.
> >
> > or, more verbosely:
> >
> >    Place the test title on the same line as the test_expect_* call
> >    which precedes it.
>
> I'll take your first suggestion.

I like the first suggestion better too.

[PATCH v2 1/5] doc: fix some typos, grammar and wording issues

[Štěpán Němec]

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
v2: Feedback from Eric and Junio, implement most of Eric's suggestions.
Range-diff with two inline comments follows:

1:  2ab1bdb9a999 ! 1:  6c2766f9471f Fix some typos, grammar or wording issues in the documentation
    @@ Metadata
     Author: Štěpán Němec <stepnem@smrk.net>
     
      ## Commit message ##
    -    Fix some typos, grammar or wording issues in the documentation
    +    doc: fix some typos, grammar and wording issues
     
      ## Documentation/SubmittingPatches ##
     @@ Documentation/SubmittingPatches: mailing list{security-ml}, instead of the public mailing list.
    @@ Documentation/SubmittingPatches: help you find out who they are.
      
      [[patch-status]]
     
    + ## Documentation/config/transfer.txt ##
    +@@ Documentation/config/transfer.txt: exposure, e.g. because:
    +   system.
    + * The git programs will pass the full URL to one another as arguments
    +   on the command-line, meaning the credentials will be exposed to other
    +-  users on OS's or systems that allow other users to see the full
    ++  unprivileged users on systems that allow them to see the full
    +   process list of other users. On linux the "hidepid" setting
    +   documented in procfs(5) allows for configuring this behavior.
    + +
    +

Another "OS's" missed in v1, plus an attempt to fix the triple "other
users" in a single sentence.

      ## Documentation/diff-options.txt ##
     @@ Documentation/diff-options.txt: ifndef::git-format-patch[]
      
    @@ Documentation/git.txt: foo.bar= ...`) sets `foo.bar` to the empty string which `
      +
      This is useful for cases where you want to pass transitory
     -configuration options to git, but are doing so on OS's where
    -+configuration options to git, but are doing so on OSes where
    - other processes might be able to read your cmdline
    - (e.g. `/proc/self/cmdline`), but not your environ
    +-other processes might be able to read your cmdline
    +-(e.g. `/proc/self/cmdline`), but not your environ
    ++configuration options to git, but are doing so on operating systems
    ++where other processes might be able to read your command line
    ++(e.g. `/proc/self/cmdline`), but not your environment
      (e.g. `/proc/self/environ`). That behavior is the default on
    + Linux, but may not be on your system.
    + +
     
      ## Documentation/gitattributes.txt ##
     @@ Documentation/gitattributes.txt: will be stored via placeholder `%P`.
    @@ Documentation/gitattributes.txt: will be stored via placeholder `%P`.
      
      This attribute controls the length of conflict markers left in
     -the work tree file during a conflicted merge.  Only setting to
    -+the work tree file during a conflicted merge.  Only setting
    - the value to a positive integer has any meaningful effect.
    +-the value to a positive integer has any meaningful effect.
    ++the work tree file during a conflicted merge.  Only a positive
    ++integer has a meaningful effect.
      
      For example, this line in `.gitattributes` can be used to tell the merge
    + machinery to leave much longer (instead of the usual 7-character-long)
     
      ## Documentation/giteveryday.txt ##
     @@ Documentation/giteveryday.txt: without a formal "merging". Or longhand +
    @@ Documentation/giteveryday.txt: without a formal "merging". Or longhand +
      
     
      ## contrib/README ##
    -@@ contrib/README: lesser degree various foreign SCM interfaces, so you know the
    +@@ contrib/README: This is the same way as how I have been treating gitk, and to a
    + lesser degree various foreign SCM interfaces, so you know the
      drill.
      
    - I expect that things that start their life in the contrib/ area
    --to graduate out of contrib/ once they mature, either by becoming
    -+graduate out of contrib/ once they mature, either by becoming
    +-I expect that things that start their life in the contrib/ area
    ++I expect things that start their life in the contrib/ area
    + to graduate out of contrib/ once they mature, either by becoming
      projects on their own, or moving to the toplevel directory.  On
      the other hand, I expect I'll be proposing removal of disused
    - and inactive ones from time to time.
    +@@ contrib/README: and inactive ones from time to time.
      
      If you have new things to add to this area, please first propose
      it on the git mailing list, and after a list discussion proves
    @@ contrib/README: lesser degree various foreign SCM interfaces, so you know the
      audience -- for example I do not work with projects whose
      upstream is svn, so I have no use for git-svn myself, but it is
     
    + ## fsmonitor--daemon.h ##
    +@@ fsmonitor--daemon.h: struct fsmonitor_daemon_state {
    +  * to only mean an external GITDIR referenced by a ".git" file.
    +  *
    +  * The platform FS event backends will receive watch-specific
    +- * relative paths (except for those OS's that always emit absolute
    ++ * relative paths (except for those OSes that always emit absolute
    +  * paths).  We use the following enum and routines to classify each
    +  * path so that we know how to handle it.  There is a slight asymmetry
    +  * here because ".git/" is inside the working directory and the
    +

Ended up only fixing the spelling here: expanding the abbreviation
seemed unnecessarily intrusive given the context, and I'd say the
abbreviation pragmatics is different in a header file compared to the
main user-facing docs like git.txt above.

      ## strbuf.h ##
     @@
      struct string_list;
    @@ t/README: The argument for --run, <test-selector>, is a list of description
      suite to include (or exclude, if negated) in the run.  A range is two
     -numbers separated with a dash and matches a range of tests with both
     -ends been included.  You may omit the first or the second number to
    -+numbers separated with a dash and matches an inclusive range of tests
    ++numbers separated with a dash and specifies an inclusive range of tests
     +to run.  You may omit the first or the second number to
      mean "from the first test" or "up to the very last test" respectively.
      
    @@ t/README: This test harness library does the following things:
     -Here are some recommented styles when writing test case.
      
     - - Keep test title the same line with test helper function itself.
    -+ - Keep test titles and helper function invocations on the same line.
    ++ - Keep the test_expect_* function call and test title on
    ++   the same line.
      
     -   Take test_expect_success helper for example, write it like:
     +   For example, with test_expect_success, write it like:
2:  9c2c2b5f0574 = 2:  64bed10be547 doc/diff-options: improve wording of the log.diffMerges mention
3:  2636e1bf42ad = 3:  fd8544c26690 git-jump: admit to passing merge mode args to ls-files
4:  5fa09b64efaf = 4:  42ee0a9b914a doc/gitk: s/sticked/stuck/
5:  530abe377ad2 = 5:  23840e0368f1 t/README: fix multi-prerequisite example

 Documentation/SubmittingPatches   | 10 +++++-----
 Documentation/config/transfer.txt |  2 +-
 Documentation/diff-options.txt    |  2 +-
 Documentation/git-branch.txt      |  2 +-
 Documentation/git-range-diff.txt  |  2 +-
 Documentation/git.txt             |  6 +++---
 Documentation/gitattributes.txt   |  4 ++--
 Documentation/giteveryday.txt     |  2 +-
 contrib/README                    |  4 ++--
 fsmonitor--daemon.h               |  2 +-
 strbuf.h                          |  8 ++++----
 t/README                          | 31 +++++++++++++++----------------
 12 files changed, 37 insertions(+), 38 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 973d7a81d449..1259549cd488 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -393,8 +393,8 @@ mailing list{security-ml}, instead of the public mailing list.
 
 Learn to use format-patch and send-email if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
-your existing e-mail client that is optimized for "multipart/*" mime
-type e-mails to corrupt and render your patches unusable.
+your existing e-mail client (often optimized for "multipart/*" MIME
+type e-mails) might render your patches unusable.
 
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
@@ -515,8 +515,8 @@ repositories.
 
 	git://git.ozlabs.org/~paulus/gitk
 
-   Those who are interested in improve gitk can volunteer to help Paul
-   in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
+   Those who are interested in improving gitk can volunteer to help Paul
+   maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
 
 - `po/` comes from the localization coordinator, Jiang Xin:
 
@@ -556,7 +556,7 @@ help you find out who they are.
 
 In any time between the (2)-(3) cycle, the maintainer may pick it up
 from the list and queue it to `seen`, in order to make it easier for
-people play with it without having to pick up and apply the patch to
+people to play with it without having to pick up and apply the patch to
 their trees themselves.
 
 [[patch-status]]
diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
index c3ac767d1e4d..1cbf477e5cfb 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.txt
@@ -21,7 +21,7 @@ exposure, e.g. because:
   system.
 * The git programs will pass the full URL to one another as arguments
   on the command-line, meaning the credentials will be exposed to other
-  users on OS's or systems that allow other users to see the full
+  unprivileged users on systems that allow them to see the full
   process list of other users. On linux the "hidepid" setting
   documented in procfs(5) allows for configuring this behavior.
 +
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 35fae7c87c8a..ee256ec077be 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -301,7 +301,7 @@ ifndef::git-format-patch[]
 
 -z::
 ifdef::git-log[]
-	Separate the commits with NULs instead of with new newlines.
+	Separate the commits with NULs instead of newlines.
 +
 Also, when `--raw` or `--numstat` has been given, do not munge
 pathnames and use NULs as output field terminators.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index d207da9101a5..4395aa935438 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -324,7 +324,7 @@ superproject's "origin/main", but tracks the submodule's "origin/main".
 	multiple times, in which case the last key becomes the primary
 	key. The keys supported are the same as those in `git
 	for-each-ref`. Sort order defaults to the value configured for the
-	`branch.sort` variable if exists, or to sorting based on the
+	`branch.sort` variable if it exists, or to sorting based on the
 	full refname (including `refs/...` prefix). This lists
 	detached HEAD (if present) first, then local branches and
 	finally remote-tracking branches. See linkgit:git-config[1].
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index 0b393715d707..6c728dbe44b2 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -166,7 +166,7 @@ A typical output of `git range-diff` would look like this:
 
 In this example, there are 3 old and 3 new commits, where the developer
 removed the 3rd, added a new one before the first two, and modified the
-commit message of the 2nd commit as well its diff.
+commit message of the 2nd commit as well as its diff.
 
 When the output goes to a terminal, it is color-coded by default, just
 like regular `git diff`'s output. In addition, the first line (adding a
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 11228956cd5e..9aeabde26200 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -96,9 +96,9 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 	to avoid ambiguity with `<name>` containing one.
 +
 This is useful for cases where you want to pass transitory
-configuration options to git, but are doing so on OS's where
-other processes might be able to read your cmdline
-(e.g. `/proc/self/cmdline`), but not your environ
+configuration options to git, but are doing so on operating systems
+where other processes might be able to read your command line
+(e.g. `/proc/self/cmdline`), but not your environment
 (e.g. `/proc/self/environ`). That behavior is the default on
 Linux, but may not be on your system.
 +
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 6deb89a29677..8c1793c14880 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -1151,8 +1151,8 @@ will be stored via placeholder `%P`.
 ^^^^^^^^^^^^^^^^^^^^^^
 
 This attribute controls the length of conflict markers left in
-the work tree file during a conflicted merge.  Only setting to
-the value to a positive integer has any meaningful effect.
+the work tree file during a conflicted merge.  Only a positive
+integer has a meaningful effect.
 
 For example, this line in `.gitattributes` can be used to tell the merge
 machinery to leave much longer (instead of the usual 7-character-long)
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.txt
index faba2ef0881c..f74a33fb35b9 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.txt
@@ -229,7 +229,7 @@ without a formal "merging". Or longhand +
   git am -3 -k`
 
 An alternate participant submission mechanism is using the
-`git request-pull` or pull-request mechanisms (e.g as used on
+`git request-pull` or pull-request mechanisms (e.g. as used on
 GitHub (www.github.com) to notify your upstream of your
 contribution.
 
diff --git a/contrib/README b/contrib/README
index 05f291c1f1d3..21d3d0e7dee4 100644
--- a/contrib/README
+++ b/contrib/README
@@ -23,7 +23,7 @@ This is the same way as how I have been treating gitk, and to a
 lesser degree various foreign SCM interfaces, so you know the
 drill.
 
-I expect that things that start their life in the contrib/ area
+I expect things that start their life in the contrib/ area
 to graduate out of contrib/ once they mature, either by becoming
 projects on their own, or moving to the toplevel directory.  On
 the other hand, I expect I'll be proposing removal of disused
@@ -31,7 +31,7 @@ and inactive ones from time to time.
 
 If you have new things to add to this area, please first propose
 it on the git mailing list, and after a list discussion proves
-there are some general interests (it does not have to be a
+there is general interest (it does not have to be a
 list-wide consensus for a tool targeted to a relatively narrow
 audience -- for example I do not work with projects whose
 upstream is svn, so I have no use for git-svn myself, but it is
diff --git a/fsmonitor--daemon.h b/fsmonitor--daemon.h
index 70d776c54f6d..673f80d2aad0 100644
--- a/fsmonitor--daemon.h
+++ b/fsmonitor--daemon.h
@@ -99,7 +99,7 @@ struct fsmonitor_daemon_state {
  * to only mean an external GITDIR referenced by a ".git" file.
  *
  * The platform FS event backends will receive watch-specific
- * relative paths (except for those OS's that always emit absolute
+ * relative paths (except for those OSes that always emit absolute
  * paths).  We use the following enum and routines to classify each
  * path so that we know how to handle it.  There is a slight asymmetry
  * here because ".git/" is inside the working directory and the
diff --git a/strbuf.h b/strbuf.h
index fd43c46433a4..e959caca876a 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -12,9 +12,9 @@
 struct string_list;
 
 /**
- * strbuf's are meant to be used with all the usual C string and memory
+ * strbufs are meant to be used with all the usual C string and memory
  * APIs. Given that the length of the buffer is known, it's often better to
- * use the mem* functions than a str* one (memchr vs. strchr e.g.).
+ * use the mem* functions than a str* one (e.g., memchr vs. strchr).
  * Though, one has to be careful about the fact that str* functions often
  * stop on NULs and that strbufs may have embedded NULs.
  *
@@ -24,7 +24,7 @@ struct string_list;
  * strbufs have some invariants that are very important to keep in mind:
  *
  *  - The `buf` member is never NULL, so it can be used in any usual C
- *    string operations safely. strbuf's _have_ to be initialized either by
+ *    string operations safely. strbufs _have_ to be initialized either by
  *    `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
  *
  *    Do *not* assume anything on what `buf` really is (e.g. if it is
@@ -37,7 +37,7 @@ struct string_list;
  *
  *  - The `buf` member is a byte array that has at least `len + 1` bytes
  *    allocated. The extra byte is used to store a `'\0'`, allowing the
- *    `buf` member to be a valid C-string. Every strbuf function ensure this
+ *    `buf` member to be a valid C-string. All strbuf functions ensure this
  *    invariant is preserved.
  *
  *    NOTE: It is OK to "play" with the buffer directly if you work it this
diff --git a/t/README b/t/README
index 61080859899b..2ef89785f831 100644
--- a/t/README
+++ b/t/README
@@ -262,8 +262,8 @@ The argument for --run, <test-selector>, is a list of description
 substrings or globs or individual test numbers or ranges with an
 optional negation prefix (of '!') that define what tests in a test
 suite to include (or exclude, if negated) in the run.  A range is two
-numbers separated with a dash and matches a range of tests with both
-ends been included.  You may omit the first or the second number to
+numbers separated with a dash and specifies an inclusive range of tests
+to run.  You may omit the first or the second number to
 mean "from the first test" or "up to the very last test" respectively.
 
 The argument to --run is split on commas into separate strings,
@@ -274,10 +274,10 @@ text that you want to match includes a comma, use the glob character
 on all tests that match either the glob *rebase* or the glob
 *merge?cherry-pick*.
 
-If --run starts with an unprefixed number or range the initial
-set of tests to run is empty. If the first item starts with '!'
+If --run starts with an unprefixed number or range, the initial
+set of tests to run is empty.  If the first item starts with '!',
 all the tests are added to the initial set.  After initial set is
-determined every test number or range is added or excluded from
+determined, every test number or range is added or excluded from
 the set one by one, from left to right.
 
 For example, to run only tests up to a specific test (21), one
@@ -579,11 +579,11 @@ This test harness library does the following things:
 
 Recommended style
 -----------------
-Here are some recommented styles when writing test case.
 
- - Keep test title the same line with test helper function itself.
+ - Keep the test_expect_* function call and test title on
+   the same line.
 
-   Take test_expect_success helper for example, write it like:
+   For example, with test_expect_success, write it like:
 
   test_expect_success 'test title' '
       ... test body ...
@@ -595,10 +595,9 @@ Here are some recommented styles when writing test case.
       'test title' \
       '... test body ...'
 
+ - End the line with an opening single quote.
 
- - End the line with a single quote.
-
- - Indent the body of here-document, and use "<<-" instead of "<<"
+ - Indent here-document bodies, and use "<<-" instead of "<<"
    to strip leading TABs used for indentation:
 
   test_expect_success 'test something' '
@@ -624,7 +623,7 @@ Here are some recommented styles when writing test case.
   '
 
  - Quote or escape the EOF delimiter that begins a here-document if
-   there is no parameter and other expansion in it, to signal readers
+   there is no parameter or other expansion in it, to signal readers
    that they can skim it more casually:
 
   cmd <<-\EOF
@@ -638,7 +637,7 @@ Do's & don'ts
 Here are a few examples of things you probably should and shouldn't do
 when writing tests.
 
-Here are the "do's:"
+The "do's:"
 
  - Put all code inside test_expect_success and other assertions.
 
@@ -1237,8 +1236,8 @@ and it knows that the object ID of an empty tree is a certain
 because the things the very basic core test tries to achieve is
 to serve as a basis for people who are changing the Git internals
 drastically.  For these people, after making certain changes,
-not seeing failures from the basic test _is_ a failure.  And
-such drastic changes to the core Git that even changes these
+not seeing failures from the basic test _is_ a failure.  Any
+Git core changes so drastic that they change even these
 otherwise supposedly stable object IDs should be accompanied by
 an update to t0000-basic.sh.
 
@@ -1248,7 +1247,7 @@ knowledge of the core Git internals.  If all the test scripts
 hardcoded the object IDs like t0000-basic.sh does, that defeats
 the purpose of t0000-basic.sh, which is to isolate that level of
 validation in one place.  Your test also ends up needing
-updating when such a change to the internal happens, so do _not_
+an update whenever the internals change, so do _not_
 do it and leave the low level of validation to t0000-basic.sh.
 
 Test coverage

base-commit: d0e8084c65cbf949038ae4cc344ac2c2efd77415
-- 
2.42.0

[PATCH v2 2/5] doc/diff-options: improve wording of the log.diffMerges mention

[Štěpán Němec]

Fix the grammar ("which default value is") and reword to match other
similar descriptions (say "configuration variable" instead of
"parameter", link to git-config(1)).

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/diff-options.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ee256ec077be..48a5012748dd 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -53,9 +53,9 @@ ifdef::git-log[]
 -m:::
 	This option makes diff output for merge commits to be shown in
 	the default format. `-m` will produce the output only if `-p`
-	is given as well. The default format could be changed using
-	`log.diffMerges` configuration parameter, which default value
-	is `separate`.
+	is given as well. The default format can be specified using
+	the configuration variable `log.diffMerges` (see
+	linkgit:git-config[1]). It defaults to `separate`.
 +
 --diff-merges=first-parent:::
 --diff-merges=1:::
-- 
2.42.0

[PATCH v2 3/5] git-jump: admit to passing merge mode args to ls-files

[Štěpán Němec]

There's even an example of such usage in the README.

Fixes: 67ba13e5a4b2 ("git-jump: pass "merge" arguments to ls-files")
Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 contrib/git-jump/git-jump | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
index 40c4b0d11107..47e0c557e63f 100755
--- a/contrib/git-jump/git-jump
+++ b/contrib/git-jump/git-jump
@@ -9,7 +9,7 @@ The <mode> parameter is one of:
 
 diff: elements are diff hunks. Arguments are given to diff.
 
-merge: elements are merge conflicts. Arguments are ignored.
+merge: elements are merge conflicts. Arguments are given to ls-files -u.
 
 grep: elements are grep hits. Arguments are given to git grep or, if
       configured, to the command in `jump.grepCmd`.
-- 
2.42.0

[PATCH v2 4/5] doc/gitk: s/sticked/stuck/

[Štěpán Němec]

The terminology was changed in b0d12fc9b23a (Use the word 'stuck'
instead of 'sticked').

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 Documentation/gitk.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index d50e9ed10e04..c2213bb77b38 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -26,7 +26,7 @@ changes each commit introduces are shown.  Finally, it supports some
 gitk-specific options.
 
 gitk generally only understands options with arguments in the
-'sticked' form (see linkgit:gitcli[7]) due to limitations in the
+'stuck' form (see linkgit:gitcli[7]) due to limitations in the
 command-line parser.
 
 rev-list options and arguments
-- 
2.42.0

[PATCH v2 5/5] t/README: fix multi-prerequisite example

[Štěpán Němec]

With the broken quoting the test wouldn't even parse correctly, but
there's also the '==' instead of POSIX '=' (of the shells I tested,
busybox ash, bash and ksh (93 and OpenBSD) accept '==', dash and zsh do
not), and 'print 2' from Python 2 days.

(I assume the test failing due to 3 != 4 is intentional or immaterial.)

Fixes: 93a572461386 ("test-lib: Add support for multiple test prerequisites")
Signed-off-by: Štěpán Němec <stepnem@smrk.net>
---
 t/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/README b/t/README
index 2ef89785f831..a0ebe294848d 100644
--- a/t/README
+++ b/t/README
@@ -887,7 +887,7 @@ see test-lib-functions.sh for the full list and their options.
    rare case where your test depends on more than one:
 
 	test_expect_success PERL,PYTHON 'yo dawg' \
-	    ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" '
+	    ' test $(perl -E '\''print eval "1 +" . qx[python -c "print(2)"]'\'') = "4" '
 
  - test_expect_failure [<prereq>] <message> <script>
 
-- 
2.42.0

Re: [PATCH v2 1/5] doc: fix some typos, grammar and wording issues

[Junio C Hamano]

Štěpán Němec <stepnem@smrk.net> writes:

> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
> ---
> v2: Feedback from Eric and Junio, implement most of Eric's suggestions.
> Range-diff with two inline comments follows:

Looking good.

The above comment was meant to apply to the whole series, but
because you lack the [0/5] cover letter, I am replying to [1/5].
You may want to run git-format-patch with --cover-letter when
sending a series with multiple patches.

Will queue.  Thanks.

Re: [PATCH v2 1/5] doc: fix some typos, grammar and wording issues

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Štěpán Němec <stepnem@smrk.net> writes:
>
>> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
>> ---
>> v2: Feedback from Eric and Junio, implement most of Eric's suggestions.
>> Range-diff with two inline comments follows:
>
> Looking good.
>
> The above comment was meant to apply to the whole series, but
> because you lack the [0/5] cover letter, I am replying to [1/5].
> You may want to run git-format-patch with --cover-letter when
> sending a series with multiple patches.
>
> Will queue.  Thanks.

I wanted to see an independent review from others before deciding to
merge this to 'next', but unfortunately we seem to lack review
bandwidth.  I've given another scan of the whole thing and did not
spot anything glaringly wrong (which is not surprising), so let's
merge it down to 'next' and if anybody finds a bad rewrite in these
changes later, let's let them update on top.

Thanks.