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

[Jonathan Nieder <jrnieder@gmail.com>]

Ramkumar Ramachandra wrote:

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

Nice.

> +Depending on the transport protocol, some of this information may be
> +absent.
> +
> +Git natively supports ssh, git, rsync, http, https, ftp, and ftps
> +protocols.

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.

Not a criticism of this patch, just something to think about.

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

Tiny nitpick: I would mention http before rsync.

[...]
>  - /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[]

What happened to this passage in git-clone.1?

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

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

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

Thanks.
Jonathan