Rename the inconsistent config keys

    noplainemail        enable-plain-email
    noheader            enable-header
    cache-root-ttl      cache-index-ttl
    cache-repo-ttl      cache-summary-ttl
    cache-scanrc-ttl    cache-scan-ttl
    agefile             age-file
    renamelimit         rename-limit
    extra-head-content  head-content

1 file changed, 126 insertions, 117 deletions

diff --git a/custom/cgitrc b/custom/cgitrc
index ba4ab66..c522b90 100644
--- a/custom/cgitrc
+++ b/custom/cgitrc
@@ -1,19 +1,18 @@
 # cgitrc reference configuration
 #
 # This file lists every cgit configuration option set to its default value.
-# Options with a real default are left uncommented at that default. Options
-# that are site-specific are commented out with a realistic example and their
-# default noted in the comment. Copied as-is, cgit behaves as if no option
-# were set.
+# Options with a real default are left uncommented at that default. Options that
+# are site-specific are commented out with a realistic example and their default
+# noted in the comment. Copied as-is, cgit behaves as if no option were set.
 #
-# Quick start. The one thing you must set to see any repositories is where
-# they live. Uncomment scan-path further down and point it at your git
-# directory, or list repositories by hand in the per-repository section at
-# the end of this file.
+# Quick start. The one thing you must set to see any repositories is where they
+# live. Uncomment scan-path further down and point it at your git directory, or
+# list repositories by hand in the per-repository section at the end of this
+# file.
 #
-# About pages (markdown, man and plain-text readmes) render through the
-# bundled about-render.lua about-filter, see the filter section below. Source
-# syntax highlighting is optional and ships as a source-filter there too.
+# About pages (markdown, man and plain-text readmes) render through the bundled
+# about-render.lua about-filter, see the filter section below. Source syntax
+# highlighting is optional and ships as a source-filter there too.
 #
 # One key=value pair per line. Lines starting with # are comments.
 
@@ -27,22 +26,22 @@
 cache-size=0
 
 # Directory used to store cgit cache entries. Value is a filesystem path that
-# may use macros. Default is /var/cache/cgit. The directory must be owned by
-# the account the web server runs cgit as, with mode 0700, since the cache
-# holds every rendered page and the URLs visitors asked for.
+# may use macros. Default is /var/cache/cgit. The directory must be owned by the
+# account the web server runs cgit as, with mode 0700, since the cache holds
+# every rendered page and the URLs visitors asked for.
 #cache-root=/var/cache/cgit
 
 # Minutes to cache the repository index page. Value is an integer number of
 # minutes. Default is 5.
-cache-root-ttl=5
+cache-index-ttl=5
 
 # Minutes to cache the repository summary page. Value is an integer number of
 # minutes. Default is 5.
-cache-repo-ttl=5
+cache-summary-ttl=5
 
 # Minutes to cache the result of scanning a path for repositories. Value is an
 # integer number of minutes. Default is 15.
-cache-scanrc-ttl=15
+cache-scan-ttl=15
 
 # Minutes to cache repo pages requested with a fixed SHA1. A negative value
 # never expires. Value is an integer number of minutes. Default is -1.
@@ -56,12 +55,12 @@ cache-dynamic-ttl=5
 # minutes. Default is 15.
 cache-about-ttl=15
 
-# Minutes to cache snapshots. Value is an integer number of minutes.
-# Default is 5.
+# Minutes to cache snapshots. Value is an integer number of minutes. Default is
+# 5.
 cache-snapshot-ttl=5
 
-# Expose the ls_cache page, which lists cache paths and the urls other
-# visitors requested. Values are 0 or 1. Default is 0.
+# Expose the ls_cache page, which lists cache paths and the urls other visitors
+# requested. Values are 0 or 1. Default is 0.
 enable-cache-list=0
 
 
@@ -69,12 +68,12 @@ enable-cache-list=0
 ## Site appearance
 ##
 
-# Heading text on the repository index page. Value is any text.
-# Default is Git repository browser.
+# Heading text on the repository index page. Value is any text. Default is Git
+# repository browser.
 #root-title=Git repository browser
 
-# Subheading text below the index page heading. Value is any text.
-# Default is a fast webinterface for the git dscm.
+# Subheading text below the index page heading. Value is any text. Default is a
+# fast webinterface for the git dscm.
 #root-desc=a fast webinterface for the git dscm
 
 # File included verbatim below the about link on the index page. Value is a
@@ -114,15 +113,16 @@ enable-cache-list=0
 # path. Default is none.
 #head-include=/var/www/htdocs/cgit-head.html
 
