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 <peff@xxxxxxxx>
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://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).
IMHO, this would be more clear as a single item, like:
. User name (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. 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html