[PATCH] add documentation for writing config files

[PATCH] add documentation for writing config files

[Tanay Abhra]

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>
---
 Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index 230b3a0..df08385 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
 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 all 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.
-- 
1.9.0.GIT

Re: [PATCH] add documentation for writing config files

[Philip Oakley]

minor nit.
From: "Tanay Abhra" <tanayabh@gmail.com>
> 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>
> ---
> Documentation/technical/api-config.txt | 31 
> ++++++++++++++++++++++++++++++-
> 1 file changed, 30 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/technical/api-config.txt 
> b/Documentation/technical/api-config.txt
> index 230b3a0..df08385 100644
> --- a/Documentation/technical/api-config.txt
> +++ b/Documentation/technical/api-config.txt
> @@ -137,4 +137,33 @@ int read_file_with_include(const char *file, 
> config_fn_t fn, void *data)
> 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 all call `git_config_set_multivar_in_file` which 
> takes

s/both //    'both all' is a bit tautological.

> +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.
> -- 
> 1.9.0.GIT
>
> --
Philip 

[PATCH v2] add documentation for writing config files

[Tanay Abhra]

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>
---
Minor nit corrected. Thanks for the review.

 Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index 230b3a0..edd5018 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
 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.
-- 
1.9.0.GIT

[PATCH v2] add documentation for writing config files

[Tanay Abhra]

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>
---
 Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index 230b3a0..edd5018 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
 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.
-- 
1.9.0.GIT

Re: [PATCH v2] add documentation for writing config files

[Matthieu Moy]

Tanay Abhra <tanayabh@gmail.com> writes:

> 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>
> ---
>  Documentation/technical/api-config.txt | 31 ++++++++++++++++++++++++++++++-

Sounds good to me, thanks.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/