Re: [RFC PATCH] Write new giturl(7) manpage

[Jonathan Nieder <jrnieder@gmail.com>]

Ramkumar Ramachandra wrote:

>  I'm not entirely happy with it because the remote vcs setting doesn't
>  quite fit here. Plus, it seems like a dirty hack to me. The name doesn't do
>  justice: giturl exists to host Ilari's remote helper notes.

I suppose you are right.  I was imagining something like this:

 NAME
 ----
 giturl - Specifying remote repositories to Git

 SYNOPSIS
 --------
 <transport>://<rest-of-URL>, <host>:<path>, <transport>::<address>, <nickname>

 DESCRIPTION
 -----------
 To specify a remote repository using Git’s native protocol, one can
 use a traditional-looking URL.

 . git://host.xz[:port]/path/to/repo.git/
 . git://host.xz[:port]/~user/path/to/repo.git/

 For the SSH protocol, often used with 'git push', use the traditional syntax
 supported by 'scp'.  You can optionally specify which user to log in as.

 . [user@]host.xz:/path/to/repo.git/
 . [user@]host.xz:path/to/repo.git/

 That syntax does not allow specifying a port number. For this, a more
 verbose URL-style syntax is supported.

 . ssh://[user@]host.xz[:port]/path/to/repo.git/
 . ssh://[user@]host.xz[:port]/~[otheruser]/path/to/repo.git/

 Frequently-accessed repositories can be given a short alphanumeric
 nickname.  For example, the 'parent repository' for a new clone is
 automatically given the nickname 'origin'.  See linkgit:git-remote[1] for
 details.

 . nickname

 A path on the current machine can be used directly.  If a repository is
 specified in this way to the linkgit:git-clone[1] command, the clone will
 automatically use the --local option (which see).  The file:// syntax
 can be used to avoid this behavior.

 . /path/to/repo.git/
 . path/to/repo.git/

 Other protocols (most notably HTTP) can be specified with the
 schema://path syntax.  Support for the 'rsync', 'file', 'git', 'ssh',
 'git+ssh', and 'ssh+git' transports is built in.

 If Git was installed with HTTP support, then the 'http', 'https',
 'ftp', and 'ftps' schemata will be supported through helper programs.
 Third-party helpers may support other protocols, for example for
 interaction with other version control systems.  The syntax
 `transport::schema://path` can be used, or `transport://path` if
 the helper is already named after a URL schema.  The
 'git remote-<transport>' helper will be used to service the request,
 with `schema://path` passed as the associated URL.
 See also linkgit:git-remote-helpers[7].

 . http[s]://[user@]host.xz[:port]/[~user/]path/to/repo.git/
 . ftp[s]://[user@]host.xz[:port]/[~user/]path/to/repo.git/
 . file:///path/to/repo.git/
 . rsync://[user@]host.xz[:port]/path/to/repo.git/
 . http::http://[user@]host.xz[:port]/[~user/]path/to/repo.git/
 . etc

git-remote(1) would include the information currently in remote-urls.txt
about remote nicknames, plus:

 - how to specify a relevant vcs helper
 - the pushurl setting

Pages such as git-clone(1) that currently include urls.txt or
remote-urls.txt could have the remote section replaced with something
shorter:

 See giturls(7) for an explanation of the supported values for <repository>
 (git://host.xz/path, http://host.xz/path, and so on).

But this is more major surgery than the purpose of your patch calls
for.  If you find a simpler way to convey the relevant information in
the meantime, I can prepare a patch this weekend.

Thanks,
Jonathan