-# Content of the robots meta tag. Value is robots meta content.
-# Default is index, nofollow.
+# Content of the robots meta tag. Value is robots meta content. Default is
+# index, nofollow.
 robots=index, nofollow
 
-# Omit the standard page header when set. Values are 0 or 1. Default is 0.
-noheader=0
+# Draw the standard page header. Set to 0 to omit it, for example when
+# embedding. Values are 0 or 1. Default is 1.
+enable-header=1
 
-# Generate an HTML fragment suitable for embedding in other pages. Values are
-# 0 or 1. Default is 0.
+# Generate an HTML fragment suitable for embedding in other pages. Values are 0
+# or 1. Default is 0.
 embedded=0
 
 # Root url for all cgit links, enabling virtual urls. Value is a url path.
@@ -142,8 +142,8 @@ embedded=0
 # path that may use macros. Default is none.
 #scan-path=/var/lib/git
 
-# When scanning, recurse into dot-directories. Must precede scan-path.
-# Values are 0 or 1. Default is 0.
+# When scanning, recurse into dot-directories. Must precede scan-path. Values
+# are 0 or 1. Default is 0.
 scan-hidden-path=0
 
 # Derive default section names from N leading path elements. Must precede
@@ -159,19 +159,21 @@ remove-suffix=0
 #project-list=/var/lib/git/projects.list
 
 # Serve a repo only if this file exists inside it. Emulates gitweb EXPORT_OK.
-# Must precede scan-path. Value is a filename. Default is none.
+# The reverse needs no setting, a repo containing a file named "noweb" is always
+# skipped by the scan. Must precede scan-path. Value is a filename. Default is
+# none.
 #strict-export=git-daemon-export-ok
 
 # Section heading that subsequently-defined repos inherit. Value is any section
 # heading text. Default is none.
 #section=main
 
-# Sort sections and repos within them by name rather than file order. Values
-# are 0 or 1. Default is 0.
+# Sort sections and repos within them by name rather than file order. Values are
+# 0 or 1. Default is 0.
 section-sort=0
 
-# How repositories within a section are sorted. Values are name or age.
-# Default is name.
+# How repositories within a section are sorted. Values are name or age. Default
+# is name.
 repository-sort=name
 
 # Let scanned repos set cgit settings via git config using gitweb.* or cgit.*
@@ -187,8 +189,8 @@ enable-git-config=0
 ## Features
 ##
 
-# Provide a blame page for files and links to it. Values are 0 or 1.
-# Default is 0.
+# Provide a blame page for files and links to it. Values are 0 or 1. Default is
+# 0.
 enable-blame=0
 
 # Print an ASCII-art commit history graph in the log page. Values are 0 or 1.
@@ -199,12 +201,16 @@ enable-commit-graph=0
 # Default is 0.
 enable-follow-links=0
 
+# Derive submodule links from the .gitmodules file for submodules that no
+# module-link template covers. Values are 0 or 1. Default is 0.
+enable-gitmodules-links=0
+
 # Generate extra summary, commit and tree links per repo on the index. Values
 # are 0 or 1. Default is 0.
 enable-index-links=0
 
-# Show the owner of each repo on the index page. Values are 0 or 1.
-# Default is 1.
+# Show the owner of each repo on the index page. Values are 0 or 1. Default is
+# 1.
 enable-index-owner=1
 
 # Show the number of modified files per commit in the log. Values are 0 or 1.
@@ -215,55 +221,51 @@ enable-log-filecount=0
 # Default is 0.
 enable-log-linecount=0
 
-# Show ages in the log, refs and index columns as an elapsed time such as
-# "3 days" rather than a calendar date. Values are 0 or 1. Default is 1.
+# Show ages in the log, refs and index columns as an elapsed time such as "3
+# days" rather than a calendar date. Values are 0 or 1. Default is 1.
 enable-relative-dates=1
 
-# Display remote branches in summary and refs views. Values are 0 or 1.
-# Default is 0.
+# Display remote branches in summary and refs views. Values are 0 or 1. Default
+# is 0.
 enable-remote-branches=0
 
-# Use the parent commit subject as link text for parent links. Values are
-# 0 or 1. Default is 0.
+# Use the parent commit subject as link text for parent links. Values are 0 or
+# 1. Default is 0.
 enable-subject-links=0
 
 # Allow /plain to serve HTML mimetypes instead of downgrading to text/plain.
 # Values are 0 or 1. Default is 0.
 enable-html-serving=0
 
