@matheusbsbs / matheus-bagliano / commits / 1ab661ddb7
Fork 0

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