[PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>

[PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>

[Ramkumar Ramachandra]

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>
---
 Added ftp, ftps and clarified a few things after Ilari's review of v2.

 Documentation/urls.txt |   64 +++++++++++++++++++++++++----------------------
 1 files changed, 34 insertions(+), 30 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 459a394..75743f2 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -1,44 +1,48 @@
 GIT URLS[[URLS]]
 ----------------

-One of the following notations can be used
-to name the remote repository:
-
-- 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
-
-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 expansion, as does the native git protocol, but
-only the former supports port specification. The following
-three are identical to the last three above, respectively:
-
-- {startsb}user@{endsb}host.xz:/path/to/repo.git/
-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
+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.
+
+In addition to SSH, which is the default transport protocol over the
+network, git natively supports git, rsync, http, https, ftp, and ftps
+protocols. The following syntaxes may be used with them. Only SSH and
+git protocols support username expansion.
+
+- 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
+- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git
+
+The SSH protocol also supports an alternative scp-like syntax:
+
 - {startsb}user@{endsb}host.xz:path/to/repo.git

-To sync with a local directory, you can use:
+For local respositories, also supported by git natively, the following
+syntaxes may be used:

-- /path/to/repo.git/
-- file:///path/to/repo.git/
+- /path/to/repo.git
+- file:///path/to/repo.git

 ifndef::git-clone[]
-They are mostly equivalent, except when cloning.  See
-linkgit:git-clone[1] for details.
+These two syntaxes are mostly equivalent, except when cloning, when
+the former implies --local option. See linkgit:git-clone[1] for
+details.
 endif::git-clone[]

-ifdef::git-clone[]
-They are 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
+may be used:
+
+- <transport>::<address>

+where <address> may be a path, a server and path, or an arbitrary
+URL-like string recognized by the specific remote helper being
+invoked. See linkgit:git-remote-helpers[1] for details.

 If there are a large number of similarly-named remote repositories and
 you want to use a different format for them (such that the URLs you
-- 
1.7.0.3

Re: [PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

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

Nice to finally see s-o-b ;-)

> diff --git a/Documentation/urls.txt b/Documentation/urls.txt
> index 459a394..75743f2 100644
> --- a/Documentation/urls.txt
> +++ b/Documentation/urls.txt
> @@ -1,44 +1,48 @@
>  GIT URLS[[URLS]]
>  ----------------
>
> -One of the following notations can be used
> -to name the remote repository:
> -
> -- 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
> -
> -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 expansion, as does the native git protocol, but
> -only the former supports port specification. The following
> -three are identical to the last three above, respectively:
> -
> -- {startsb}user@{endsb}host.xz:/path/to/repo.git/
> -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
> +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.
> +
> +In addition to SSH, which is the default transport protocol over the
> +network, git natively supports git, rsync, http, https, ftp, and ftps
> +protocols. The following syntaxes may be used with them. Only SSH and
> +git protocols support username expansion.

I don't see why we want to single out ssh:// being the default at all; in
fact I do not think it is the default in any way.  To "git clone" or "git
remote add" you always specify what URL to use.

> +- 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
> +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git

I am not sure if dropping the user expansion from the example and
replacing that with one and half line of prose makes it easier to read, or
harder.

> +The SSH protocol also supports an alternative scp-like syntax:
> +
>  - {startsb}user@{endsb}host.xz:path/to/repo.git

This probably is an improvement as it wasn't clear what transport the scp
syntax triggered, namely the ssh transport.

I earlier said that ssh is not the default and there is no reason to
single it out as such.  But there is a notable thing to mention about the
ssh transport: it traditionally has been the only authenticated transport,
if you don't count the webdav push-over-http.

> -To sync with a local directory, you can use:
> +For local respositories, also supported by git natively, the following
> +syntaxes may be used:
>
> -- /path/to/repo.git/
> -- file:///path/to/repo.git/
> +- /path/to/repo.git
> +- file:///path/to/repo.git

Why did you have to drop the trailing slashes from all the examples that
made them clear that we are talking about directories?

>  ifndef::git-clone[]
> -They are mostly equivalent, except when cloning.  See
> -linkgit:git-clone[1] for details.
> +These two syntaxes are mostly equivalent, except when cloning, when
> +the former implies --local option. See linkgit:git-clone[1] for
> +details.
>  endif::git-clone[]

Good.

> -ifdef::git-clone[]
> -They are 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
> +may be used:
> +
> +- <transport>::<address>
>
> +where <address> may be a path, a server and path, or an arbitrary
> +URL-like string recognized by the specific remote helper being
> +invoked. See linkgit:git-remote-helpers[1] for details.

I guess I should ask for "experts help" on this part, but to me this
paragraph looks good.

Thanks.

Re: [PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>

[Ramkumar Ramachandra]

Hi,

On Tue, Apr 6, 2010 at 3:52 AM, Junio C Hamano <gitster@pobox.com> wrote:
> I don't see why we want to single out ssh:// being the default at all; in
> fact I do not think it is the default in any way.  To "git clone" or "git
> remote add" you always specify what URL to use.

Junio: Thanks for this! I was wondering about the same thing, and
waiting for someone to comment. I've addressed this, and all your
other concerns in v4.

-- Ram