-# Generate line-number links for plaintext blobs in the tree view. Values are
-# 0 or 1. Default is 1.
+# Generate line-number links for plaintext blobs in the tree view. Values are 0
+# or 1. Default is 1.
 enable-tree-linenumbers=1
 
 # List directories first, then files, in the tree view. Values are 0 or 1.
 # Default is 0.
 enable-tree-group-dirs=0
 
-# Default maximum statistics period. Leaving this unset disables statistics.
-# Values are week, month, quarter or year. Default is unset.
-#max-stats=week
-
-# Enable the statistics page, which counts commits per author over a window
-# of recent weeks, months, quarters or years.
-# Values are 0 or 1. Default is 0.
-enable-stats=0
+# Enable the statistics page, which counts commits per author, and set the
+# coarsest period it offers. Each value also offers the finer periods before it.
+# Leaving this unset disables statistics. Values are week, month, quarter or
+# year. Default is unset.
+#max-stats=year
 
 
 ##
 ## Snapshots and cloning
 ##
 
-# Default set of snapshot archive formats to offer. Value is a space list of
-# tar tar.gz tar.bz2 tar.lz tar.xz tar.zst zip, or the word all.
-# Default is none.
+# Default set of snapshot archive formats to offer. Value is a space list of tar
+# tar.gz tar.bz2 tar.lz tar.xz tar.zst zip, or the word all. Default is none.
 #snapshots=tar.gz tar.xz zip
 
 # Act as a dumb HTTP endpoint for git clones. Values are 0 or 1. Default is 1.
 enable-http-clone=1
 
 # Prefixes combined with the repo url to build clone urls. Used only when
-# repo.clone-url is unset. Value is space-separated url prefixes.
-# Default is none.
+# repo.clone-url is unset. Value is space-separated url prefixes. Default is
+# none.
 #clone-prefix=https://example.com/git git://example.com
 
 # Clone-url templates used when repo.clone-url is unset. Value is
@@ -279,11 +281,11 @@ enable-http-clone=1
 # Prefix the command with lua: to run it through the built-in Lua interpreter,
 # which avoids a fork per call, or with exec: to run a normal program. The
 # commands below that point at /usr/share/cgit/extensions/ use scripts this
-# repository ships under custom/extensions/. The ones written as /path/to/your-command
-# mark where your own command goes.
+# repository ships under custom/extensions/. The ones written as
+# /path/to/your-command mark where your own command goes.
 
-# Allow filter settings to be overridden in per-repo cgitrc files. Values are
-# 0 or 1. Default is 0.
+# Allow the filter settings to be set per repository, both as repo.* lines below
+# and inside per-repo cgitrc files. Values are 0 or 1. Default is 0.
 enable-filter-overrides=0
 
 # Filter command used to format about-page content. The bundled about-render.lua
@@ -296,22 +298,23 @@ enable-filter-overrides=0
 # with exec or lua. Default is none.
 #commit-filter=lua:/usr/share/cgit/extensions/link-commits.lua
 
-# Filter command used to format author and committer emails, for example to
-# add avatar images. Value is a command optionally prefixed with exec or lua.
+# Filter command used to format author and committer emails, for example to add
+# avatar images. Value is a command optionally prefixed with exec or lua.
 # Default is none.
 #email-filter=lua:/usr/share/cgit/extensions/email-gravatar.lua
 
 # Filter command used to format plaintext blobs in the tree view. Without it
-# cgit serves the text plain. For syntax highlighting, the shipped filter
-# below uses the Scintillua lexers and needs the lpeg module installed too,
-# on Debian that is "apt install lua-lpeg". Missing either dependency means
-# plain uncolored text, not an error. See the comments in that file. Value
-# is a command optionally prefixed with exec or lua. Default is none.
+# cgit serves the text plain. For syntax highlighting, the shipped filter below
+# uses the Scintillua lexers and needs the lpeg module installed too, on Debian
+# that is "apt install lua-lpeg". Missing either dependency means plain
+# uncolored text, not an error. See the comments in that file. Value is a
+# command optionally prefixed with exec or lua. Default is none.
 #source-filter=lua:/usr/share/cgit/extensions/syntax-highlight.lua
 
 # Filter command invoked to authenticate access, gating repositories behind a
-# login. See custom/extensions/auth-inline.lua and custom/extensions/auth-file.lua. Value
-# is a command optionally prefixed with exec or lua. Default is none.
+# login. See custom/extensions/auth-inline.lua and
+# custom/extensions/auth-file.lua. Value is a command optionally prefixed with
+# exec or lua. Default is none.
 #auth-filter=lua:/usr/share/cgit/extensions/auth-inline.lua
 
 
