git-config: Improve documentation of git-config file handling
The description which files git-config uses and how the various command line options and environment variables affect its behaviour was incomplete, outdated and confusing. Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de> Signed-off-by: Junio C Hamano <junkio@cox.net>
Frank Lichtenheld committed
May 31, 2007 at 02:35 UTC
17014090036b9b996707dfca5af69f1e87bd2315
1 file changed
+59
-7
Documentation/git-config.txt
+59
-7
@@ -75,11 +75,22 @@ OPTIONS
75
Like --get-all, but interprets the name as a regular expression.
76
77
--global::
78
- Use global ~/.gitconfig file rather than the repository .git/config.
78
+ For writing options: write to global ~/.gitconfig file rather than
79
+ the repository .git/config.
80
++
81
+For reading options: read only from global ~/.gitconfig rather than
82
+from all available files.
83
++
84
+See also <<FILES>>.
85
86
--system::
81
- Use system-wide $(prefix)/etc/gitconfig rather than the repository
82
- .git/config.
87
+ For writing options: write to system-wide $(prefix)/etc/gitconfig
88
+ rather than the repository .git/config.
89
++
90
+For reading options: read only from system-wide $(prefix)/etc/gitconfig
91
+rather than from all available files.
92
++
93
+See also <<FILES>>.
94
95
--remove-section::
96
Remove the given section from the configuration file.
@@ -106,18 +117,59 @@ OPTIONS
117
by 1024, 1048576, or 1073741824 prior to output.
118
119
120
+[[FILES]]
121
+FILES
122
+-----
123
+
124
+There are three files where git-config will search for configuration
125
+options:
126
+
127
+.git/config::
128
+ Repository specific configuration file. (The filename is
129
+ of course relative to the repository root, not the working
130
+ directory.)
131
+
132
+~/.gitconfig::
133
+ User-specific configuration file. Also called "global"
134
+ configuration file.
135
+
136
+$(prefix)/etc/gitconfig::
137
+ System-wide configuration file.
138
+
139
+If no further options are given, all reading options will read all of these
140
+files that are available. If the global or the system-wide configuration
141
+file are not available they will be ignored. If the repository configuration
142
+file is not available or readable, git-config will exit with a non-zero
143
+error code. However, in neither case will an error message be issued.
144
+
145
+All writing options will per default write to the repository specific
146
+configuration file. Note that this also affects options like '--replace-all'
147
+and '--unset'. *git-config will only ever change one file at a time*.
148
+
149
+You can override these rules either by command line options or by environment
150
+variables. The '--global' and the '--system' options will limit the file used
151
+to the global or system-wide file respectively. The GIT_CONFIG environment
152
+variable has a similar effect, but you can specify any filename you want.
153
+
154
+The GIT_CONFIG_LOCAL environment variable on the other hand only changes
155
+the name used instead of the repository configuration file. The global and
156
+the system-wide configuration files will still be read. (For writing options
157
+this will obviously result in the same behavior as using GIT_CONFIG.)
158
+
159
+
160
ENVIRONMENT
161
-----------
162
163
GIT_CONFIG::
164
Take the configuration from the given file instead of .git/config.
114
- Using the "--global" option forces this to ~/.gitconfig.
165
+ Using the "--global" option forces this to ~/.gitconfig. Using the
166
+ "--system" option forces this to $(prefix)/etc/gitconfig.
167
168
GIT_CONFIG_LOCAL::
117
- Currently the same as $GIT_CONFIG; when Git will support global
118
- configuration files, this will cause it to take the configuration
119
- from the global configuration file in addition to the given file.
169
+ Take the configuration from the given file instead if .git/config.
170
+ Still read the global and the system-wide configuration files, though.
171
172
+See also <<FILES>>.
173
174
175
[[EXAMPLES]]