Documentation/urls: Rewrite to accomodate <transport>::<address>
PATCH 2/5 Documentation/urls: Rewrite to accomodate <transport>::<address>
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.
--- Documentation/urls.txt | 58 +++++++++++++++++++++++++++-------------------- 1 files changed, 33 insertions(+), 25 deletions(-)
Documentation/urls.txt +33 -25
@@ -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
Signature · 1 line
1.7.0.4
Documentation/urls.txt line 5
Quoted 10 lines · Ramkumar Ramachandra
Documentation/urls.txt +2
-2@@ -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.
Documentation/urls.txt
Quoted 5 lines
Documentation/urls.txt +5
-0+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.
Quoted 11 lines
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
Quoted 4 lines
+- 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.
[...]
Quoted 4 lines
- /path/to/repo.git/
- file:///path/to/repo.git/ifndef::git-clone[]
Documentation/urls.txt line 40
Quoted 10 lines
Documentation/urls.txt +3
-5-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?
Documentation/urls.txt line 49
Quoted 10 lines
Documentation/urls.txt +9
-0+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,
Thanks.
Jonathan
Here's the fixup.
Documentation/urls.txt +6 -1
@@ -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
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.
Sverre Rabbelier
Acked-byHeya,
Quoted 3 lines · Junio C Hamano
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:
Signature · 3 lines
Cheers, Sverre Rabbelier
Quoted 3 lines · Sverre Rabbelier
With that I think the entire series can be:
Acked-by Sverre Rabbelier <[email protected]>
Thanks. The end results look good to me, too.
Heya,
Quoted 1 line · Junio C Hamano
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.
Signature · 3 lines
Cheers, Sverre Rabbelier
Quoted 6 lines · Sverre Rabbelier
Quoted 1 line · Junio C Hamano
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 ;-).
Hi,
Quoted 5 lines
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