[PATCH v2 1/2] Documentation/config: fix typos

[PATCH v2 1/2] Documentation/config: fix typos

[Andrew Kreimer]

Fix typos in documentation.

Signed-off-by: Andrew Kreimer <algonell@gmail.com>
---
 Documentation/config/extensions.txt | 2 +-
 Documentation/config/gc.txt         | 2 +-
 Documentation/config/remote.txt     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
index 38dce3df35..f0a784447d 100644
--- a/Documentation/config/extensions.txt
+++ b/Documentation/config/extensions.txt
@@ -9,7 +9,7 @@ work and will produce hard-to-diagnose issues.
 
 extensions.compatObjectFormat::
 
-	Specify a compatitbility hash algorithm to use.  The acceptable values
+	Specify a compatibility hash algorithm to use.  The acceptable values
 	are `sha1` and `sha256`.  The value specified must be different from the
 	value of extensions.objectFormat.  This allows client level
 	interoperability between git repositories whose objectFormat matches
diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt
index 1d4f9470ea..21d56db279 100644
--- a/Documentation/config/gc.txt
+++ b/Documentation/config/gc.txt
@@ -163,7 +163,7 @@ gc.repackFilterTo::
 	containing the filtered out objects. **WARNING:** The
 	specified location should be accessible, using for example the
 	Git alternates mechanism, otherwise the repo could be
-	considered corrupt by Git as it migh not be able to access the
+	considered corrupt by Git as it might not be able to access the
 	objects in that packfile. See the `--filter-to=<dir>` option
 	of linkgit:git-repack[1] and the `objects/info/alternates`
 	section of linkgit:gitrepository-layout[5].
diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
index 36e771556c..71d1fee835 100644
--- a/Documentation/config/remote.txt
+++ b/Documentation/config/remote.txt
@@ -50,7 +50,7 @@ remote.<name>.skipFetchAll::
 	If true, this remote will be skipped when updating
 	using linkgit:git-fetch[1], the `update` subcommand of
 	linkgit:git-remote[1], and ignored by the prefetch task
-	of `git maitenance`.
+	of `git maintenance`.
 
 remote.<name>.receivepack::
 	The default program to execute on the remote side when pushing.  See
-- 
2.39.5

[PATCH v2 2/2] Documentation: fix typos

[Andrew Kreimer]

Fix typos in documentation.

Signed-off-by: Andrew Kreimer <algonell@gmail.com>
---
 Documentation/BreakingChanges.txt        | 2 +-
 Documentation/DecisionMaking.txt         | 2 +-
 Documentation/gitformat-commit-graph.txt | 2 +-
 Documentation/gitweb.txt                 | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 2b64665694..112770a9da 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -117,7 +117,7 @@ Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
 
 * The git-pack-redundant(1) command can be used to remove redundant pack files.
   The subcommand is unusably slow and the reason why nobody reports it as a
-  performance bug is suspected to be the absense of users. We have nominated
+  performance bug is suspected to be the absence of users. We have nominated
   the command for removal and have started to emit a user-visible warning in
   c3b58472be (pack-redundant: gauge the usage before proposing its removal,
   2020-08-25) whenever the command is executed.
diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt
index dbb4c1f569..b43c472ae5 100644
--- a/Documentation/DecisionMaking.txt
+++ b/Documentation/DecisionMaking.txt
@@ -54,7 +54,7 @@ implementation, for very large changes).
 
 For non-technical decisions such as community norms or processes, it is up to
 the community as a whole to implement and sustain agreed-upon changes.
-The project leadership committe (PLC) may help the implementation of
+The project leadership committee (PLC) may help the implementation of
 policy decisions.
 
 
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 3e906e8030..14d1631234 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -122,7 +122,7 @@ All multi-byte numbers are in network byte order.
       for commits with corrected commit date offsets that cannot be
       stored within 31 bits.
     * Generation Data Overflow chunk is present only when Generation Data
-      chunk is present and atleast one corrected commit date offset cannot
+      chunk is present and at least one corrected commit date offset cannot
       be stored within 31 bits.
 
 ==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
index 56d24a30a3..5e2b491ec2 100644
--- a/Documentation/gitweb.txt
+++ b/Documentation/gitweb.txt
@@ -234,7 +234,7 @@ from the template during repository creation, usually installed in
 configuration variable, but the file takes precedence.
 
 category (or `gitweb.category`)::
-	Singe line category of a project, used to group projects if
+	Single line category of a project, used to group projects if
 	`$projects_list_group_categories` is enabled.  By default (file and
 	configuration variable absent), uncategorized projects are put in the
 	`$project_list_default_category` category.  You can use the
-- 
2.39.5

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Eric Sunshine]

On Mon, Sep 23, 2024 at 7:04 AM Andrew Kreimer <algonell@gmail.com> wrote:
> Fix typos in documentation.
>
> Signed-off-by: Andrew Kreimer <algonell@gmail.com>

Thanks. The changes in v2 of this series look fine.

