{"thread":{"id":"23336","subject":"[PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>","startedAt":"2010-04-05T13:56:58Z","lastAt":"2010-04-06T08:44:03Z","messageCount":3,"participants":["Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"138592","messageId":"n2rf3271551004050656vdd7d242dpeebacb25d4082f75@mail.gmail.com","threadId":"23336","inReplyTo":null,"subject":"[PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-04-05T13:56:58Z","receivedAt":"2010-04-05T13:56:58Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Rewrite the first part of the document to explicitly show differences\nbetween the URLs that can be used with different transport\nprotocols. Mention <transport>::<address> format to explicitly invoke\na remote helper.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n---\n Added ftp, ftps and clarified a few things after Ilari's review of v2.\n\n Documentation/urls.txt |   64 +++++++++++++++++++++++++----------------------\n 1 files changed, 34 insertions(+), 30 deletions(-)\n\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex 459a394..75743f2 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -1,44 +1,48 @@\n GIT URLS[[URLS]]\n ----------------\n\n-One of the following notations can be used\n-to name the remote repository:\n-\n-- rsync://host.xz/path/to/repo.git/\n-- http://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- https://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git\n-\n-SSH is the default transport protocol over the network.  You can\n-optionally specify which user to log-in as, and an alternate,\n-scp-like syntax is also supported.  Both syntaxes support\n-username expansion, as does the native git protocol, but\n-only the former supports port specification. The following\n-three are identical to the last three above, respectively:\n-\n-- {startsb}user@{endsb}host.xz:/path/to/repo.git/\n-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/\n+In general, URLs contain information about the transport protocol, the\n+address of the remote server, and the path to the repository.\n+Depending on the transport protocol, some of this information may be\n+absent.\n+\n+In addition to SSH, which is the default transport protocol over the\n+network, git natively supports git, rsync, http, https, ftp, and ftps\n+protocols. The following syntaxes may be used with them. Only SSH and\n+git protocols support username expansion.\n+\n+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git\n+- git://host.xz{startsb}:port{endsb}/path/to/repo.git\n+- rsync://host.xz/path/to/repo.git\n+- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git\n+- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git\n+\n+The SSH protocol also supports an alternative scp-like syntax:\n+\n - {startsb}user@{endsb}host.xz:path/to/repo.git\n\n-To sync with a local directory, you can use:\n+For local respositories, also supported by git natively, the following\n+syntaxes may be used:\n\n-- /path/to/repo.git/\n-- file:///path/to/repo.git/\n+- /path/to/repo.git\n+- file:///path/to/repo.git\n\n ifndef::git-clone[]\n-They are mostly equivalent, except when cloning.  See\n-linkgit:git-clone[1] for details.\n+These two syntaxes are mostly equivalent, except when cloning, when\n+the former implies --local option. See linkgit:git-clone[1] for\n+details.\n endif::git-clone[]\n\n-ifdef::git-clone[]\n-They are equivalent, except the former implies --local option.\n-endif::git-clone[]\n+When git doesn't know how to handle a certain transport protocol, it\n+attempts to use the 'remote-<transport>' remote helper, if one\n+exists. To explicitly request a remote helper, the following syntax\n+may be used:\n+\n+- <transport>::<address>\n\n+where <address> may be a path, a server and path, or an arbitrary\n+URL-like string recognized by the specific remote helper being\n+invoked. See linkgit:git-remote-helpers[1] for details.\n\n If there are a large number of similarly-named remote repositories and\n you want to use a different format for them (such that the URLs you\n-- \n1.7.0.3\n"},{"id":"138679","messageId":"7vhbnpmteu.fsf@alter.siamese.dyndns.org","threadId":"23336","inReplyTo":"n2rf3271551004050656vdd7d242dpeebacb25d4082f75@mail.gmail.com","subject":"Re: [PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-05T22:22:17Z","receivedAt":"2010-04-05T22:22:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra <artagnon@gmail.com> writes:\n\n> Rewrite the first part of the document to explicitly show differences\n> between the URLs that can be used with different transport\n> protocols. Mention <transport>::<address> format to explicitly invoke\n> a remote helper.\n>\n> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n> ---\n\nNice to finally see s-o-b ;-)\n\n> diff --git a/Documentation/urls.txt b/Documentation/urls.txt\n> index 459a394..75743f2 100644\n> --- a/Documentation/urls.txt\n> +++ b/Documentation/urls.txt\n> @@ -1,44 +1,48 @@\n>  GIT URLS[[URLS]]\n>  ----------------\n>\n> -One of the following notations can be used\n> -to name the remote repository:\n> -\n> -- rsync://host.xz/path/to/repo.git/\n> -- http://host.xz{startsb}:port{endsb}/path/to/repo.git/\n> -- https://host.xz{startsb}:port{endsb}/path/to/repo.git/\n> -- git://host.xz{startsb}:port{endsb}/path/to/repo.git/\n> -- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/\n> -- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/\n> -- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/\n> -- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/\n> -- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git\n> -\n> -SSH is the default transport protocol over the network.  You can\n> -optionally specify which user to log-in as, and an alternate,\n> -scp-like syntax is also supported.  Both syntaxes support\n> -username expansion, as does the native git protocol, but\n> -only the former supports port specification. The following\n> -three are identical to the last three above, respectively:\n> -\n> -- {startsb}user@{endsb}host.xz:/path/to/repo.git/\n> -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/\n> +In general, URLs contain information about the transport protocol, the\n> +address of the remote server, and the path to the repository.\n> +Depending on the transport protocol, some of this information may be\n> +absent.\n> +\n> +In addition to SSH, which is the default transport protocol over the\n> +network, git natively supports git, rsync, http, https, ftp, and ftps\n> +protocols. The following syntaxes may be used with them. Only SSH and\n> +git protocols support username expansion.\n\nI don't see why we want to single out ssh:// being the default at all; in\nfact I do not think it is the default in any way.  To \"git clone\" or \"git\nremote add\" you always specify what URL to use.\n\n> +- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git\n> +- git://host.xz{startsb}:port{endsb}/path/to/repo.git\n> +- rsync://host.xz/path/to/repo.git\n> +- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git\n> +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git\n\nI am not sure if dropping the user expansion from the example and\nreplacing that with one and half line of prose makes it easier to read, or\nharder.\n\n> +The SSH protocol also supports an alternative scp-like syntax:\n> +\n>  - {startsb}user@{endsb}host.xz:path/to/repo.git\n\nThis probably is an improvement as it wasn't clear what transport the scp\nsyntax triggered, namely the ssh transport.\n\nI earlier said that ssh is not the default and there is no reason to\nsingle it out as such.  But there is a notable thing to mention about the\nssh transport: it traditionally has been the only authenticated transport,\nif you don't count the webdav push-over-http.\n\n> -To sync with a local directory, you can use:\n> +For local respositories, also supported by git natively, the following\n> +syntaxes may be used:\n>\n> -- /path/to/repo.git/\n> -- file:///path/to/repo.git/\n> +- /path/to/repo.git\n> +- file:///path/to/repo.git\n\nWhy did you have to drop the trailing slashes from all the examples that\nmade them clear that we are talking about directories?\n\n>  ifndef::git-clone[]\n> -They are mostly equivalent, except when cloning.  See\n> -linkgit:git-clone[1] for details.\n> +These two syntaxes are mostly equivalent, except when cloning, when\n> +the former implies --local option. See linkgit:git-clone[1] for\n> +details.\n>  endif::git-clone[]\n\nGood.\n\n> -ifdef::git-clone[]\n> -They are equivalent, except the former implies --local option.\n> -endif::git-clone[]\n> +When git doesn't know how to handle a certain transport protocol, it\n> +attempts to use the 'remote-<transport>' remote helper, if one\n> +exists. To explicitly request a remote helper, the following syntax\n> +may be used:\n> +\n> +- <transport>::<address>\n>\n> +where <address> may be a path, a server and path, or an arbitrary\n> +URL-like string recognized by the specific remote helper being\n> +invoked. See linkgit:git-remote-helpers[1] for details.\n\nI guess I should ask for \"experts help\" on this part, but to me this\nparagraph looks good.\n\nThanks.\n"},{"id":"138726","messageId":"h2yf3271551004060144uc7ae9662s2148c11f697a2dd0@mail.gmail.com","threadId":"23336","inReplyTo":"7vhbnpmteu.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v3] Documentation/urls: Rewrite to accomodate <transport>::<address>","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-04-06T08:44:03Z","receivedAt":"2010-04-06T08:44:03Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nOn Tue, Apr 6, 2010 at 3:52 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> I don't see why we want to single out ssh:// being the default at all; in\n> fact I do not think it is the default in any way.  To \"git clone\" or \"git\n> remote add\" you always specify what URL to use.\n\nJunio: Thanks for this! I was wondering about the same thing, and\nwaiting for someone to comment. I've addressed this, and all your\nother concerns in v4.\n\n-- Ram\n"}]}