# [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
9 messages from 2010-04-18 to 2010-04-18. Participants: Ramkumar Ramachandra, Jonathan Nieder, Junio C Hamano, Sverre Rabbelier. Thread: https://gitlist.dev/t/23507 ## Ramkumar Ramachandra, 2010-04-18 00:54 Subject: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <1271552047-sup-9523@kytes> URL: https://gitlist.dev/e/1271552047-sup-9523%40kytes ``` Rewrite the first part of the document to explicitly show differences between the URLs that can be used with different transport protocols. Mention ::
format to explicitly invoke a remote helper. Signed-off-by: Ramkumar Ramachandra --- 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-' remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used: + +- ::
+where
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 ``` ## Jonathan Nieder, 2010-04-18 02:59 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <20100418025940.GA2249@progeny.tock> URL: https://gitlist.dev/e/20100418025940.GA2249%40progeny.tock In-Reply-To: <1271552047-sup-9523@kytes> ``` 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-' remote helper, if one > +exists. To explicitly request a remote helper, the following syntax > +may be used: > + > +- ::
> > +where
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 Thanks. Jonathan ``` ## Ramkumar Ramachandra, 2010-04-18 03:59 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: URL: https://gitlist.dev/e/i2gf3271551004172059sb3abbafcz2feb9eed14e596aa%40mail.gmail.com In-Reply-To: <20100418025940.GA2249@progeny.tock> ``` 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 ``` ## Ramkumar Ramachandra, 2010-04-18 05:03 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <1271566767-sup-7167@kytes> URL: https://gitlist.dev/e/1271566767-sup-7167%40kytes In-Reply-To: <20100418025940.GA2249@progeny.tock> ``` 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-' remote helper, if one exists. To explicitly request a remote helper, the following syntax ``` ## Junio C Hamano, 2010-04-18 18:39 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <7vk4s4wqo5.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vk4s4wqo5.fsf%40alter.siamese.dyndns.org In-Reply-To: <1271566767-sup-7167@kytes> ``` 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, 2010-04-18 18:44 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: URL: https://gitlist.dev/e/m2pfabb9a1e1004181144x10f6a0f1x2e55bc025aba781b%40mail.gmail.com In-Reply-To: <7vk4s4wqo5.fsf@alter.siamese.dyndns.org> ``` Heya, On Sun, Apr 18, 2010 at 20:39, Junio C Hamano 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 -- Cheers, Sverre Rabbelier ``` ## Junio C Hamano, 2010-04-18 20:59 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <7vzl10v5mo.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vzl10v5mo.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Sverre Rabbelier writes: > With that I think the entire series can be: > > Acked-by: Sverre Rabbelier Thanks. The end results look good to me, too. ``` ## Sverre Rabbelier, 2010-04-18 21:10 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: URL: https://gitlist.dev/e/w2gfabb9a1e1004181410ia09cc99o1ba807b53744f3ee%40mail.gmail.com In-Reply-To: <7vzl10v5mo.fsf@alter.siamese.dyndns.org> ``` Heya, On Sun, Apr 18, 2010 at 22:59, Junio C Hamano 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 ``` ## Junio C Hamano, 2010-04-18 21:56 Subject: Re: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Message-ID: <7vvdbov2zc.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vvdbov2zc.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Sverre Rabbelier writes: > On Sun, Apr 18, 2010 at 22:59, Junio C Hamano 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 ;-). ```