Re: [PATCH/RFC] Documentation: reorganize documentation of URLs understood by git

[Jonathan Nieder <jrnieder@gmail.com>]

Junio C Hamano wrote:

> I am of two minds.  It is frustrating if "git clone" (or "git fetch", or
> "git remote") page didn't list any examples an intelligent person (or at
> least one who thinks he is intelligent enough) to mimic and instead
> referred him with "look there" indirections.

Makes sense.  So it should be self-contained for at least the common cases.
Something like:

GIT URLS

	One of the following notations can be used to name the remote repository:

	·   git://host.xz[:port]/path/to/repo.git/
	·   git://host.xz[:port]/~user/path/to/repo.git/
	·   [user@]host.xz:~user/path/to/repo.git/
	·   [user@]host.xz:/path/to/repo.git/
	·   [user@]host.xz:path/to/repo.git/
	·   ssh://host.xz[:port]/path/to/repo.git/
	·   ssh://host.xz[:port]/~user/path/to/repo.git/
	·   /path/to/local/repo.git/
	·   path/to/local/repo.git/
	·   file:///path/to/repo.git/
	·   svn::http://host.xz[:port]/path/to/repo/

	Schemas supported include git, ssh, file, rsync, and if HTTP support
	is installed, http, https, ftp, and ftps.

	Git can be taught to support additional schemas by installing a
	'git-remote-<schema>' helper to your $PATH.  See git-remote-helpers(7)
	if you want to write one.

	The url.*.insteadOf and url.*.pushInsteadOf configuration items
	affect URLs supplied to this command.  This can be useful if
	there are a large number of similarly-named remote repositories
	and you want to use a different format for them.  See gitconfig(5)
	for details on setting this up.

Unfortunately, that leaves out any explanation of which transport you would
want to use; in particular, it doesn’t say

 * Using local paths implies a request for "clone --local" unless the
   louder file:// syntax is used;

 * If you were thinking of using host.xz:port:/path/to/, use ssh://
   instead. [1]

 * The git protocol is very nice, but it does not support authentication.
   If that is a problem for you, use ssh instead for pushing.

   The rsync protocol support is bitrotting.

   http and ftp can be used as “smart” or “dumb” protocols; the former
   requires that the server administrator install a CGI script to serve
   requests efficiently; the latter is all some hosting services
   provide, and it has some caveats like requiring update-server-info.

Not sure where this should go.

Thanks for the food for thought,
Jonathan

[1] Aside: Is there any reason for git and scp not to learn to support
the two-colon syntax?  I would think directories named 1087: are a rather
rare beast, and they could still be accessed as "host.xz:./1087:/".