In the future, to make life easier for reviewers, when rerolling a
patch series, please include a cover letter ("git format-patch
--cover-letter") and include the following in the cover letter:

* explain in your own words how the new version of the series differs
from the previous version

* provide a link to the cover-letter of the previous version (i.e.
https://lore.kernel.org/git/20240920082815.8192-1-algonell@gmail.com/)

* include a range-diff ("git format-patch --range-diff=") which
provides a mechanical representation of the differences between the
new version of the series and the previous version

Depending upon how dramatically the patch series changes from one
version to the next, the range-diff may end up being unreadable
gobbledygook, in which case you may instead want to include an
interdiff ("git format-patch --interdiff").

If you're rerolling just a single patch instead of a full patch
series, rather than including a cover letter, instead place the above
information in the commentary section of the patch (immediately below
the "---" line which follows your sign-off), and use "git format-patch
--range-diff" (or "--interdiff") to insert the mechanical differences
(which may appear in the commentary section or at the end of the
patch, depending upon which version of Git you're using).

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Eric Sunshine]

On Mon, Sep 23, 2024 at 1:51 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
> Thanks. The changes in v2 of this series look fine.
>
> In the future, to make life easier for reviewers, when rerolling a
> patch series, please include a cover letter ("git format-patch
> --cover-letter") and include the following in the cover letter:
>
> * explain in your own words how the new version of the series differs
> from the previous version
>
> * provide a link to the cover-letter of the previous version (i.e.
> https://lore.kernel.org/git/20240920082815.8192-1-algonell@gmail.com/)
>
> * include a range-diff ("git format-patch --range-diff=") which
> provides a mechanical representation of the differences between the
> new version of the series and the previous version

I forgot to mention email threading as a way to further help reviewers
and readers of the mailing list archive...

When sending a reroll of a series, use "git send-email --reply-to=" to
reference the cover letter of the previous version. If your email
client doesn't provide an easy way to access the ID of the previous
cover letter, you can grab it from the list archive. For instance,
consulting the above link:

    git send-email --reply-to='20240920082815.8192-1-algonell@gmail.com' ...

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Andrew Kreimer]

On Mon, Sep 23, 2024 at 01:59:16PM -0400, Eric Sunshine wrote:
> On Mon, Sep 23, 2024 at 1:51 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
> > Thanks. The changes in v2 of this series look fine.
> >
> > In the future, to make life easier for reviewers, when rerolling a
> > patch series, please include a cover letter ("git format-patch
> > --cover-letter") and include the following in the cover letter:
> >
> > * explain in your own words how the new version of the series differs
> > from the previous version
> >
> > * provide a link to the cover-letter of the previous version (i.e.
> > https://lore.kernel.org/git/20240920082815.8192-1-algonell@gmail.com/)
> >
> > * include a range-diff ("git format-patch --range-diff=") which
> > provides a mechanical representation of the differences between the
> > new version of the series and the previous version
> 
> I forgot to mention email threading as a way to further help reviewers
> and readers of the mailing list archive...
> 
> When sending a reroll of a series, use "git send-email --reply-to=" to
> reference the cover letter of the previous version. If your email
> client doesn't provide an easy way to access the ID of the previous
> cover letter, you can grab it from the list archive. For instance,
> consulting the above link:
> 
>     git send-email --reply-to='20240920082815.8192-1-algonell@gmail.com' ...

All noted, thank you!

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Kristoffer Haugsbakk]

Hi

On Mon, Sep 23, 2024, at 19:51, Eric Sunshine wrote:
> Depending upon how dramatically the patch series changes from one
> version to the next, the range-diff may end up being unreadable
> gobbledygook, in which case you may instead want to include an
> interdiff ("git format-patch --interdiff").

What’s the benefit of interdiff in that case? Neither
git-format-patch(1) nor git-range-diff(1) seems to discuss what the
differences between these two are.

-- 
Kristoffer Haugsbakk

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Eric Sunshine]

On Mon, Sep 23, 2024 at 2:44 PM Kristoffer Haugsbakk
<kristofferhaugsbakk@fastmail.com> wrote:
> On Mon, Sep 23, 2024, at 19:51, Eric Sunshine wrote:
> > Depending upon how dramatically the patch series changes from one
> > version to the next, the range-diff may end up being unreadable
> > gobbledygook, in which case you may instead want to include an
> > interdiff ("git format-patch --interdiff").
>
> What’s the benefit of interdiff in that case? Neither
> git-format-patch(1) nor git-range-diff(1) seems to discuss what the
> differences between these two are.

An interdiff is just a plain diff. If you have branch (or tag) "v1"
which is the original version of a patch series, and "v2" which is the
reroll of the series, then interdiff is simply:

    git diff v1 v2

Thus, it shows the difference between the final state of the code at
v1 and the state at v2. Interdiffs are easy to read because they are
just diffs. However, because they are only showing differences in file
content, they don't show changes to commit messages or new or removed
or reordered patches in a series.

A range-diff is a diff-of-diffs. It is very, very roughly similar to this:

    git format-patch -o v1-patches <common-base>..v1
    git format-patch -o v2-patches <common-base>..v2
    some-diff-dir-command v1-patches v2-patches

It shows the diff of the patches themselves, including changes to
commit messages and changes to changes, as well as inserted and
removed and reordered patches.

Range-diffs tend to be a good deal more difficult to read (at least at
first) but help show the evolution of the _patch series_ itself
between versions, whereas interdiffs show only the evolution of the
_code_ between versions. As a reviewer, if you're primarily interested
in how the code evolved, then interdiffs are much more easily
digested, but most reviewers are also interested in the holistic
aspects of a patch series for which range-diffs are more helpful. I
periodically include both range-diff and interdiffs in my rerolls.

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Kristoffer Haugsbakk]

On Mon, Sep 23, 2024, at 21:05, Eric Sunshine wrote:
> On Mon, Sep 23, 2024 at 2:44 PM Kristoffer Haugsbakk
> <kristofferhaugsbakk@fastmail.com> wrote:
>> On Mon, Sep 23, 2024, at 19:51, Eric Sunshine wrote:
>> > Depending upon how dramatically the patch series changes from one
>> > version to the next, the range-diff may end up being unreadable
>> > gobbledygook, in which case you may instead want to include an
>> > interdiff ("git format-patch --interdiff").
>>
>> What’s the benefit of interdiff in that case? Neither
>> git-format-patch(1) nor git-range-diff(1) seems to discuss what the
>> differences between these two are.
>
> An interdiff is just a plain diff. If you have branch (or tag) "v1"
> which is the original version of a patch series, and "v2" which is the
> reroll of the series, then interdiff is simply:
>
>     git diff v1 v2
>
> Thus, it shows the difference between the final state of the code at
> v1 and the state at v2. Interdiffs are easy to read because they are
> just diffs. However, because they are only showing differences in file
> content, they don't show changes to commit messages or new or removed
> or reordered patches in a series.
>
> A range-diff is a diff-of-diffs. It is very, very roughly similar to this:
>
>     git format-patch -o v1-patches <common-base>..v1
>     git format-patch -o v2-patches <common-base>..v2
>     some-diff-dir-command v1-patches v2-patches
>
> It shows the diff of the patches themselves, including changes to
> commit messages and changes to changes, as well as inserted and
> removed and reordered patches.
>
> Range-diffs tend to be a good deal more difficult to read (at least at
> first) but help show the evolution of the _patch series_ itself
> between versions, whereas interdiffs show only the evolution of the
> _code_ between versions. As a reviewer, if you're primarily interested
> in how the code evolved, then interdiffs are much more easily
> digested, but most reviewers are also interested in the holistic
> aspects of a patch series for which range-diffs are more helpful. I
> periodically include both range-diff and interdiffs in my rerolls.

Thanks for that.  I love when a good range-diff falls out of a
reroll—and I love the tool—but of course that can’t be expected out of
every reroll.

-- 
Kristoffer Haugsbakk

Re: [PATCH v2 1/2] Documentation/config: fix typos

[Kristoffer Haugsbakk]

On Mon, Sep 23, 2024, at 21:13, Kristoffer Haugsbakk wrote:
> On Mon, Sep 23, 2024, at 21:05, Eric Sunshine wrote:
>> [...]
>>
>> An interdiff is just a plain diff. If you have branch (or tag) "v1"
>> which is the original version of a patch series, and "v2" which is the
>> reroll of the series, then interdiff is simply:
>>
>>     git diff v1 v2
>>
>> Thus, it shows the difference between the final state of the code at
>> v1 and the state at v2. Interdiffs are easy to read because they are
>> just diffs. However, because they are only showing differences in file
>> content, they don't show changes to commit messages or new or removed
>> or reordered patches in a series.
>>
>> A range-diff is a diff-of-diffs. It is very, very roughly similar to this:
>>
>>     git format-patch -o v1-patches <common-base>..v1
>>     git format-patch -o v2-patches <common-base>..v2
>>     some-diff-dir-command v1-patches v2-patches
>>
>> It shows the diff of the patches themselves, including changes to
>> commit messages and changes to changes, as well as inserted and
>> removed and reordered patches.
>>
>> Range-diffs tend to be a good deal more difficult to read (at least at
>> first) but help show the evolution of the _patch series_ itself
>> between versions, whereas interdiffs show only the evolution of the
>> _code_ between versions. As a reviewer, if you're primarily interested
>> in how the code evolved, then interdiffs are much more easily
>> digested, but most reviewers are also interested in the holistic
>> aspects of a patch series for which range-diffs are more helpful. I
>> periodically include both range-diff and interdiffs in my rerolls.
>
> Thanks for that.  I love when a good range-diff falls out of a
> reroll—and I love the tool—but of course that can’t be expected out of
> every reroll.

I guess I shouldn’t be surprised.  But interdiff turned out to be really
useful.  Minor rerolls are really easy to read.  Such a pleasure to get
a quick sanity check before sending out a new round.

And then I also get to use range-diff at the same time—the cherry on top.

-- 
Kristoffer Haugsbakk