Merge branch 'jk/prune-top-level-refs-after-packing'
[gitweb.git] / Documentation / technical / api-config.txt
index 815c1eecc3ddec98825d2d89e13899250c098238..0d8b99b368aea13a322382314d88229acda0b1db 100644 (file)
@@ -155,6 +155,19 @@ as well as retrieval for the queried variable, including:
        Similar to `git_config_get_string`, but expands `~` or `~user` into
        the user's home directory when found at the beginning of the path.
 
+`git_die_config(const char *key, const char *err, ...)`::
+
+       First prints the error message specified by the caller in `err` and then
+       dies printing the line number and the file name of the highest priority
+       value for the configuration variable `key`.
+
+`void git_die_config_linenr(const char *key, const char *filename, int linenr)`::
+
+       Helper function which formats the die error message according to the
+       parameters entered. Used by `git_die_config()`. It can be used by callers
+       handling `git_config_get_value_multi()` to print the correct error message
+       for the desired value.
+
 See test-config.c for usage examples.
 
 Value Parsing Helpers
@@ -279,4 +292,33 @@ They all behave similarly to the `git_config_get*()` family described in
 Writing Config Files
 --------------------
 
-TODO
+Git gives multiple entry points in the Config API to write config values to
+files namely `git_config_set_in_file` and `git_config_set`, which write to
+a specific config file or to `.git/config` respectively. They both take a
+key/value pair as parameter.
+In the end they both call `git_config_set_multivar_in_file` which takes four
+parameters:
+
+- the name of the file, as a string, to which key/value pairs will be written.
+
+- the name of key, as a string. This is in canonical "flat" form: the section,
+  subsection, and variable segments will be separated by dots, and the section
+  and variable segments will be all lowercase.
+  E.g., `core.ignorecase`, `diff.SomeType.textconv`.
+
+- the value of the variable, as a string. If value is equal to NULL, it will
+  remove the matching key from the config file.
+
+- the value regex, as a string. It will disregard key/value pairs where value
+  does not match.
+
+- a multi_replace value, as an int. If value is equal to zero, nothing or only
+  one matching key/value is replaced, else all matching key/values (regardless
+  how many) are removed, before the new pair is written.
+
+It returns 0 on success.
+
+Also, there are functions `git_config_rename_section` and
+`git_config_rename_section_in_file` with parameters `old_name` and `new_name`
+for renaming or removing sections in the config files. If NULL is passed
+through `new_name` parameter, the section will be removed from the config file.