Overhaul the text of the http.<url>.* options documentation providing a hopefully easier to understand itemized list of matching behavior as suggested by and including text from Jeff King. --- Documentation/config.txt | 60 +++++++++++++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 6b135be..8ff966d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1515,30 +1515,44 @@ http.useragent:: http.<url>.*:: Any of the http.* options above can be applied selectively to some urls. - For example "http.https://example.com.useragent"; would set the user - agent only for https connections to example.com. The <url> value - matches a url if it refers to the same scheme, host and port and the - path portion is an exact match or a prefix that matches at a "/" - boundary. If <url> does not include a user name, it will match a url - with any username otherwise the user name must match as well (the - password part, if present in the url, is always ignored). A <url> - with longer path matches takes precedence over shorter matches no matter - what order they occur in the configuration file. + For a config key to match a URL, each element of the config key is + compared to that of the URL, in the following order: + -For example, if both "https://user@xxxxxxxxxxx/path"; and -"https://example.com/path/name"; are used as a config <url> value and -then "https://user@xxxxxxxxxxx/path/name/here"; is passed to a git -command, the settings in the "https://example.com/path/name"; section -will be preferred because that <url> has a longer path length match than -"https://user@xxxxxxxxxxx/path"; even though the latter did match the -user. For same length matches, the last one wins except that a same -length <url> match that includes a user name will be preferred over a -same length <url> match that does not. The urls are normalized before -matching so that equivalent urls that are simply spelled differently -will match properly. Environment variable settings always override any -matches. The urls that are matched against are those given directly to -git commands. This means any urls visited as a result of a redirection -do not participate in matching. +-- +. Scheme (e.g., `https` in `https://example.com/`). This field + must match exactly between the config key and the URL. +. Host/domain name (e.g., `example.com` in `https://example.com/`). + This field must match exactly between the config key and the URL. +. Port number (e.g., `8080` in `http://example.com:8080/`). + This field must match exactly between the config key and the URL. + Omitted port numbers are automatically converted to the correct + default for the scheme before matching. +. Path (e.g., `repo.git` in `https://example.com/repo.git`). The + path field of the config key must match the path field of the URL + either exactly or as a prefix of slash-delimited path elements. This means + a config key with path `foo/` matches URL path `foo/bar`. A prefix can only + match on a slash (`/`) boundary. Longer matches take precedence (so a config + key with path `foo/bar` is a better match to URL path `foo/bar` than a config + key with just path `foo/`). +. Exact user name match (e.g., `user` in `https://user@xxxxxxxxxxx/repo.git`). + If the config key has a user name it must match the user name in the URL + exactly. +. Any user name match. If a config key does not have a user name, that config + key will match a URL with any user name (including none). +-- ++ +The list above is ordered by decreasing precedence; a URL that matches +a config key's path is preferred to one that matches its user name. For example, +if the URL is `https://user@xxxxxxxxxxx/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://user@xxxxxxxxxxx`. ++ +All URLs are normalized before attempting any matching (the password part, +if embedded in the URL, is always ignored for matching purposes) so that +equivalent urls that are simply spelled differently will match properly. +Environment variable settings always override any matches. The urls that are +matched against are those given directly to Git commands. This means any URLs +visited as a result of a redirection do not participate in matching. i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself -- 1.8.3 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html