[PATCH] Documentation: clarify multiple pushurls vs urls

From: Calvin Wan <calvinwan@google.com>
Date: Feb 6, 2023, 19:55 UTC
Message-ID: <20230206195503.3113048-1-calvinwan@google.com>

While it is possible to define multiple `url` fields in a remote to push to multiple remotes at once, it is preferable to achieve this by defining multiple `pushurl` fields.

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).

Add documentation to clarify how fetch interacts with multiple urls and the recommended method to push to multiple remotes.

Signed-off-by: Calvin Wan <calvinwan@google.com>
---
 Documentation/urls-remotes.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt
index 86d0008f94..61aaded645 100644
--- a/Documentation/urls-remotes.txt
+++ b/Documentation/urls-remotes.txt
@@ -33,7 +33,10 @@ config file would appear like this:
 ------------
 
 The `<pushurl>` is used for pushes only. It is optional and defaults
-to `<URL>`.
+to `<URL>`. Additional pushurls can be defined to push to multiple
+remotes. While multiple URLs can be defined to achieve the same
+outcome, this is not recommended since fetch only uses the first
+defined URL.
 
 Named file in `$GIT_DIR/remotes`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-- 
2.39.1.519.gcb327c4b5f-goog