add documentation for writing config files
Replace TODO introduced in commit 9c3c22 with documentation explaining Git config API functions for writing configuration files. Signed-off-by: Tanay Abhra <tanayabh@gmail.com> Reviewed-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Tanay Abhra committed
Jul 28, 2014 at 03:42 UTC
97d6e799aaa5048a3a5f57c11b5685be0a5a5a52
1 file changed
+30
-1
Documentation/technical/api-config.txt
+30
-1
@@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
137
Writing Config Files
138
--------------------
139
140
-TODO
140
+Git gives multiple entry points in the Config API to write config values to
141
+files namely `git_config_set_in_file` and `git_config_set`, which write to
142
+a specific config file or to `.git/config` respectively. They both take a
143
+key/value pair as parameter.
144
+In the end they both call `git_config_set_multivar_in_file` which takes four
145
+parameters:
146
+
147
+- the name of the file, as a string, to which key/value pairs will be written.
148
+
149
+- the name of key, as a string. This is in canonical "flat" form: the section,
150
+ subsection, and variable segments will be separated by dots, and the section
151
+ and variable segments will be all lowercase.
152
+ E.g., `core.ignorecase`, `diff.SomeType.textconv`.
153
+
154
+- the value of the variable, as a string. If value is equal to NULL, it will
155
+ remove the matching key from the config file.
156
+
157
+- the value regex, as a string. It will disregard key/value pairs where value
158
+ does not match.
159
+
160
+- a multi_replace value, as an int. If value is equal to zero, nothing or only
161
+ one matching key/value is replaced, else all matching key/values (regardless
162
+ how many) are removed, before the new pair is written.
163
+
164
+It returns 0 on success.
165
+
166
+Also, there are functions `git_config_rename_section` and
167
+`git_config_rename_section_in_file` with parameters `old_name` and `new_name`
168
+for renaming or removing sections in the config files. If NULL is passed
169
+through `new_name` parameter, the section will be removed from the config file.