git-config doc: variables sorting bug

git-config doc: variables sorting bug

[Bruno Haible]

Hi,

In https://git-scm.com/docs/git-config the variables (advice.* ...
worktree.guessRemote) are apparently meant to be in alphabetical order.

However,
  filter.<driver>.clean
  filter.<driver>.smudge
come after format.*. They should come before format.*, since 'i' < 'o'.

Bruno

[PATCH] docs: sort configuration variable groupings alphabetically

[Eric Sunshine]

From: Eric Sunshine <sunshine@sunshineco.com>

By and large, variable groupings in Documentation/config.txt are sorted
alphabetically, though a few are not. Those outliers make it more
difficult to find a specific grouping when quickly running an eye over
the list to locate a variable of interest. Address this shortcoming by
sorting the groupings alphabetically.

NOTE: This change only sorts the top-level groupings (i.e. "core.*"
comes after "completion.*"); it does not touch the ordering of variables
within each group since variables within individual groups might
intentionally be ordered in some other fashion (such as
most-common-first or most-important-first).

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---
 Documentation/config.txt | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index e3a74dd1c1..782c2bab90 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -369,20 +369,18 @@ inventing new variables for use in your own tool, make sure their
 names do not conflict with those that are used by Git itself and
 other popular tools, and describe them in your documentation.
 
-include::config/advice.txt[]
-
-include::config/attr.txt[]
-
-include::config/core.txt[]
-
 include::config/add.txt[]
 
+include::config/advice.txt[]
+
 include::config/alias.txt[]
 
 include::config/am.txt[]
 
 include::config/apply.txt[]
 
+include::config/attr.txt[]
+
 include::config/blame.txt[]
 
 include::config/branch.txt[]
@@ -405,10 +403,12 @@ include::config/commit.txt[]
 
 include::config/commitgraph.txt[]
 
-include::config/credential.txt[]
-
 include::config/completion.txt[]
 
+include::config/core.txt[]
+
+include::config/credential.txt[]
+
 include::config/diff.txt[]
 
 include::config/difftool.txt[]
@@ -421,10 +421,10 @@ include::config/feature.txt[]
 
 include::config/fetch.txt[]
 
-include::config/format.txt[]
-
 include::config/filter.txt[]
 
+include::config/format.txt[]
+
 include::config/fsck.txt[]
 
 include::config/fsmonitor--daemon.txt[]
@@ -435,10 +435,10 @@ include::config/gitcvs.txt[]
 
 include::config/gitweb.txt[]
 
-include::config/grep.txt[]
-
 include::config/gpg.txt[]
 
+include::config/grep.txt[]
+
 include::config/gui.txt[]
 
 include::config/guitool.txt[]
@@ -519,10 +519,10 @@ include::config/splitindex.txt[]
 
 include::config/ssh.txt[]
 
-include::config/status.txt[]
-
 include::config/stash.txt[]
 
+include::config/status.txt[]
+
 include::config/submodule.txt[]
 
 include::config/tag.txt[]
-- 
2.44.0

Re: git-config doc: variables sorting bug

[Eric Sunshine]

On Wed, Feb 28, 2024 at 5:15 AM Bruno Haible <bruno@clisp.org> wrote:
> In https://git-scm.com/docs/git-config the variables (advice.* ...
> worktree.guessRemote) are apparently meant to be in alphabetical order.
>
> However,
>   filter.<driver>.clean
>   filter.<driver>.smudge
> come after format.*. They should come before format.*, since 'i' < 'o'.

A possible fix has been posted here:
https://lore.kernel.org/git/20240229190229.20222-1-ericsunshine@charter.net/

Re: [PATCH] docs: sort configuration variable groupings alphabetically

[Junio C Hamano]

Eric Sunshine <ericsunshine@charter.net> writes:

> NOTE: This change only sorts the top-level groupings (i.e. "core.*"
> comes after "completion.*"); it does not touch the ordering of variables
> within each group since variables within individual groups might
> intentionally be ordered in some other fashion (such as
> most-common-first or most-important-first).

I think this is a useful first step.

It is tempting to think, in this day and age, searching in a
document is so easy to start with a single keystroke (either ^F in a
browser, or '/' in a pager) that the ordering of entries does not
matter as much as it used to, but the reader may not know exactly
what variable they are looking for, and a predictable ordering helps
while they are browsing the list.

Will queue.  Thanks.