path: root/Documentation/technical/api-config.txt
diff options
authorJeff King <>2012-02-06 09:54:04 (GMT)
committerJunio C Hamano <>2012-02-17 15:59:55 (GMT)
commit9b25a0b52e09400719366f0a33d0d0da98bbf7b0 (patch)
tree35f8ac15096787f3a90b775fe29fc93054b6989e /Documentation/technical/api-config.txt
parent4a7bb5ba950f08d1e46c4bd2e8b1c903b4d024c8 (diff)
config: add include directive
It can be useful to split your ~/.gitconfig across multiple files. For example, you might have a "main" file which is used on many machines, but a small set of per-machine tweaks. Or you may want to make some of your config public (e.g., clever aliases) while keeping other data back (e.g., your name or other identifying information). Or you may want to include a number of config options in some subset of your repos without copying and pasting (e.g., you want to reference them from the .git/config of participating repos). This patch introduces an include directive for config files. It looks like: [include] path = /path/to/file This is syntactically backwards-compatible with existing git config parsers (i.e., they will see it as another config entry and ignore it unless you are looking up include.path). The implementation provides a "git_config_include" callback which wraps regular config callbacks. Callers can pass it to git_config_from_file, and it will transparently follow any include directives, passing all of the discovered options to the real callback. Include directives are turned on automatically for "regular" git config parsing. This includes calls to git_config, as well as calls to the "git config" program that do not specify a single file (e.g., using "-f", "--global", etc). They are not turned on in other cases, including: 1. Parsing of other config-like files, like .gitmodules. There isn't a real need, and I'd rather be conservative and avoid unnecessary incompatibility or confusion. 2. Reading single files via "git config". This is for two reasons: a. backwards compatibility with scripts looking at config-like files. b. inspection of a specific file probably means you care about just what's in that file, not a general lookup for "do we have this value anywhere at all". If that is not the case, the caller can always specify "--includes". 3. Writing files via "git config"; we want to treat include.* variables as literal items to be copied (or modified), and not expand them. So "git config --unset-all" would operate _only_ on .git/config, not any of its included files (just as it also does not operate on ~/.gitconfig). Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical/api-config.txt')
1 files changed, 27 insertions, 1 deletions
diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index b0aeb2e..edf8dfb 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -52,13 +52,17 @@ 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 one extra parameter:
+process. It takes two extra parameters:
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`.
+Specify whether include directives should be followed in parsed files.
+Regular `git_config` defaults to `1`.
There is a special version of `git_config` called `git_config_early`.
This version takes an additional parameter to specify the repository
config, instead of having it looked up via `git_path`. This is useful
@@ -108,6 +112,28 @@ string is given, prints an error message and returns -1.
Similar to `git_config_string`, but expands `~` or `~user` into the
user's home directory when found at the beginning of the path.
+Include Directives
+By default, the config parser does not respect include directives.
+However, a caller can use the special `git_config_include` wrapper
+callback to support them. To do so, you simply wrap your "real" callback
+function and data pointer in a `struct config_include_data`, and pass
+the wrapper to the regular config-reading functions. For example:
+int read_file_with_include(const char *file, config_fn_t fn, void *data)
+ struct config_include_data inc = CONFIG_INCLUDE_INIT;
+ inc.fn = fn;
+ = data;
+ return git_config_from_file(git_config_include, file, &inc);
+`git_config` respects includes automatically. The lower-level
+`git_config_from_file` does not.
Writing Config Files