Fix perl/ build.
[git/git.git] / Documentation / config.txt
CommitLineData
1ab661dd
PB
1CONFIGURATION FILE
2------------------
3
4The git configuration file contains a number of variables that affect
b8936cf0
FD
5the git command's behavior. They can be used by both the git plumbing
6and the porcelains. The variables are divided into sections, where
1ab661dd
PB
7in the fully qualified variable name the variable itself is the last
8dot-separated segment and the section name is everything before the last
9dot. The variable names are case-insensitive and only alphanumeric
10characters are allowed. Some variables may appear multiple times.
11
12The syntax is fairly flexible and permissive; whitespaces are mostly
b8936cf0 13ignored. The '#' and ';' characters begin comments to the end of line,
1ab661dd
PB
14blank lines are ignored, lines containing strings enclosed in square
15brackets start sections and all the other lines are recognized
16as setting variables, in the form 'name = value'. If there is no equal
17sign on the line, the entire line is taken as 'name' and the variable
18is recognized as boolean "true". String values may be entirely or partially
19enclosed in double quotes; some variables may require special value format.
20
21Example
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
34Variables
35~~~~~~~~~
36
37Note that this list is non-comprehensive and not necessarily complete.
b8936cf0
FD
38For command-specific variables, you will find a more detailed description
39in the appropriate manual page. You will find a description of non-core
1ab661dd
PB
40porcelain configuration variables in the respective porcelain documentation.
41
42core.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
47core.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.
b8936cf0
FD
55+
56Can be overridden by the 'GIT_PROXY_COMMAND' environment variable
57(which always applies universally, without the special "for"
58handling).
1ab661dd
PB
59
60core.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
9f0bb90d
JH
67core.preferSymlinkRefs::
68 Instead of the default "symref" format for HEAD
69 and other symbolic reference files, use symbolic links.
70 This is sometimes needed to work with old scripts that
71 expect HEAD to be a symbolic link.
1ab661dd 72
6de08ae6 73core.logAllRefUpdates::
4057deb5
JH
74 Updates to a ref <ref> is logged to the file
75 "$GIT_DIR/logs/<ref>", by appending the new and old
76 SHA1, the date/time and the reason of the update, but
77 only when the file exists. If this configuration
78 variable is set to true, missing "$GIT_DIR/logs/<ref>"
79 file is automatically created for branch heads.
80
81 This information can be used to determine what commit
82 was the tip of a branch "2 days ago". This value is
83 false by default (no automated creation of log files).
6de08ae6 84
1ab661dd
PB
85core.repositoryFormatVersion::
86 Internal variable identifying the repository format and layout
87 version.
88
89core.sharedRepository::
d5dc6a76
JF
90 When 'group' (or 'true'), the repository is made shareable between
91 several users in a group (making sure all the files and objects are
92 group-writable). When 'all' (or 'world' or 'everybody'), the
93 repository will be readable by all users, additionally to being
94 group-shareable. When 'umask' (or 'false'), git will use permissions
95 reported by umask(2). See gitlink:git-init-db[1]. False by default.
1ab661dd
PB
96
97core.warnAmbiguousRefs::
98 If true, git will warn you if the ref name you passed it is ambiguous
99 and might match multiple refs in the .git/refs/ tree. True by default.
100
3d3e95af 101core.compression::
12f6c308
JBH
102 An integer -1..9, indicating the compression level for objects that
103 are not in a pack file. -1 is the zlib and git default. 0 means no
104 compression, and 1..9 are various speed/size tradeoffs, 9 being
105 slowest.
106
93821bd9
LT
107core.legacyheaders::
108 A boolean which enables the legacy object header format in case
109 you want to interoperate with old clients accessing the object
110 database directly (where the "http://" and "rsync://" protocols
111 count as direct access).
112
4514ad4f
PB
113alias.*::
114 Command aliases for the gitlink:git[1] command wrapper - e.g.
115 after defining "alias.last = cat-file commit HEAD", the invocation
116 "git last" is equivalent to "git cat-file commit HEAD". To avoid
99b41c84
PB
117 confusion and troubles with script usage, aliases that
118 hide existing git commands are ignored. Arguments are split by
119 spaces, the usual shell quoting and escaping is supported.
120 quote pair and a backslash can be used to quote them.
4514ad4f 121
1ab661dd
PB
122apply.whitespace::
123 Tells `git-apply` how to handle whitespaces, in the same way
124 as the '--whitespace' option. See gitlink:git-apply[1].
125
648ad18f
SB
126branch.<name>.remote::
127 When in branch <name>, it tells `git fetch` which remote to fetch.
128
5372806a
SB
129branch.<name>.merge::
130 When in branch <name>, it tells `git fetch` the default remote branch
131 to be merged.
132
aa086eb8
ML
133pager.color::
134 A boolean to enable/disable colored output when the pager is in
135 use (default is true).
136
b5376648
JH
137diff.color::
138 When true (or `always`), always use colors in patch.
139 When false (or `never`), never. When set to `auto`, use
140 colors only when the output is to the terminal.
141
142diff.color.<slot>::
143 Use customized color for diff colorization. `<slot>`
144 specifies which part of the patch to use the specified
145 color, and is one of `plain` (context text), `meta`
146 (metainformation), `frag` (hunk header), `old` (removed
147 lines), or `new` (added lines). The value for these
148 configuration variables can be one of: `normal`, `bold`,
149 `dim`, `ul`, `blink`, `reverse`, `reset`, `black`,
150 `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or
151 `white`.
152
1ab661dd
PB
153diff.renameLimit::
154 The number of files to consider when performing the copy/rename
155 detection; equivalent to the git diff option '-l'.
156
b68ea12e
EW
157diff.renames::
158 Tells git to detect renames. If set to any boolean value, it
159 will enable basic rename detection. If set to "copies" or
160 "copy", it will detect copies, as well.
161
1ab661dd
PB
162format.headers::
163 Additional email headers to include in a patch to be submitted
164 by mail. See gitlink:git-format-patch[1].
165
166gitcvs.enabled::
167 Whether the cvs pserver interface is enabled for this repository.
168 See gitlink:git-cvsserver[1].
169
170gitcvs.logfile::
171 Path to a log file where the cvs pserver interface well... logs
172 various stuff. See gitlink:git-cvsserver[1].
173
174http.sslVerify::
175 Whether to verify the SSL certificate when fetching or pushing
37425065 176 over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment
1ab661dd
PB
177 variable.
178
179http.sslCert::
180 File containing the SSL certificate when fetching or pushing
37425065 181 over HTTPS. Can be overridden by the 'GIT_SSL_CERT' environment
1ab661dd
PB
182 variable.
183
184http.sslKey::
185 File containing the SSL private key when fetching or pushing
abda1ef5 186 over HTTPS. Can be overridden by the 'GIT_SSL_KEY' environment
1ab661dd
PB
187 variable.
188
189http.sslCAInfo::
190 File containing the certificates to verify the peer with when
abda1ef5 191 fetching or pushing over HTTPS. Can be overridden by the
1ab661dd
PB
192 'GIT_SSL_CAINFO' environment variable.
193
194http.sslCAPath::
195 Path containing files with the CA certificates to verify the peer
37425065 196 with when fetching or pushing over HTTPS. Can be overridden
1ab661dd
PB
197 by the 'GIT_SSL_CAPATH' environment variable.
198
199http.maxRequests::
abda1ef5 200 How many HTTP requests to launch in parallel. Can be overridden
1ab661dd
PB
201 by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5.
202
203http.lowSpeedLimit, http.lowSpeedTime::
204 If the HTTP transfer speed is less than 'http.lowSpeedLimit'
205 for longer than 'http.lowSpeedTime' seconds, the transfer is aborted.
abda1ef5 206 Can be overridden by the 'GIT_HTTP_LOW_SPEED_LIMIT' and
1ab661dd
PB
207 'GIT_HTTP_LOW_SPEED_TIME' environment variables.
208
3ea099d4
SK
209http.noEPSV::
210 A boolean which disables using of EPSV ftp command by curl.
211 This can helpful with some "poor" ftp servers which doesn't
212 support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV'
213 environment variable. Default is false (curl will use EPSV).
214
1ab661dd
PB
215i18n.commitEncoding::
216 Character encoding the commit messages are stored in; git itself
217 does not care per se, but this information is necessary e.g. when
218 importing commits from emails or in the gitk graphical history
219 browser (and possibly at other places in the future or in other
220 porcelains). See e.g. gitlink:git-mailinfo[1]. Defaults to 'utf-8'.
221
0f03ca94
PB
222log.showroot::
223 If true, the initial commit will be shown as a big creation event.
224 This is equivalent to a diff against an empty tree.
225 Tools like gitlink:git-log[1] or gitlink:git-whatchanged[1], which
226 normally hide the root commit will now show it. True by default.
227
1ab661dd
PB
228merge.summary::
229 Whether to include summaries of merged commits in newly created
230 merge commit messages. False by default.
231
4812a93a
JK
232pack.window::
233 The size of the window used by gitlink:git-pack-objects[1] when no
234 window size is given on the command line. Defaults to 10.
235
1ab661dd
PB
236pull.octopus::
237 The default merge strategy to use when pulling multiple branches
238 at once.
239
240pull.twohead::
241 The default merge strategy to use when pulling a single branch.
242
0cc6d346
SB
243remote.<name>.url::
244 The URL of a remote repository. See gitlink:git-fetch[1] or
245 gitlink:git-push[1].
246
247remote.<name>.fetch::
248 The default set of "refspec" for gitlink:git-fetch[1]. See
249 gitlink:git-fetch[1].
250
251remote.<name>.push::
252 The default set of "refspec" for gitlink:git-push[1]. See
253 gitlink:git-push[1].
254
b6945f57
JH
255repack.usedeltabaseoffset::
256 Allow gitlink:git-repack[1] to create packs that uses
257 delta-base offset. Defaults to false.
258
1ab661dd
PB
259show.difftree::
260 The default gitlink:git-diff-tree[1] arguments to be used
261 for gitlink:git-show[1].
262
263showbranch.default::
264 The default set of branches for gitlink:git-show-branch[1].
265 See gitlink:git-show-branch[1].
266
b982592d
JK
267status.color::
268 A boolean to enable/disable color in the output of
269 gitlink:git-status[1]. May be set to `true` (or `always`),
270 `false` (or `never`) or `auto`, in which case colors are used
271 only when the output is to a terminal. Defaults to false.
272
273status.color.<slot>::
274 Use customized color for status colorization. `<slot>` is
275 one of `header` (the header text of the status message),
276 `updated` (files which are updated but not committed),
277 `changed` (files which are changed but not updated in the index),
278 or `untracked` (files which are not tracked by git). The values of
279 these variables may be specified as in diff.color.<slot>.
280
ce1a79b6 281tar.umask::
7fe08af4 282 By default, gitlink:git-tar-tree[1] sets file and directories modes
ce1a79b6
WT
283 to 0666 or 0777. While this is both useful and acceptable for projects
284 such as the Linux Kernel, it might be excessive for other projects.
285 With this variable, it becomes possible to tell
7fe08af4 286 gitlink:git-tar-tree[1] to apply a specific umask to the modes above.
ce1a79b6
WT
287 The special value "user" indicates that the user's current umask will
288 be used. This should be enough for most projects, as it will lead to
7fe08af4 289 the same permissions as gitlink:git-checkout[1] would use. The default
ce1a79b6
WT
290 value remains 0, which means world read-write.
291
1ab661dd
PB
292user.email::
293 Your email address to be recorded in any newly created commits.
abda1ef5 294 Can be overridden by the 'GIT_AUTHOR_EMAIL' and 'GIT_COMMITTER_EMAIL'
1ab661dd
PB
295 environment variables. See gitlink:git-commit-tree[1].
296
297user.name::
298 Your full name to be recorded in any newly created commits.
abda1ef5 299 Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME'
1ab661dd
PB
300 environment variables. See gitlink:git-commit-tree[1].
301
302whatchanged.difftree::
303 The default gitlink:git-diff-tree[1] arguments to be used
304 for gitlink:git-whatchanged[1].
305
306imap::
307 The configuration variables in the 'imap' section are described
308 in gitlink:git-imap-send[1].
199a9218 309
fc04c412
SP
310receive.unpackLimit::
311 If the number of objects received in a push is below this
312 limit then the objects will be unpacked into loose object
313 files. However if the number of received objects equals or
314 exceeds this limit then the received pack will be stored as
315 a pack, after adding any missing delta bases. Storing the
316 pack from a push can make the push operation complete faster,
317 especially on slow filesystems.
318
319receive.denyNonFastForwards::
199a9218
JS
320 If set to true, git-receive-pack will deny a ref update which is
321 not a fast forward. Use this to prevent such an update via a push,
322 even if that push is forced. This configuration variable is
323 set when initializing a shared repository.
324