repo-config: document what value_regexp does a bit more clearly.

[thirdparty/git.git] / Documentation / git-repo-config.txt

git-repo-config(1)
==================

NAME
----
git-repo-config - Get and set options in .git/config


SYNOPSIS
--------
[verse]
'git-repo-config' [type] name [value [value_regex]]
'git-repo-config' [type] --replace-all name [value [value_regex]]
'git-repo-config' [type] --get name [value_regex]
'git-repo-config' [type] --get-all name [value_regex]
'git-repo-config' [type] --unset name [value_regex]
'git-repo-config' [type] --unset-all name [value_regex]

DESCRIPTION
-----------
You can query/set/replace/unset options with this command. The name is
actually the section and the key separated by a dot, and the value will be
escaped.

If you want to set/unset an option which can occur on multiple
lines, a POSIX regexp `value_regex` needs to be given.  Only the
existing values that match the regexp are updated or unset.  If
you want to handle the lines that do *not* match the regex, just
prepend a single exclamation mark in front (see EXAMPLES).

The type specifier can be either '--int' or '--bool', which will make
'git-repo-config' ensure that the variable(s) are of the given type and
convert the value to the canonical form (simple decimal number for int,
a "true" or "false" string for bool). If no type specifier is passed,
no checks or transformations are performed on the value.

This command will fail if

. .git/config is invalid,
. .git/config can not be written to,
. no section was provided,
. the section or key is invalid,
. you try to unset an option which does not exist, or
. you try to unset/set an option for which multiple lines match.


OPTIONS
-------

--replace-all::
	Default behaviour is to replace at most one line. This replaces
	all lines matching the key (and optionally the value_regex)

--get::
	Get the value for a given key (optionally filtered by a regex
	matching the value).

--get-all::
	Like get, but does not fail if the number of values for the key
	is not exactly one.

--unset::
	Remove the line matching the key from .git/config.

--unset-all::
	Remove all matching lines from .git/config.


EXAMPLE
-------

Given a .git/config like this:

	#
	# This is the config file, and
	# a '#' or ';' character indicates
	# a comment
	#

	; core variables
	[core]
		; Don't trust file modes
		filemode = false

	; Our diff algorithm
	[diff]
		external = "/usr/local/bin/gnu-diff -u"
		renames = true

	; Proxy settings
	[core]
		gitproxy="ssh" for "ssh://kernel.org/"
		gitproxy="proxy-command" for kernel.org
		gitproxy="myprotocol-command" for "my://"
		gitproxy=default-proxy ; for all the rest

you can set the filemode to true with

------------
% git repo-config core.filemode true
------------

The hypothetic proxy command entries actually have a postfix to discern
to what URL they apply. Here is how to change the entry for kernel.org
to "ssh".

------------
% git repo-config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
------------

This makes sure that only the key/value pair for kernel.org is replaced.

To delete the entry for renames, do

------------
% git repo-config --unset diff.renames
------------

If you want to delete an entry for a multivar (like core.gitproxy above),
you have to provide a regex matching the value of exactly one line.

To query the value for a given key, do

------------
% git repo-config --get core.filemode
------------

or

------------
% git repo-config core.filemode
------------

or, to query a multivar:

------------
% git repo-config --get core.gitproxy "for kernel.org$"
------------

If you want to know all the values for a multivar, do:

------------
% git repo-config --get-all core.gitproxy
------------

If you like to live dangerous, you can replace *all* core.gitproxy by a
new one with

------------
% git repo-config --replace-all core.gitproxy ssh
------------

However, if you really only want to replace the line for the default proxy,
i.e. the one without a "for ..." postfix, do something like this:

------------
% git repo-config core.gitproxy ssh '! for '
------------

To actually match only values with an exclamation mark, you have to

------------
% git repo-config section.key value '[!]'
------------


include::config.txt[]


Author
------
Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>

Documentation
--------------
Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.

GIT
---
Part of the gitlink:git[7] suite