Re: [PATCH] Documentation: clarify multiple pushurls vs urls

From: Calvin Wan <calvinwan@google.com>
Date: Feb 6, 2023, 21:12 UTC
Message-ID: <CAFySSZCO7M8bm8Cc97x7MpZYHd0qWwRHF_YRDmw1rryF6Q7dnQ@mail.gmail.com>
In-Reply-To: <230206.86k00u5ygg.gmgdl@evledraar.gmail.com>

Show 30 quoted lines

> > Defining multiple `url` fields can cause confusion for users since
> > running `git config remote.<remote>.url` returns the last defined url
> > which doesn't align with the url `git fetch <remote>` uses (the first).
>
> I'm certainly confused, I had no idea it worked this way, I'd have thought it was last-set-wins like most things.
>
> From a glance fb0cc87ec0f (Allow programs to not depend on remotes
> having urls, 2009-11-18) mentions it as a known factor, but with:
>
>         diff --git a/transport.c b/transport.c
>         index 77a61a9d7bb..06159c4184e 100644
>         --- a/transport.c
>         +++ b/transport.c
>         @@ -1115,7 +1115,7 @@ struct transport *transport_get(struct remote *remote, const char *url)
>                 helper = remote->foreign_vcs;
>
>                 if (!url && remote->url)
>         -               url = remote->url[0];
>         +               url = remote->url[remote->url_nr - 1];
>                 ret->url = url;
>
>                 /* maybe it is a foreign URL? */
>
> All tests pass for me, and it's selecting the last URL now. I can't find
> any other mention of these semantics in the docs (but maybe I didn't
> look in the right places).
>
> So is this just some accident, does anyone rely on it, and would we be
> better off just "fixing" this, rather than steering people away from
> "url"?

I should've mentioned running `git remote -v` on a config with multiple urls
 shows the correct fetch url, so functionally everything is working as
intended -- just needs a doc update somewhere.

Show 18 quoted lines

> Surely if there's confusion about the priority of the *.url config
> variable we should be documenting that explicitly where we discuss "url"
> itself (e.g. in Documentation/config/remote.txt). Just mentioning it in
> passing as we document "pushUrl" feels like the wrong place.
>
> But I still don't quite see the premise. "git push" has a feature to
> push to all N urls, whether that's Url or pushUrl.
>
> When I configure it to have multiple URLs it pushes to the first
> configured one first, if the source of the confusion was that it didn't
> prefer the last configured one first, shouldn't it be doing them in
> reverse order?
>
> I don't think that would make sense, but I also don't see how
> recommending "pushurl" over "url" un-confuses things.
>
> So why is it confusing that "fetch" would use the same order, but due to
> the semantics of a "fetch" we'd stop after the first one?

I agree with you now that updating the documentation in Documentation/config/remote.txt is the ideal way to go about this, but I'll mention what my original thought process was:

If a user wants one url to push/fetch to, then he defines 'url' If a user wants to push to multiple urls, then he can either define multiple urls or pushurls (one of the pushurls can be the same as the url). But if a user has say url #2 and #3 defined, they act as pushurls anyways, so defining them as such removes any speculation as to what else they could do (and also clears up the confusion when running `git config remote.<remote>.url`).