# [PATCH v3] Documentation/urls: Rewrite to accomodate ::
3 messages from 2010-04-05 to 2010-04-06. Participants: Ramkumar Ramachandra, Junio C Hamano. Thread: https://gitlist.dev/t/23336 ## Ramkumar Ramachandra, 2010-04-05 13:56 Subject: [PATCH v3] Documentation/urls: Rewrite to accomodate ::
Message-ID: URL: https://gitlist.dev/e/n2rf3271551004050656vdd7d242dpeebacb25d4082f75%40mail.gmail.com ``` 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 --- Added ftp, ftps and clarified a few things after Ilari's review of v2. Documentation/urls.txt | 64 +++++++++++++++++++++++++---------------------- 1 files changed, 34 insertions(+), 30 deletions(-) diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 459a394..75743f2 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -1,44 +1,48 @@ GIT URLS[[URLS]] ---------------- -One of the following notations can be used -to name the remote repository: - -- 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 - -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: - -- {startsb}user@{endsb}host.xz:/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ +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. + +In addition to SSH, which is the default transport protocol over the +network, git natively supports git, rsync, http, https, ftp, and ftps +protocols. The following syntaxes may be used with them. Only SSH and +git protocols support username expansion. + +- 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 +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git + +The SSH protocol also supports an alternative scp-like syntax: + - {startsb}user@{endsb}host.xz:path/to/repo.git -To sync with a local directory, you can use: +For local respositories, also supported by git natively, the following +syntaxes may be used: -- /path/to/repo.git/ -- file:///path/to/repo.git/ +- /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.3 ``` ## Junio C Hamano, 2010-04-05 22:22 Subject: Re: [PATCH v3] Documentation/urls: Rewrite to accomodate ::
Message-ID: <7vhbnpmteu.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vhbnpmteu.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Ramkumar Ramachandra writes: > 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 > --- Nice to finally see s-o-b ;-) > diff --git a/Documentation/urls.txt b/Documentation/urls.txt > index 459a394..75743f2 100644 > --- a/Documentation/urls.txt > +++ b/Documentation/urls.txt > @@ -1,44 +1,48 @@ > GIT URLS[[URLS]] > ---------------- > > -One of the following notations can be used > -to name the remote repository: > - > -- 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 > - > -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: > - > -- {startsb}user@{endsb}host.xz:/path/to/repo.git/ > -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ > +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. > + > +In addition to SSH, which is the default transport protocol over the > +network, git natively supports git, rsync, http, https, ftp, and ftps > +protocols. The following syntaxes may be used with them. Only SSH and > +git protocols support username expansion. I don't see why we want to single out ssh:// being the default at all; in fact I do not think it is the default in any way. To "git clone" or "git remote add" you always specify what URL to use. > +- 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 > +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git I am not sure if dropping the user expansion from the example and replacing that with one and half line of prose makes it easier to read, or harder. > +The SSH protocol also supports an alternative scp-like syntax: > + > - {startsb}user@{endsb}host.xz:path/to/repo.git This probably is an improvement as it wasn't clear what transport the scp syntax triggered, namely the ssh transport. I earlier said that ssh is not the default and there is no reason to single it out as such. But there is a notable thing to mention about the ssh transport: it traditionally has been the only authenticated transport, if you don't count the webdav push-over-http. > -To sync with a local directory, you can use: > +For local respositories, also supported by git natively, the following > +syntaxes may be used: > > -- /path/to/repo.git/ > -- file:///path/to/repo.git/ > +- /path/to/repo.git > +- file:///path/to/repo.git Why did you have to drop the trailing slashes from all the examples that made them clear that we are talking about directories? > 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[] Good. > -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. I guess I should ask for "experts help" on this part, but to me this paragraph looks good. Thanks. ``` ## Ramkumar Ramachandra, 2010-04-06 08:44 Subject: Re: [PATCH v3] Documentation/urls: Rewrite to accomodate ::
Message-ID: URL: https://gitlist.dev/e/h2yf3271551004060144uc7ae9662s2148c11f697a2dd0%40mail.gmail.com In-Reply-To: <7vhbnpmteu.fsf@alter.siamese.dyndns.org> ``` Hi, On Tue, Apr 6, 2010 at 3:52 AM, Junio C Hamano wrote: > I don't see why we want to single out ssh:// being the default at all; in > fact I do not think it is the default in any way.  To "git clone" or "git > remote add" you always specify what URL to use. Junio: Thanks for this! I was wondering about the same thing, and waiting for someone to comment. I've addressed this, and all your other concerns in v4. -- Ram ```