Document the configuration file
This patch adds a Documentation/config.txt file included by git-repo-config and currently aggregating hopefully all the available git plumbing / core porcelain configuration variables, as well as briefly describing the format. It also updates an outdated bit of the example in git-repo-config(1). Signed-off-by: Petr Baudis <pasky@suse.cz>
Petr Baudis committed
Apr 25, 2006 at 00:59 UTC
1ab661ddb7eb564c1c3cb97a512257860a651459
3 files changed
+198
-14
Documentation/config.txt
new
+181
@@ -0,0 +1,181 @@
1
+CONFIGURATION FILE
2
+------------------
3
+
4
+The git configuration file contains a number of variables that affect
5
+the git commands behaviour. They can be used by both the git plumbing
6
+and the porcelains. The variables are divided to sections, where
7
+in the fully qualified variable name the variable itself is the last
8
+dot-separated segment and the section name is everything before the last
9
+dot. The variable names are case-insensitive and only alphanumeric
10
+characters are allowed. Some variables may appear multiple times.
11
+
12
+The syntax is fairly flexible and permissive; whitespaces are mostly
13
+ignored. The '#' and ';' characters begin commends to the end of line,
14
+blank lines are ignored, lines containing strings enclosed in square
15
+brackets start sections and all the other lines are recognized
16
+as setting variables, in the form 'name = value'. If there is no equal
17
+sign on the line, the entire line is taken as 'name' and the variable
18
+is recognized as boolean "true". String values may be entirely or partially
19
+enclosed in double quotes; some variables may require special value format.
20
+
21
+Example
22
+~~~~~~~
23
+
24
+ # Core variables
25
+ [core]
26
+ ; Don't trust file modes
27
+ filemode = false
28
+
29
+ # Our diff algorithm
30
+ [diff]
31
+ external = "/usr/local/bin/gnu-diff -u"
32
+ renames = true
33
+
34
+Variables
35
+~~~~~~~~~
36
+
37
+Note that this list is non-comprehensive and not necessarily complete.
38
+For command-specific variables, you will find more detailed description
39
+in the appropriate manual page. You will find description of non-core
40
+porcelain configuration variables in the respective porcelain documentation.
41
+
42
+core.fileMode::
43
+ If false, the executable bit differences between the index and
44
+ the working copy are ignored; useful on broken filesystems like FAT.
45
+ See gitlink:git-update-index[1]. True by default.
46
+
47
+core.gitProxy::
48
+ A "proxy command" to execute (as 'command host port') instead
49
+ of establishing direct connection to the remote server when
50
+ using the git protocol for fetching. If the variable value is
51
+ in the "COMMAND for DOMAIN" format, the command is applied only
52
+ on hostnames ending with the specified domain string. This variable
53
+ may be set multiple times and is matched in the given order;
54
+ the first match wins.
55
+
56
+ Can be overriden by the 'GIT_PROXY_COMMAND' environment variable
57
+ (which always applies universally, without the special "for"
58
+ handling).
59
+
60
+core.ignoreStat::
61
+ The working copy files are assumed to stay unchanged until you
62
+ mark them otherwise manually - Git will not detect the file changes
63
+ by lstat() calls. This is useful on systems where those are very
64
+ slow, such as Microsoft Windows. See gitlink:git-update-index[1].
65
+ False by default.
66
+
67
+core.onlyUseSymrefs::
68
+ Always use the "symref" format instead of symbolic links for HEAD
69
+ and other symbolic reference files. True by default.
70
+
71
+core.repositoryFormatVersion::
72
+ Internal variable identifying the repository format and layout
73
+ version.
74
+
75
+core.sharedRepository::
76
+ If true, the repository is made shareable between several users
77
+ in a group (making sure all the files and objects are group-writable).
78
+ See gitlink:git-init-db[1]. False by default.
79
+
80
+core.warnAmbiguousRefs::
81
+ If true, git will warn you if the ref name you passed it is ambiguous
82
+ and might match multiple refs in the .git/refs/ tree. True by default.
83
+
84
+apply.whitespace::
85
+ Tells `git-apply` how to handle whitespaces, in the same way
86
+ as the '--whitespace' option. See gitlink:git-apply[1].
87
+
88
+diff.renameLimit::
89
+ The number of files to consider when performing the copy/rename
90
+ detection; equivalent to the git diff option '-l'.
91
+
92
+format.headers::
93
+ Additional email headers to include in a patch to be submitted
94
+ by mail. See gitlink:git-format-patch[1].
95
+
96
+gitcvs.enabled::
97
+ Whether the cvs pserver interface is enabled for this repository.
98
+ See gitlink:git-cvsserver[1].
99
+
100
+gitcvs.logfile::
101
+ Path to a log file where the cvs pserver interface well... logs
102
+ various stuff. See gitlink:git-cvsserver[1].
103
+
104
+http.sslVerify::
105
+ Whether to verify the SSL certificate when fetching or pushing
106
+ over HTTPS. Can be overriden by the 'GIT_SSL_NO_VERIFY' environment
107
+ variable.
108
+
109
+http.sslCert::
110
+ File containing the SSL certificate when fetching or pushing
111
+ over HTTPS. Can be overriden by the 'GIT_SSL_CERT' environment
112
+ variable.
113
+
114
+http.sslKey::
115
+ File containing the SSL private key when fetching or pushing
116
+ over HTTPS. Can be overriden by the 'GIT_SSL_KEY' environment
117
+ variable.
118
+
119
+http.sslCAInfo::
120
+ File containing the certificates to verify the peer with when
121
+ fetching or pushing over HTTPS. Can be overriden by the
122
+ 'GIT_SSL_CAINFO' environment variable.
123
+
124
+http.sslCAPath::
125
+ Path containing files with the CA certificates to verify the peer
126
+ with when fetching or pushing over HTTPS. Can be overriden
127
+ by the 'GIT_SSL_CAPATH' environment variable.
128
+
129
+http.maxRequests::
130
+ How many HTTP requests to launch in parallel. Can be overriden
131
+ by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5.
132
+
133
+http.lowSpeedLimit, http.lowSpeedTime::
134
+ If the HTTP transfer speed is less than 'http.lowSpeedLimit'
135
+ for longer than 'http.lowSpeedTime' seconds, the transfer is aborted.
136
+ Can be overriden by the 'GIT_HTTP_LOW_SPEED_LIMIT' and
137
+ 'GIT_HTTP_LOW_SPEED_TIME' environment variables.
138
+
139
+i18n.commitEncoding::
140
+ Character encoding the commit messages are stored in; git itself
141
+ does not care per se, but this information is necessary e.g. when
142
+ importing commits from emails or in the gitk graphical history
143
+ browser (and possibly at other places in the future or in other
144
+ porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'.
145
+
146
+merge.summary::
147
+ Whether to include summaries of merged commits in newly created
148
+ merge commit messages. False by default.
149
+
150
+pull.octopus::
151
+ The default merge strategy to use when pulling multiple branches
152
+ at once.
153
+
154
+pull.twohead::
155
+ The default merge strategy to use when pulling a single branch.
156
+
157
+show.difftree::
158
+ The default gitlink:git-diff-tree[1] arguments to be used
159
+ for gitlink:git-show[1].
160
+
161
+showbranch.default::
162
+ The default set of branches for gitlink:git-show-branch[1].
163
+ See gitlink:git-show-branch[1].
164
+
165
+user.email::
166
+ Your email address to be recorded in any newly created commits.
167
+ Can be overriden by the 'GIT_AUTHOR_EMAIL' and 'GIT_COMMITTER_EMAIL'
168
+ environment variables. See gitlink:git-commit-tree[1].
169
+
170
+user.name::
171
+ Your full name to be recorded in any newly created commits.
172
+ Can be overriden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
173
+ environment variables. See gitlink:git-commit-tree[1].
174
+
175
+whatchanged.difftree::
176
+ The default gitlink:git-diff-tree[1] arguments to be used
177
+ for gitlink:git-whatchanged[1].
178
+
179
+imap::
180
+ The configuration variables in the 'imap' section are described
181
+ in gitlink:git-imap-send[1].
Documentation/git-repo-config.txt
+16
-13
@@ -87,11 +87,11 @@ Given a .git/config like this:
87
renames = true
88
89
; Proxy settings
90
- [proxy]
91
- command="ssh" for "ssh://kernel.org/"
92
- command="proxy-command" for kernel.org
93
- command="myprotocol-command" for "my://"
94
- command=default-proxy ; for all the rest
90
+ [core]
91
+ gitproxy="ssh" for "ssh://kernel.org/"
92
+ gitproxy="proxy-command" for kernel.org
93
+ gitproxy="myprotocol-command" for "my://"
94
+ gitproxy=default-proxy ; for all the rest
95
96
you can set the filemode to true with
97
@@ -104,7 +104,7 @@ to what URL they apply. Here is how to change the entry for kernel.org
104
to "ssh".
105
106
------------
107
-% git repo-config proxy.command '"ssh" for kernel.org' 'for kernel.org$'
107
+% git repo-config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
108
------------
109
110
This makes sure that only the key/value pair for kernel.org is replaced.
@@ -115,7 +115,7 @@ To delete the entry for renames, do
115
% git repo-config --unset diff.renames
116
------------
117
118
-If you want to delete an entry for a multivar (like proxy.command above),
118
+If you want to delete an entry for a multivar (like core.gitproxy above),
119
you have to provide a regex matching the value of exactly one line.
120
121
To query the value for a given key, do
@@ -133,27 +133,27 @@ or
133
or, to query a multivar:
134
135
------------
136
-% git repo-config --get proxy.command "for kernel.org$"
136
+% git repo-config --get core.gitproxy "for kernel.org$"
137
------------
138
139
If you want to know all the values for a multivar, do:
140
141
------------
142
-% git repo-config --get-all proxy.command
142
+% git repo-config --get-all core.gitproxy
143
------------
144
145
-If you like to live dangerous, you can replace *all* proxy.commands by a
145
+If you like to live dangerous, you can replace *all* core.gitproxy by a
146
new one with
147
148
------------
149
-% git repo-config --replace-all proxy.command ssh
149
+% git repo-config --replace-all core.gitproxy ssh
150
------------
151
152
However, if you really only want to replace the line for the default proxy,
153
i.e. the one without a "for ..." postfix, do something like this:
154
155
------------
156
-% git repo-config proxy.command ssh '! for '
156
+% git repo-config core.gitproxy ssh '! for '
157
------------
158
159
To actually match only values with an exclamation mark, you have to
@@ -163,13 +163,16 @@ To actually match only values with an exclamation mark, you have to
163
------------
164
165
166
+include::config.txt[]
167
+
168
+
169
Author
170
------
171
Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
172
173
Documentation
174
--------------
172
-Documentation by Johannes Schindelin.
175
+Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.
176
177
GIT
178
---
config.c
+1
-1
@@ -252,7 +252,7 @@ int git_default_config(const char *var, const char *value)
252
return 0;
253
}
254
255
- /* Add other config variables here.. */
255
+ /* Add other config variables here and to Documentation/config.txt. */
256
return 0;
257
}
258