git-config doc: variables sorting bug

Bruno Haible· Feb 28, 2024, 10:12 UTC · lore

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

Eric Sunshine· Feb 29, 2024, 19:02 UTC · re: Bruno Haible · lore

[PATCH] docs: sort configuration variable groupings alphabetically

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

Junio C Hamano· Feb 29, 2024, 19:59 UTC · re: Eric Sunshine · lore

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

Eric Sunshine <ericsunshine@charter.net> writes:

Show 5 quoted lines

> 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.

Eric Sunshine· Feb 29, 2024, 19:08 UTC · re: Bruno Haible · lore

Re: git-config doc: variables sorting bug

On Wed, Feb 28, 2024 at 5:15 AM Bruno Haible <bruno@clisp.org> wrote:

Show 7 quoted lines

> 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/