This page is primarily intended for Mercurial's developers.
This is a speculative project and does not represent any firm decisions on future behavior.
Make the .hgrc file more unified.
The goal of this project is to make a clear naming style regarding the .hgrc configuration options.
2. Detailed description
The current .hgrc configuration options is messed with many different styles:
- anoption (~ 192 options, many are unreadable)
- an_option (~ 8 options)
- an-option (~ 7 options)
Having a unified style makes the code cleaner, better integrated.
In addition, having guideline for sections would be useful. In Mercurial core + bundled extensions we have about 300 configuration options. They are spread across the following sections:
34 ui 28 convert 27 experimental 21 web 20 bugzilla 19 lists 13 notify 10 format 10 devel 9 values 9 profiling 7 server 6 smtp 5 worker 5 patchbomb 5 http_proxy 4 progress 4 mq 3 pager 3 histedit 3 factotum 3 eol 3 email 2 transplant 2 share 2 phases 2 paths 2 patch 2 merge 2 hostsecurity 2 gpg 2 fsmonitor 2 color 2 chgserver 2 bundle 2 blackbox 2 acl 1 win32text 1 win32mbcs 1 shelve 1 perf 1 keywordset 1 hook 1 hgk 1 fakepatchtime 1 fakedirstatewritetime 1 debug 1 cmdserver 1 censor 1 bookmarks 1 automv
There are *many* options is the [ui] section and many sections with very few config. Gathering related options in the same config section has multiple advantages. The main one is that it puts related options together in the documentation improving discoverability. But at the same time, having too many options in the [ui] is burying the important ones under more minor ones.
2.0.1. Proposal: use - in config examples
While major options can be written in only one word, we should start using hyphens between words.
The actual config looks like this:
[web] allowpull = foo allow_push = bar # yes, for real [progress] assume-tty = yes [worker] backgroundcloseminfilecount = 12
Using hyphens, options will be renamed like this:
[web] allow-pull = foo allow-push = bar [progress] assume-tty = yes [worker] background-close-min-file-count = 12
Names like backgroundcloseminfilecount, graphnodetemplate, mergemarkertemplate are actually not readable by humans.
Using the implemented alias support, we can start renaming options to the new convention without any breakage.
coreconfigitem('web', 'allowpull', default=None, alias=[('web', 'allow-pull')] )
Note: we need to keep the old name as the original section/key configitem.
2.1. Proposal for sections: central config declaration
Currently, config options do not needs to be declared in any special way. You just fetch a value in the code using ui.config(section, name[, defaultvalue]).
On top of that, we have contrib/check-config.py that runs on the code in the Mercurial repository trying to catch:
- inconsistent type used in config
- undocumented config option
The proposal is to have a central declaration of all known config options. That register would contain:
- default value,
- state: (deprecated, experimental, etc)
2.1.1. direct benefit
an issue devel warning on access to undefined option. Catching bug from minor typo (eg: ui.config('path',…) vs ui.config('paths',…))
- have declaration/documentation checks also runs for out of core extensions,
- it becomes less error prone to update an option default value,
- makes it easier for extensions to change default value,
- makes it easier to discover existing config and section when adding a new options,
2.1.2. sub-proposal: config renaming
We could have official "config alias". For example, let's say we could rename ui.clonebundleprefers to clonebundle.preference, we declare the rename in the central repository and on access, if clonebundle.preference is undefined, the old name is checked instead (possibly with a transformation).
That would come really handy in regard with experimental option as we could rename them without breaking existing users.
Having such feature would also allow a large cleanup on the existing config options to merge some related section together and to split some minor options out of the [ui] section.
In addition, we could also, decide on one form standard for config option "name" (as describe in the earlier part of the document) and rename all existing one to match our pick.
write official naming guideline for options
implement a central declaration
implement alias support
migrate documentation and default config to the central declaration
devel warning for non-existing/inconsistent access
official way for extensions to overwrite default
implement config "forwarding"
reorganize existing sections,
small patch to list all existing options: https://www.mercurial-scm.org/repo/users/marmoute/mercurial/rev/1696f686f616