{"thread":{"id":"36813","subject":"[PATCH] config: Add documentation for writing config files","startedAt":"2014-06-02T13:27:01Z","lastAt":"2014-06-03T08:43:37Z","messageCount":3,"participants":["Tanay Abhra","Matthieu Moy"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"243128","messageId":"1401715621-3681-1-git-send-email-tanayabh@gmail.com","threadId":"36813","inReplyTo":null,"subject":"[PATCH] config: Add documentation for writing config files","fromName":"Tanay Abhra","fromEmail":"tanayabh@gmail.com","sentAt":"2014-06-02T13:27:01Z","receivedAt":"2014-06-02T13:27:01Z","isPatch":true,"sender":{"key":"tanayabh@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2097229?v=4"},"body":"Signed-off-by: Tanay Abhra <tanayabh@gmail.com>\n---\n Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-\n 1 file changed, 30 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex 230b3a0..df08385 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)\n Writing Config Files\n --------------------\n \n-TODO\n+Git gives multiple entry points in the Config API to write config values to\n+files namely `git_config_set_in_file` and `git_config_set`, which write to\n+a specific config file or to `.git/config` respectively. They both take a\n+key/value pair as parameter.\n+In the end they both all call `git_config_set_multivar_in_file` which takes\n+four parameters:\n+\n+- the name of the file, as a string, to which key/value pairs will be written.\n+\n+- the name of key, as a string. This is in canonical \"flat\" form: the section,\n+  subsection, and variable segments will be separated by dots, and the section\n+  and variable segments will be all lowercase.\n+  E.g., `core.ignorecase`, `diff.SomeType.textconv`.\n+\n+- the value of the variable, as a string. If value is equal to NULL, it will\n+  remove the matching key from the config file.\n+\n+- the value regex, as a string. It will disregard key/value pairs where value\n+  does not match.\n+\n+- a multi_replace value, as an int. If value is equal to zero, nothing or only\n+  one matching key/value is replaced, else all matching key/values (regardless\n+  how many) are removed, before the new pair is written.\n+\n+It returns 0 on success.\n+\n+Also, there are functions `git_config_rename_section` and\n+`git_config_rename_section_in_file` with parameters `old_name` and `new_name`\n+for renaming or removing sections in the config files. If NULL is passed\n+through `new_name` parameter, the section will be removed from the config file.\n-- \n1.9.0.GIT\n"},{"id":"243151","messageId":"vpq38fnf6go.fsf@anie.imag.fr","threadId":"36813","inReplyTo":"1401715621-3681-1-git-send-email-tanayabh@gmail.com","subject":"Re: [PATCH] config: Add documentation for writing config files","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2014-06-02T19:37:43Z","receivedAt":"2014-06-02T19:37:43Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Tanay Abhra <tanayabh@gmail.com> writes:\n\n> Signed-off-by: Tanay Abhra <tanayabh@gmail.com>\n> ---\n>  Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-\n>  1 file changed, 30 insertions(+), 1 deletion(-)\n\nEven though the reason to replace a TODO with real stuff is rather\nstraigthforward, the reader appriates a short commit message (ideally\npointing to the commit introducing the TODO). My first thought reading\nthe patch was \"wtf, is that a patch in the middle of a series, where\ndoes this TODO come from\" ;-).\n\n> diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\n> index 230b3a0..df08385 100644\n> --- a/Documentation/technical/api-config.txt\n> +++ b/Documentation/technical/api-config.txt\n> @@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)\n>  Writing Config Files\n>  --------------------\n>  \n> -TODO\n> +Git gives multiple entry points in the Config API to write config values to\n> +files namely `git_config_set_in_file` and `git_config_set`, which write to\n> +a specific config file or to `.git/config` respectively. They both take a\n> +key/value pair as parameter.\n\nSounds good.\n\n> +In the end they both all call `git_config_set_multivar_in_file` which takes\n> +four parameters:\n\nDo we really want to document this as part of the config API? i.e. does\na normal user of the API want to know about this? My understanding is\nthat git_config_set_multivar_in_file is essentially a private function,\nand then the best place to document is with comments near the function\ndefinition (it already has such comment).\n\nYour text is easier to understand and more detailed, but I would\npersonnally prefer improving the in-code comment (possibly just leaving\na mention of git_config_set_multivar_in_file and pointing the reader to\nthe code for details).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"243185","messageId":"538D8AB9.4010800@gmail.com","threadId":"36813","inReplyTo":"vpq38fnf6go.fsf@anie.imag.fr","subject":"Re: [PATCH] config: Add documentation for writing config files","fromName":"Tanay Abhra","fromEmail":"tanayabh@gmail.com","sentAt":"2014-06-03T08:43:37Z","receivedAt":"2014-06-03T08:43:37Z","isPatch":true,"sender":{"key":"tanayabh@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2097229?v=4"},"body":"On 06/02/2014 12:37 PM, Matthieu Moy wrote:\n> Tanay Abhra <tanayabh@gmail.com> writes:\n> \n>> Signed-off-by: Tanay Abhra <tanayabh@gmail.com>\n>> ---\n>>  Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-\n>>  1 file changed, 30 insertions(+), 1 deletion(-)\n> \n> Even though the reason to replace a TODO with real stuff is rather\n> straigthforward, the reader appriates a short commit message (ideally\n> pointing to the commit introducing the TODO). My first thought reading\n> the patch was \"wtf, is that a patch in the middle of a series, where\n> does this TODO come from\" ;-).\n\nOk, I will send a new patch with the updated commit message. .\n\n>> +In the end they both all call `git_config_set_multivar_in_file` which takes\n>> +four parameters:\n> \n> Do we really want to document this as part of the config API? i.e. does\n> a normal user of the API want to know about this? My understanding is\n> that git_config_set_multivar_in_file is essentially a private function,\n> and then the best place to document is with comments near the function\n> definition (it already has such comment).\n\nSorry, but I don't think so. In cache.h, the following functions have been provided\nas externs,\ngit_config_set_in_file()\ngit_config_set()\ngit_config_set_multivar()\ngit_config_set_multivar_in_file()\nextern int git_config_rename_section()\nextern int git_config_rename_section_in_file()\n\nThus, they seem to be the part of the API. In most of the technical API docs I have\nread there is at least a description of all parameters of the main function also,\nrelevant data structures if any.\nAlso a certain amount of redundancy about details is allowed.\n\nA good example is api-hashmap.txt which provides detailed descriptions of each\nfunction and data structure which was very much helpful to me.\n\nReverse is api-string-list.txt which was useless to me, so I had to go through\nthe whole code to understand how to use it.\n\nThanks for the review.\n"}]}