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

[PATCH 2/5] 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>
---
 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 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:
+An alternative scp-like syntax may also be used with the ssh protocol:
 
-- {startsb}user@{endsb}host.xz:/path/to/repo.git/
-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
-- {startsb}user@{endsb}host.xz:path/to/repo.git
+- {startsb}user@{endsb}host.xz:path/to/repo.git/
 
-To sync with a local directory, you can use:
+The ssh and git protocols additionally support ~username expansion:
+
+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
+- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/
+- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/
+
+For local respositories, also supported by git natively, the following
+syntaxes may be used:
 
 - /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.4

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

[Jonathan Nieder]

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

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

[Ramkumar Ramachandra]

Hi,

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

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

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

[Ramkumar Ramachandra]

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

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

[Junio C Hamano]

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.

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

[Sverre Rabbelier]

Heya,

On Sun, Apr 18, 2010 at 20:39, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

With that I think the entire series can be:

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

-- 
Cheers,

Sverre Rabbelier

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

[Junio C Hamano]

Sverre Rabbelier <srabbelier@gmail.com> writes:

> With that I think the entire series can be:
>
> Acked-by: Sverre Rabbelier <srabbelier@gmail.com>

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

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

[Sverre Rabbelier]

Heya,

On Sun, Apr 18, 2010 at 22:59, Junio C Hamano <gitster@pobox.com> wrote:
> Thanks.  The end results look good to me, too.

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

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

[Junio C Hamano]

Sverre Rabbelier <srabbelier@gmail.com> writes:

> On Sun, Apr 18, 2010 at 22:59, Junio C Hamano <gitster@pobox.com> wrote:
>> Thanks. The end results look good to me, too.
>
> 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 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 ;-).