@@ -330,8 +333,8 @@ max-message-length=80
 # Default is 80.
 max-repodesc-length=80
 
-# Max blob size in KBytes read into memory for html, plain and blob output.
-# A value of 0 disables the limit. Value is an integer. Default is 10240.
+# Max blob size in KBytes read into memory for html, plain and blob output. A
+# value of 0 disables the limit. Value is an integer. Default is 10240.
 max-blob-size=10240
 
 # Number of repos listed per page on the index. A value of 0 or negative shows
@@ -343,8 +346,8 @@ max-repo-count=50
 max-commit-count=50
 
 # Maximum number of commits the patch view emits as a series for an explicit
-# revision range. A single commit is unaffected. A value of 0 removes the
-# limit. Value is an integer. Default is 50.
+# revision range. A single commit is unaffected. A value of 0 removes the limit.
+# Value is an integer. Default is 50.
 max-patch-count=50
 
 # Commits changing more files than this render as a diffstat, where each file
@@ -352,9 +355,9 @@ max-patch-count=50
 # Value is an integer. Default is 200.
 max-diff-files=200
 
-# A file whose diff spans more lines than this is replaced by a link to its
-# own diff page in whole-commit views. A value of 0 always renders it inline.
-# Value is an integer. Default is 1000.
+# A file whose diff spans more lines than this is replaced by a link to its own
+# diff page in whole-commit views. A value of 0 always renders it inline. Value
+# is an integer. Default is 1000.
 max-diff-lines=1000
 
 # Branches and tags listed per section on the refs page, and per page on the
@@ -364,19 +367,19 @@ max-ref-count=200
 
 # Max files considered when detecting renames. A value of -1 uses the git
 # compile-time value. Value is an integer. Default is -1.
-renamelimit=-1
+rename-limit=-1
 
 
 ##
 ## Presentation
 ##
 
-# Number of log entries shown in the summary view. Value is an integer.
-# Default is 10.
+# Number of log entries shown in the summary view. Value is an integer. Default
+# is 10.
 summary-log=10
 
-# Number of branches shown in the summary view. Value is an integer.
-# Default is 10.
+# Number of branches shown in the summary view. Value is an integer. Default is
+# 10.
 summary-branches=10
 
 # Number of tags shown in the summary view. Value is an integer. Default is 10.
@@ -386,13 +389,13 @@ summary-tags=10
 # Default is 0.
 side-by-side-diffs=0
 
-# Print commit and tag times in the server timezone. Values are 0 or 1.
-# Default is 0.
+# Print commit and tag times in the server timezone. Values are 0 or 1. Default
+# is 0.
 local-time=0
 
-# Format for the calendar dates in the age columns. Accepts the names git
-# takes for --date, such as short, iso8601, rfc2822, human and unix, each of
-# which may carry a -local suffix, plus format:<strftime>. Default is short.
+# Format for the calendar dates in the age columns. Accepts the names git takes
+# for --date, such as short, iso8601, rfc2822, human and unix, each of which may
+# carry a -local suffix, plus format:<strftime>. Default is short.
 date-format=short
 
 # Ordering of commits in the log view. Leaving this unset uses the git log
@@ -405,12 +408,13 @@ branch-sort=name
 # Sort items in the repo list case-sensitively. Values are 0 or 1. Default is 1.
 case-sensitive-sort=1
 
-# Hide full author email addresses when set. Values are 0 or 1. Default is 0.
-noplainemail=0
+# Show full author email addresses beside names. Set to 0 to hide them. Values
+# are 0 or 1. Default is 1.
+enable-plain-email=1
 
 # File giving the timestamp of the youngest commit. Value is a path relative to
 # the repo. Default is info/web/last-modified.
-#agefile=info/web/last-modified
+#age-file=info/web/last-modified
 
 # Fallback mimetype lookup file for plain output. Value is a filesystem path.
 # Default is none.
@@ -457,8 +461,8 @@ noplainemail=0
 # macros. Default is none.
 #repo.clone-url=https://example.com/example.git git://example.com/example.git
 
-# Default branch for the repo. Falls back to the first sorted branch. Value is
-# a branch name. Default is the HEAD branch, or master.
+# Default branch for the repo. Falls back to the first sorted branch. Value is a
+# branch name. Default is the HEAD branch, or master.
 #repo.defbranch=master
 
 # Override the current section name for this repo. Value is a section name.
