#pragma section-numbers 2
= Config Extension =
'''This extension is not distributed with Mercurial.'''

''Author: Steve Borho''

Repository: http://www.bitbucket.org/sborho/hgconfig/

Requires [[http://code.google.com/p/iniparse/|iniparse]] to be installed.

To use the dialogs, you must have [[http://www.riverbankcomputing.com/software/pyqt/intro|PyQt4]] or [[http://www.pygtk.org/|PyGtk]] installed.   '''This extension is considered defunct, use TortoiseHg config dialogs instead. For command line access to configuration, consider HgcfgExtension.'''

<<TableOfContents(3)>>

== Overview ==
This extension provides an `hg config` command which can be used to read or write values from your Mercurial configuration files.  It also provides a small number of dialog windows for the most common configuration tasks.

== Configuration ==
Configure your `.hgrc` to enable the extension by adding following lines:

{{{
[extensions]
hgext.hgconfig =
}}}
Note that the hg-config repository comes with an `hgconf.rc` file which is intended to be copied into a site-wide `hgrc.d/` directory.  It enables the extension and configures the username hook (below).

== Username Hook ==
This extension also provides a hook which can spawn the username dialog when a user tries to make a commit without a valid username.  It is enabled by adding the following lines to the site-wide `hgrc` file.

{{{
[hooks]
precommit.username = python:hgconf.uname.hook
}}}
After a user triggers the dialog and enters a valid username, the dialog will override the global precommit.username hook by adding the following lines into the same `hgrc` file the username was stored:

{{{
[hooks]
precommit.username =
}}}
== Config Command ==
When the extension is properly installed, you can easily get the online help.

{{{
% hg help config
hg config [<file-option>] [-gibBr] section.name [newvalue]

Apply a change or query a Mercurial configuration file.

       By default changes are applied globally to a user's ~/.hgrc (or
       equivalent) unless the --local flag is given, in which case the
       changes are applied to this repository's $(hg root)/.hg/hgrc
       file.  The configuration file may also be explicitly specified
       via the --file argument.

       Examples:
       hg config --get --local paths.default
       hg config --get --bool diff.git
       hg config --local paths.default ~/clone-parent
       hg config ui.ssh "/path/to/ssh -C"
       hg config --file /etc/mercurial/hgrc extensions.hgext.mq

       To launch one of the provided dialogs:
       hg config [--local] username
       hg config paths          # only operates on local repo
       hg config webconf        # only operates on local repo

       The --get and --file options are by ignored dialog commands.

       Get comamnds return 0 if successful, a boolean 0 or 1 if
       --return-bool was specified, or 2 if an error occurred. The key
       value is returned on stdout and all warnings are piped to stderr.

       Note that 'hg config' is parsing a value from a particular file,
       while Mercurial parses a series of files at startup in order
       to read its configuration (man 5 hgrc).  To see the actual value
       that Mercurial will use, use the 'hg showconfig' command.

       Set commands return 0 if successful, or 1 if a write failure
       occurred

options:

 -g --get             get value for specified key
 -i --int             force retrieved value to be an integer
 -b --bool            force retrieved value to be a 0 or 1
 -B --return-bool     command returns 0 or 1 based on retrieved value
 -l --local           operate on configuration of local repository
 -rm --remove         remove specified key from file
    --remove-section  remove specified section from file
 -f --file            operate on specified config file

use "hg -v help config" to show global options
}}}
----
CategoryExtensionsByOthers