Re: [REQUEST 1/1] docs: update http.url.* options documentation
Junio C Hamano gits...@pobox.com writes: Will queue the attached, unless you spot glaring errors made by me, coding while drunk ;-) ... aand, it turns out that I screwed up while running git commit --amend (missed -a). I should go to bed now. -- 8 -- From: Kyle J. McKay mack...@gmail.com Date: Thu, 25 Jul 2013 15:39:13 -0700 Subject: [PATCH] docs: update http.url.* options documentation 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. Signed-off-by: Jeff King p...@peff.net Signed-off-by: Kyle J. McKay mack...@gmail.com Signed-off-by: Junio C Hamano gits...@pobox.com --- Documentation/config.txt | 63 ++-- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 6b135be..60c140f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1515,30 +1515,47 @@ 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://u...@example.com/path; and -https://example.com/path/name; are used as a config url value and -then https://u...@example.com/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://u...@example.com/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/`). + +. User name (e.g., `user` in `https://u...@example.com/repo.git`). If + the config key has a user name it must match the user name in the + URL exactly. If the 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://u...@example.com/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://u...@example.com`. ++ +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
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Jul 25, 2013, at 21:37, Jeff King wrote: On Thu, Jul 25, 2013 at 03:39:13PM -0700, Kyle J. McKay wrote: 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. --- Signed-off-by: Jeff King p...@peff.net Thank you. Added. You should add your S-O-B, too, for your bits. Yes. I wanted to make certain it didn't get applied just yet. :) +-- +. 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. These look fine in the rendered manpage, but I think the source might be a little easier to read with a blank line between items. My ASCIIDOC is a bit weak. I have added some blank lines. +. Exact user name match (e.g., `user` in `https://u...@example.com/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). IMHO, this would be more clear as a single item, like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none). The only problem I have with a single item is what's the precedence? Does an exact user match have the same precedence as an any-user match? That would seem to be implied by having them as the same item number. Separating them would appear to make it clearer that an exact user match wins over an any user match, but if you have some alternate text as a suggestion for the single item that clears that up... :) +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. And this nicely ties up the open questions I had after re-reading the list. Good. We could define equivalent here (the %-encoding thing is obvious, I think, but which components are case-sensitive and which are not is perhaps a bit subtle). I do not necessarily know that it is useful to the user, though, and is one more thing to confuse them. And somebody who really cares can look at the appropriate RFCs. I am considering this text to address that: All URLs are normalized (%-encodings are standardized, case- insensitive parts are lowercased, `./` and `../` path components are resolved) before attempting any matching (the password part, if embedded in the URL, but I'm not sure the extra verbiage makes it better. I think it may just complicate the explanation unnecessarily? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Jul 25, 2013, at 23:23, Kyle J. McKay wrote: On Jul 25, 2013, at 21:37, Jeff King wrote: You should add your S-O-B, too, for your bits. Yes. I wanted to make certain it didn't get applied just yet. :) Looks like it got patch snarfed anyway. ;-) On Jul 25, 2013, at 23:07, Junio C Hamano wrote: Junio C Hamano gits...@pobox.com writes: Will queue the attached, unless you spot glaring errors made by me, coding while drunk ;-) On Jul 25, 2013, at 21:37, Jeff King wrote: So this patch looks pretty good to me; the two points I raised above are how I would have done it, but they are relatively minor if you do not agree. So Yeah, looks pretty good to me too then. ;) -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Thu, Jul 25, 2013 at 11:23:23PM -0700, Kyle J. McKay wrote: IMHO, this would be more clear as a single item, like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none). The only problem I have with a single item is what's the precedence? Does an exact user match have the same precedence as an any-user match? That would seem to be implied by having them as the same item number. Separating them would appear to make it clearer that an exact user match wins over an any user match, but if you have some alternate text as a suggestion for the single item that clears that up... :) Ah, I see your thinking now. You want to say no username has less precedence than some username, which has less precedence than a path, so they are all elements of a single list. My thinking was username has precedence less than path, and like a shorter path has less precedence than a longer path, an empty username has less precedence than a non-empty username. I agree my suggested wording would need to mention that explicitly. Like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none), but at lower precedence than a config key with a user name. I can live with it either way, though. They are just two ways of considering the same thing. I am considering this text to address that: All URLs are normalized (%-encodings are standardized, case-insensitive parts are lowercased, `./` and `../` path components are resolved) before attempting any matching (the password part, if embedded in the URL, but I'm not sure the extra verbiage makes it better. I think it may just complicate the explanation unnecessarily? Yeah, I think I agree. Let's leave it out. -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Jul 26, 2013, at 15:27, Jeff King wrote: On Thu, Jul 25, 2013 at 11:23:23PM -0700, Kyle J. McKay wrote: IMHO, this would be more clear as a single item, like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none). The only problem I have with a single item is what's the precedence? Does an exact user match have the same precedence as an any-user match? That would seem to be implied by having them as the same item number. Separating them would appear to make it clearer that an exact user match wins over an any user match, but if you have some alternate text as a suggestion for the single item that clears that up... :) Ah, I see your thinking now. You want to say no username has less precedence than some username, which has less precedence than a path, so they are all elements of a single list. My thinking was username has precedence less than path, and like a shorter path has less precedence than a longer path, an empty username has less precedence than a non-empty username. I agree my suggested wording would need to mention that explicitly. Like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none), but at lower precedence than a config key with a user name. I can live with it either way, though. They are just two ways of considering the same thing. I am considering this text to address that: All URLs are normalized (%-encodings are standardized, case- insensitive parts are lowercased, `./` and `../` path components are resolved) before attempting any matching (the password part, if embedded in the URL, but I'm not sure the extra verbiage makes it better. I think it may just complicate the explanation unnecessarily? Yeah, I think I agree. Let's leave it out. So there's a version of this in next as cea9928 and I think that version is fine. If the documentation gets updated in the future, or perhaps moved to a separate urls-matching.txt for some reason at some point (git config --url, git config --url-parse), I'll make a point of inserting the , but at lower precedence than a config key with a user name text. Kyle -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Fri, Jul 26, 2013 at 07:15:07PM -0700, Kyle J. McKay wrote: So there's a version of this in next as cea9928 and I think that version is fine. If the documentation gets updated in the future, or perhaps moved to a separate urls-matching.txt for some reason at some point (git config --url, git config --url-parse), I'll make a point of inserting the , but at lower precedence than a config key with a user name text. Unless you are planning to do that immediately, we are very likely to forget. Either it is worth adding or not, and if it is, we should not let having to add one more commit stop us. Here it is in patch form, so the amount of effort does not influence our decision. :) I'd lean towards including it, but don't feel strongly. -- 8 -- Subject: [PATCH] docs: mention precedence of empty username matching in URLs The documentation makes it clear that a URL with a username will match a config entry with or without a username, but is not clear that in the presence of both, the one with username would be preferred. Signed-off-by: Jeff King p...@peff.net --- Documentation/config.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 0dd5566..f2ed9ef 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1568,7 +1568,8 @@ http.url.*:: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that - config key will match a URL with any user name (including none). + config key will match a URL with any user name (including none), + but at a lower precedence than a config key with a user name. -- + The list above is ordered by decreasing precedence; a URL that matches -- 1.8.3.rc1.30.gff0fb75 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Jul 26, 2013, at 19:43, Jeff King wrote: On Fri, Jul 26, 2013 at 07:15:07PM -0700, Kyle J. McKay wrote: So there's a version of this in next as cea9928 and I think that version is fine. If the documentation gets updated in the future, or perhaps moved to a separate urls-matching.txt for some reason at some point (git config --url, git config --url-parse), I'll make a point of inserting the , but at lower precedence than a config key with a user name text. Unless you are planning to do that immediately, we are very likely to forget. Either it is worth adding or not, and if it is, we should not let having to add one more commit stop us. Here it is in patch form, so the amount of effort does not influence our decision. :) I'd lean towards including it, but don't feel strongly. -- 8 -- Subject: [PATCH] docs: mention precedence of empty username matching in URLs The documentation makes it clear that a URL with a username will match a config entry with or without a username, but is not clear that in the presence of both, the one with username would be preferred. Signed-off-by: Jeff King p...@peff.net --- Documentation/config.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 0dd5566..f2ed9ef 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1568,7 +1568,8 @@ http.url.*:: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that - config key will match a URL with any user name (including none). + config key will match a URL with any user name (including none), + but at a lower precedence than a config key with a user name. -- + The list above is ordered by decreasing precedence; a URL that matches -- 1.8.3.rc1.30.gff0fb75 I like it. :) +1 for adding it as an incremental patch to next. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[REQUEST 1/1] docs: update http.url.* options documentation
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://u...@example.com/path; and -https://example.com/path/name; are used as a config url value and -then https://u...@example.com/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://u...@example.com/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://u...@example.com/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://u...@example.com/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://u...@example.com`. ++ +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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
On Thu, Jul 25, 2013 at 03:39:13PM -0700, Kyle J. McKay wrote: 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. --- Signed-off-by: Jeff King p...@peff.net You should add your S-O-B, too, for your bits. +-- +. 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. These look fine in the rendered manpage, but I think the source might be a little easier to read with a blank line between items. +. 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. Thanks, I forgot to include port number in my original suggested text. +. Exact user name match (e.g., `user` in `https://u...@example.com/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). IMHO, this would be more clear as a single item, like: . User name (e.g., `user` in `https://u...@example.com/repo.git`). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none). +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. And this nicely ties up the open questions I had after re-reading the list. Good. We could define equivalent here (the %-encoding thing is obvious, I think, but which components are case-sensitive and which are not is perhaps a bit subtle). I do not necessarily know that it is useful to the user, though, and is one more thing to confuse them. And somebody who really cares can look at the appropriate RFCs. So this patch looks pretty good to me; the two points I raised above are how I would have done it, but they are relatively minor if you do not agree. -Peff -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [REQUEST 1/1] docs: update http.url.* options documentation
Jeff King p...@peff.net writes: Signed-off-by: Jeff King p...@peff.net You should add your S-O-B, too, for your bits. ... So this patch looks pretty good to me; the two points I raised above are how I would have done it, but they are relatively minor if you do not agree. Will queue the attached, unless you spot glaring errors made by me, coding while drunk ;-) -- 8 -- From: Kyle J. McKay mack...@gmail.com Date: Thu, 25 Jul 2013 15:39:13 -0700 Subject: [PATCH] docs: update http.url.* options documentation 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. Signed-off-by: Jeff King p...@peff.net Signed-off-by: Kyle J. McKay mack...@gmail.com Signed-off-by: Junio C Hamano gits...@pobox.com --- Documentation/config.txt | 60 +--- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 6b135be..ec852ab 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://u...@example.com/path; and -https://example.com/path/name; are used as a config url value and -then https://u...@example.com/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://u...@example.com/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://u...@example.com/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://u...@example.com/foo/bar` a config key match of +`https://example.com/foo` will be preferred over a config key match of +`https://u...@example.com`. ++ +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
