[REQUEST 1/1] docs: update http.<url>.* options documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]