@@ -471,18 +475,18 @@ noplainemail=0
 
 # Extra content added verbatim to the head of each page for this repo. Value is
 # an HTML fragment. Default is none.
-#repo.extra-head-content=<meta name="example" content="value">
+#repo.head-content=<meta name="example" content="value">
 
-# File included verbatim as the repo About page. A colon-prefixed value uses
-# the head or defbranch. Value is a [ref]path entry. Default is the global
-# readme value.
+# File included verbatim as the repo About page. A colon-prefixed value uses the
+# head or defbranch. Value is a [ref]path entry. Default is the global readme
+# value.
 #repo.readme=:README.md
 
 # Per-repo logo image url. Value is a url. Default is the global logo value.
 #repo.logo=/cgit.png
 
-# Per-repo logo link target url. Value is a url. Default is the global
-# logo-link value.
+# Per-repo logo link target url. Value is a url. Default is the global logo-link
+# value.
 #repo.logo-link=/
 
 # Per-repo submodule link format string. Value is a printf format string taking
@@ -493,13 +497,13 @@ noplainemail=0
 # string taking sha1. Default is none.
 #repo.module-link.path/to/sub=https://example.com/sub/commit/?id=%s
 
-# Snapshot formats offered for this repo, restricted by the global mask. A
-# value of 0 disables snapshots. Value is snapshot formats. Default is the
-# global snapshots value.
+# Snapshot formats offered for this repo, restricted by the global mask. A value
+# of 0 disables snapshots. Value is snapshot formats. Default is the global
+# snapshots value.
 #repo.snapshots=tar.gz zip
 
-# Hide the repo from the index but still allow direct access. Values are
-# 0 or 1. Default is 0.
+# Hide the repo from the index but still allow direct access. Values are 0 or 1.
+# Default is 0.
 #repo.hide=0
 
 # Ignore the repo entirely so it is not indexed and not directly accessible.
@@ -518,6 +522,10 @@ noplainemail=0
 # global enable-follow-links value.
 #repo.enable-follow-links=0
 
+# Per-repo override of enable-gitmodules-links. Values are 0 or 1. Default is
+# the global enable-gitmodules-links value.
+#repo.enable-gitmodules-links=0
+
 # Per-repo override of enable-log-filecount. Values are 0 or 1. Default is the
 # global enable-log-filecount value.
 #repo.enable-log-filecount=0
@@ -526,8 +534,8 @@ noplainemail=0
 # global enable-log-linecount value.
 #repo.enable-log-linecount=0
 
-# Per-repo override of enable-remote-branches. Values are 0 or 1. Default is
-# the global enable-remote-branches value.
+# Per-repo override of enable-remote-branches. Values are 0 or 1. Default is the
+# global enable-remote-branches value.
 #repo.enable-remote-branches=0
 
 # Per-repo override of enable-subject-links. Values are 0 or 1. Default is the
@@ -545,26 +553,27 @@ noplainemail=0
 # Values are date or topo. Default is unset.
 #repo.commit-sort=date
 
-# Per-repo maximum statistics period. Values are week, month, quarter or year.
-# Default is the global max-stats value.
+# Per-repo maximum statistics period. A value of 0 disables the statistics page
+# for this repo. Values are week, month, quarter, year or 0. Default is the
+# global max-stats value.
 #repo.max-stats=week
 
-# Per-repo override of the about-filter. Allowed in a repo cgitrc only when
+# Per-repo override of the about-filter. Only honoured when
 # enable-filter-overrides is 1. Value is a command. Default is the global
 # about-filter value.
 #repo.about-filter=exec:/path/to/your-command
 
-# Per-repo override of the commit-filter. Allowed in a repo cgitrc only when
+# Per-repo override of the commit-filter. Only honoured when
 # enable-filter-overrides is 1. Value is a command. Default is the global
 # commit-filter value.
 #repo.commit-filter=lua:/usr/share/cgit/extensions/link-commits.lua
 
-# Per-repo override of the source-filter. Allowed in a repo cgitrc only when
+# Per-repo override of the source-filter. Only honoured when
 # enable-filter-overrides is 1. Value is a command. Default is the global
 # source-filter value.
 #repo.source-filter=exec:/path/to/your-command
 
-# Per-repo override of the email-filter. Allowed in a repo cgitrc only when
+# Per-repo override of the email-filter. Only honoured when
 # enable-filter-overrides is 1. Value is a command. Default is the global
 # email-filter value.
 #repo.email-filter=lua:/usr/share/cgit/extensions/email-gravatar.lua