Rewrite the first part of the document to explicitly show differences
between the URLs that can be used with different transport
protocols. Mention <transport>::<address> format to explicitly invoke
a remote helper.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/urls.txt |   58 +++++++++++++++++++++++++++--------------------
 1 files changed, 33 insertions(+), 25 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 459a394..a473da6 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -1,44 +1,52 @@
 GIT URLS[[URLS]]
 ----------------
 
-One of the following notations can be used
-to name the remote repository:
+In general, URLs contain information about the transport protocol, the
+address of the remote server, and the path to the repository.
+Depending on the transport protocol, some of this information may be
+absent.
+
+Git natively supports ssh, git, rsync, http, https, ftp, and ftps
+protocols. The following syntaxes may be used with them:
 
-- rsync://host.xz/path/to/repo.git/
-- http://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- https://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/
 - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git
+- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
+- rsync://host.xz/path/to/repo.git/
+- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
+- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
 
-SSH is the default transport protocol over the network.  You can
-optionally specify which user to log-in as, and an alternate,
-scp-like syntax is also supported.  Both syntaxes support
-username ...
[ message continues ]

Hmm: if it is not built in to the git binary, is it right to call the
support native?  I don’t mean to say HTTP support is a second-class
citizen (with http-backend on the server side, it isn’t any more), but
it is possible that remote-http is not installed on a system.  Also, it
is a good example to introduce remote helpers with.


Tiny nitpick: I would mention http before rsync.



Except for the removal of the ifdef::git-clone[] section,

  Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.
Jonathan
--

[ message continues ]

By "native", I meant that no special remote helpers are necessary (it
would be with svn, for example). Does the technical detail of whether
the support is built into the main Git binary need to enter the
documentation?

Thanks for the review! :) I'll post a fixup patch soon.

-- Ram
--

[ message continues ]

Here's the fixup.

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index a473da6..8f442ba 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -11,8 +11,8 @@ protocols. The following syntaxes may be used with them:
 
 - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
 - git://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- rsync://host.xz/path/to/repo.git/
 - http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
+- rsync://host.xz/path/to/repo.git/
 - ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/
 
 An alternative scp-like syntax may also be used with the ssh protocol:
@@ -37,6 +37,11 @@ the former implies --local option. See linkgit:git-clone[1] for
 details.
 endif::git-clone[]
 
+ifdef::git-clone[]
+These two syntaxes are mostly equivalent, except the former implies
+--local option.
+endif::git-clone[]
+
 When git doesn't know how to handle a certain transport protocol, it
 attempts to use the 'remote-<transport>' remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
--

[ message continues ]

Thanks, both.  Will squash into the second patch.

Except that I'll further move rsync:// lower so that the curl family can
stay together, both in the list (that appeared in your "fixup") and in the
introductory text.
--

[ message continues ]

Heya,


With that I think the entire series can be:

Acked-by: Sverre Rabbelier <srabbelier@gmail.com>

-- 
Cheers,

Sverre Rabbelier
--

[ message continues ]

Thanks.  The end results look good to me, too.

--

[ message continues ]

Heya,


Hmm. Do we want to get this into 1.7.1? With how much debate this
series has had I don't see much added benefit from having it cooking
in next. I noticed another doc patch got merged into master in the
latest cooking, so I'm sort-of assuming there's special rules for
documentation, please correct me if that's nonsense.

-- 
Cheers,

Sverre Rabbelier
--

[ message continues ]

I don't think this is that _urgent_, but on the other hand I don't think
this is with heavy-enough impact that needs to be out of the coming
release either.  As long as there aren't any glaring factual errors or
formatting breakages, I think it is safe to merge it and get it over
with ;-).



--

[ message continues ]