config: Cleanup external API

Do not mess with environment variables anymore. The new external API has
more helper methods, and everything is explicit.

2 files changed, 65 insertions, 17 deletions

diff --git a/include/git2/config.h b/include/git2/config.h
index 502b0ae33..7be45b176 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -76,34 +76,54 @@ GIT_EXTERN(int) git_config_file__ondisk(struct git_config_file **out, const char
 GIT_EXTERN(int) git_config_new(git_config **out);
 
 /**
- * Open a configuration file
+ * Add a generic config file instance to an existing config
  *
- * This creates a new configuration object and adds the specified file
- * to it.
+ * Note that the configuration object will free the file
+ * automatically.
  *
- * @param cfg_out pointer to the configuration data
- * @param path where to load the confiration from
- */
-GIT_EXTERN(int) git_config_open_file(git_config **cfg_out, const char *path);
-
-/**
- * Open the global configuration file at $HOME/.gitconfig
+ * Further queries on this config object will access each
+ * of the config file instances in order (instances with
+ * a higher priority will be accessed first).
  *
- * @param cfg pointer to the configuration
+ * @param cfg the configuration to add the file to
+ * @param file the configuration file (backend) to add
+ * @param priority the priority the backend should have
  */
-GIT_EXTERN(int) git_config_open_global(git_config **cfg);
+GIT_EXTERN(int) git_config_add_file(git_config *cfg, git_config_file *file, int priority);
 
 /**
- * Add a config backend to an existing instance
+ * Add an on-disk config file instance to an existing config
+ *
+ * The on-disk file pointed at by `path` will be opened and
+ * parsed; it's expected to be a native Git config file following
+ * the default Git config syntax (see man git-config).
  *
  * Note that the configuration object will free the file
  * automatically.
  *
+ * Further queries on this config object will access each
+ * of the config file instances in order (instances with
+ * a higher priority will be accessed first).
+ *
  * @param cfg the configuration to add the file to
- * @param file the configuration file (backend) to add
+ * @param file path to the configuration file (backend) to add
  * @param priority the priority the backend should have
  */
-GIT_EXTERN(int) git_config_add_file(git_config *cfg, git_config_file *file, int priority);
+GIT_EXTERN(int) git_config_add_file_ondisk(git_config *cfg, const char *path, int priority);
+
+
+/**
+ * Create a new config instance containing a single on-disk file
+ *
+ * This method is a simple utility wrapper for the following sequence
+ * of calls:
+ *	- git_config_new
+ *	- git_config_add_file_ondisk
+ *
+ * @param cfg The configuration instance to create
+ * @param path Path to the on-disk file to open
+ */
+GIT_EXTERN(int) git_config_open_ondisk(git_config **cfg, const char *path);
 
 /**
  * Free the configuration and its associated memory and files
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 5c7903adc..27c3138f7 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -268,12 +268,40 @@ GIT_EXTERN(int) git_repository_is_bare(git_repository *repo);
 /**
  * Retrieve the relevant configuration for a repository
  *
- * Puts together the configuration from the global and local files.
+ * By default he returned `git_config` instance contains a single
+ * configuration file, the `.gitconfig' file that may be found
+ * inside the repository.
+ *
+ * If the `user_config_path` variable is not NULL, the given config
+ * file will be also included in the configuration set. On most UNIX
+ * systems, this file may be found on `$HOME/.gitconfig`.
+ *
+ * If the `system_config_path` variable is not NULL, the given config
+ * file will be also included in the configuration set. On most UNIX
+ * systems, this file may be found on `$PREFIX/etc/gitconfig`.
+ *
+ * The resulting `git_config` instance will query the files in the following
+ * order:
+ *
+ *	- Repository configuration file
+ *	- User configuration file
+ *	- System configuration file
+ *
+ * The method will fail if any of the passed config files cannot be
+ * found or accessed.
+ *
+ * The returned `git_config` instance is owned by the caller and must
+ * be manually free'd once it's no longer on use.
  *
  * @param out the repository's configuration
  * @param repo the repository for which to get the config
+ * @param user_config_path Path to the user config file
+ * @param system_config_path Path to the system-wide config file
  */
-GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo);
+GIT_EXTERN(int) git_repository_config(git_config **out,
+	git_repository *repo,
+	const char *user_config_path,
+	const char *system_config_path);
 
 /** @} */
 GIT_END_DECL