Subject: Re: [PATCH] doc: fix config API documentation about config_with_options

From: Brandon Williams <[email-masked]>
Date: Wed, 9 May 2018 10:19:50 -0700

On 05/09, Antonio Ospite wrote:
> In commit dc8441fdb ("config: don't implicitly use gitdir or commondir",
> 2017-06-14) the function git_config_with_options was renamed to
> config_with_options to better reflect the fact that it does not access
> the git global config or the repo config by default.
> 
> However Documentation/technical/api-config.txt still refers to the
> previous name, fix that.
> 
> While at it also update the documentation about the extra parameters,
> because they too changed since the initial definition.
> 
> Signed-off-by: Antonio Ospite <[email-masked]>
> ---
> 
> Patch based on the maint branch.

Thanks for updating the docs.  Maybe one day we can migrate these docs
to the source files themselves, making it easier to keep up to date.
For now this is good :)

> 
> Ciao,
>    Antonio
> 
>  Documentation/technical/api-config.txt | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
> index 9a778b0ca..fa39ac9d7 100644
> --- a/Documentation/technical/api-config.txt
> +++ b/Documentation/technical/api-config.txt
> @@ -47,21 +47,23 @@ will first feed the user-wide one to the callback, and then the
>  repo-specific one; by overwriting, the higher-priority repo-specific
>  value is left at the end).
>  
> -The `git_config_with_options` function lets the caller examine config
> +The `config_with_options` function lets the caller examine config
>  while adjusting some of the default behavior of `git_config`. It should
>  almost never be used by "regular" Git code that is looking up
>  configuration variables. It is intended for advanced callers like
>  `git-config`, which are intentionally tweaking the normal config-lookup
>  process. It takes two extra parameters:
>  
> -`filename`::
> -If this parameter is non-NULL, it specifies the name of a file to
> -parse for configuration, rather than looking in the usual files. Regular
> -`git_config` defaults to `NULL`.
> +`config_source`::
> +If this parameter is non-NULL, it specifies the source to parse for
> +configuration, rather than looking in the usual files. See `struct
> +git_config_source` in `config.h` for details. Regular `git_config` defaults
> +to `NULL`.
>  
> -`respect_includes`::
> -Specify whether include directives should be followed in parsed files.
> -Regular `git_config` defaults to `1`.
> +`opts`::
> +Specify options to adjust the behavior of parsing config files. See `struct
> +config_options` in `config.h` for details. As an example: regular `git_config`
> +sets `opts.respect_includes` to `1` by default.
>  
>  Reading Specific Files
>  ----------------------
> -- 
> 2.17.0
> 

-- 
Brandon Williams