[RFC PATCH] Write new giturl(7) manpage

[RFC PATCH] Write new giturl(7) manpage

[Ramkumar Ramachandra]

Write a new manpage for documenting how different URLs are handled by
remote helpers.
---
 It severely lacks polish, but I thought I'd send in an early draft requesting
 comments. Also, I've made it more cryptic than Jonathan's revision and
 included more references.

 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. How can it be
 expanded to be more general?

 Why doesn't urls.txt document <transport>::<address> syntax? Should I
 fix this?

 Documentation/giturl.txt |   85 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 85 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/giturl.txt

diff --git a/Documentation/giturl.txt b/Documentation/giturl.txt
new file mode 100644
index 0000000..9ffd17c
--- /dev/null
+++ b/Documentation/giturl.txt
@@ -0,0 +1,85 @@
+giturl(7)
+=========
+
+NAME
+----
+giturl - An overview on how different URLs are handled by Git
+
+SYNOPSIS
+--------
+git *
+
+DESCRIPTION
+-----------
+
+URLs are used in two places. Directly on the command line by the end
+user, and in remotes configuration (see REMOTES section below). They
+all have the general structure described in the URLS section
+below. While most of them are handled by Git internally, some of them
+are handled by remote helper programs. When a URL thatgit doesn't
+handle internally is encountered either on the command line or in the
+remotes configuration, a remote helper that does will be used
+transparently by the transport machinery of git (i.e., by commands
+such as git ls-remote, git send-pack, and git archive --remote). The
+following is a list of such URLs:
+
+<transport>::<address>
+~~~~~~~~~~~~~~~~~~~~~~
+A URL of the form `<transport>::<rest-of-URL>` is used on the command
+line by the end-user.
+
+The 'git remote-<transport>' helper will be invoked with the full
+<transport>::<rest-of-URL> URL as the first argument and <address> as
+the second argument.
+
+<name> with vcs set
+~~~~~~~~~~~~~~~~~~~
+`remote.<name>.vcs` is set to `<transport>` (see
+git-config[1]). `remote.<name>.url` is optionally set to a URL of the
+form `<transport>://<rest-of-URL>`.
+
+If the `remote.<name>.url` is set, the helper will be invoked with
+`<name>` as the first argument and `<rest-of-URL>` as the second
+argument.  Otherwise, the helper will be invoked with a single
+argument, `<name>`.
+
+<nickname> with vcs unset
+~~~~~~~~~~~~~~~~~~~~~~~~~
+`remote.<name>.url` is set to a URL of the form
+`<transport>://<rest-of-URL>`.
+
+The ‘git remote-<transport>’ helper will be invoked with the
+`<name>` as first argument and `<transport>://<rest-of-URL>` as the
+second argument.
+
+Exception: the built-in 'rsync', 'file', 'git', 'ssh', 'git+ssh', and
+'ssh+git' transports are not handled using remote helpers.
+
+<transport>://<rest-of-URL>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A URL of the form `<transport>://<rest-of-URL>` is used on the command
+line by the end-user.
+
+If 'transport' is not one of the built-in protocols listed above, the
+'git remote-<transport>' helper will be invoked with two arguments,
+both equal to the full `<transport>://<rest-of-URL>` URL.
+
+include::urls-remotes.txt[]
+
+SEE ALSO
+--------
+linkgit:git-remote-helpers[1]
+linkgit:git-remote[1]
+linkgit:git-config[1]
+
+Author
+------
+Written by Ramkumar Ramachandra
+
+Documentation
+-------------
+Documentation by Ilari Liusvaara and the git-list <git@vger.kernel.org>
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
1.7.0.3

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

[Daniel Barkalow]

On Mon, 29 Mar 2010, Ramkumar Ramachandra wrote:

> Write a new manpage for documenting how different URLs are handled by
> remote helpers.
> ---
>  It severely lacks polish, but I thought I'd send in an early draft requesting
>  comments. Also, I've made it more cryptic than Jonathan's revision and
>  included more references.
> 
>  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. How can it be
>  expanded to be more general?
> 
>  Why doesn't urls.txt document <transport>::<address> syntax? Should I
>  fix this?

One useful way of answering questions like this is to find the commits 
that added the <transport>::<address> syntax (probably easiest with git 
blame), and at the commits that touched urls.txt (probably with git log), 
and see if the reading the messages makes it obvious. I'd guess (without 
actually looking myself) that it was just overlooked.

	-Daniel
*This .sig left intentionally blank*

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

[Ilari Liusvaara]

On Mon, Mar 29, 2010 at 11:48:18AM -0400, Daniel Barkalow wrote:
> On Mon, 29 Mar 2010, Ramkumar Ramachandra wrote:
> 
> >  Why doesn't urls.txt document <transport>::<address> syntax? Should I
> >  fix this?
> 
> One useful way of answering questions like this is to find the commits 
> that added the <transport>::<address> syntax (probably easiest with git 
> blame), and at the commits that touched urls.txt (probably with git log), 
> and see if the reading the messages makes it obvious. I'd guess (without 
> actually looking myself) that it was just overlooked.

I think the following commit added that syntax:

commit 87422439d100f020cadb63b5da8495e5fbfb8fa3
Author: Johannes Schindelin <johannes.schindelin@gmx.de>
Date:   Wed Nov 18 02:42:26 2009 +0100

    Allow specifying the remote helper in the url
    
    The common case for remote helpers will be to import some repository
    which can be specified by a single URL.  Support this use case by
    allowing users to say:
    
        git clone hg::https://soc.googlecode.com/hg/ soc
    
    Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
    Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

AFAICT, urls.txt hasn't been touched since this commit.

-Ilari

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

[Sverre Rabbelier]

Heya,

On Mon, Mar 29, 2010 at 09:55, Ilari Liusvaara
<ilari.liusvaara@elisanet.fi> wrote:
> AFAICT, urls.txt hasn't been touched since this commit.

Yup, my bad for not updating urls.txt (mainly because I didn't know it
existed :P). I think Ramkumar's patch [0] to fix that is a step in the
right direction :).

[] http://mid.gmane.org/f3271551003290810u4edbbbd0x2432bc7411333800@mail.gmail.com

-- 
Cheers,

Sverre Rabbelier

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

[Ramkumar Ramachandra]

> One useful way of answering questions like this is to find the commits
> that added the <transport>::<address> syntax (probably easiest with git
> blame), and at the commits that touched urls.txt (probably with git log),
> and see if the reading the messages makes it obvious. I'd guess (without
> actually looking myself) that it was just overlooked.

Got it.

> Yup, my bad for not updating urls.txt (mainly because I didn't know it
> existed :P). I think Ramkumar's patch [0] to fix that is a step in the
> right direction :).

Thanks :) I've prepared a second revision, which is a complete rewrite
of urls. In the meantime, could you review this patch?

-- Ram

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

[Jonathan Nieder]

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

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

[Sverre Rabbelier]

Heya,

On Mon, Mar 29, 2010 at 13:18, Jonathan Nieder <jrnieder@gmail.com> wrote:
> I suppose you are right.  I was imagining something like this:

Wow, nice. I like it. Well written :).

-- 
Cheers,

Sverre Rabbelier

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

[Ramkumar Ramachandra]

On Tue, Mar 30, 2010 at 12:48 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> I suppose you are right.  I was imagining something like this:

Your patch looks awesome. It looks like I didn't have the right idea.
I'll drop this patch- you can write one.

-- Ram

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

[Ramkumar Ramachandra]

> On Tue, Mar 30, 2010 at 12:48 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> I suppose you are right.  I was imagining something like this:

My only concern is that it shouldn't duplicate too much of the
information in urls.txt. Also, it'll be nice if it's consistent with
the new urls.txt after my patch [1].

-- Ram

[1] http://thread.gmane.org/gmane.comp.version-control.git/143499

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

[Jonathan Nieder]

Currently, the git documentation includes several copies of the same
explanation of the format of git URLs and git remotes.  On one hand,
this makes some manual pages (e.g., git-fetch(1) and git-pull(1))
appear longer than they really ought to be, and on the other hand, it
makes it difficult to find a single appropriate page to link to online
to answer questions about these topics.

So add a new giturl(7) page describing the format of URLs understood
by git, move the explanation of remote nicknames to git-remote(1), and
replace urls.txt and urls-remote.txt with pointers to these pages.

While at it, add some explanation of the new mechanisms for accessing
a repository using a third-party tool.  This is meant to be more
useful for users learning to use git than for tool authors, but with
some tweaks it should be useful for the latter, too.

This documentation was improved with feedback from Ilari, Ram,
Sverre, and Daniel.  It is still very rough.

Cc: Daniel Barkalow <barkalow@iabervon.org>
Cc: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
Cc: Sverre Rabbelier <srabbelier@gmail.com>
Cc: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Hi,

Here is the suggested page explaining URLs recognized by git I mentioned
before.  It was harder to find time this weekend for this then I thought
--- sorry.

About half of the patch is taken up by moving text from urls-remotes.txt
to git-remote.txt.  If anyone has ideas for making this more convenient
to read, I’m all ears.

The main idea driving this for me is that the reference manual should be
something that a sufficiently interested person could read from cover to
cover.  As it is, there’s too much repetition for that.  I also would
like each topic to be documented clearly and thoroughly in an easy-to-find
place; it seems unlikely this achieves those first two criteria, but at
least this way I think the information about Git URLs should be easy to
find.

Suggestions on language and organization are especially welcome.  This
is just to get the ball rolling; hopefully someone more capable of
writing clear documentation can help meld the page into something
people can use.

Patch is against master.

Thoughts?
Jonathan

 Documentation/Makefile         |    2 +-
 Documentation/git-remote.txt   |  109 ++++++++++++++++++++++++++++++++++++++-
 Documentation/giturl.txt       |  105 ++++++++++++++++++++++++++++++++++++++
 Documentation/urls-remotes.txt |   95 +----------------------------------
 Documentation/urls.txt         |   86 ++-----------------------------
 5 files changed, 218 insertions(+), 179 deletions(-)
 create mode 100644 Documentation/giturl.txt
 rewrite Documentation/urls-remotes.txt (99%)
 rewrite Documentation/urls.txt (98%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8a8a395..97c41ed 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,7 +4,7 @@ MAN1_TXT= \
 	gitk.txt git.txt
 MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
 	gitrepository-layout.txt
-MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
+MAN7_TXT=gitcli.txt giturl.txt gittutorial.txt gittutorial-2.txt \
 	gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
 	gitdiffcore.txt gitworkflows.txt
 
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 3fc599c..352e762 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -146,13 +146,115 @@ be updated.  (See linkgit:git-config[1]).
 +
 With `--prune` option, prune all the remotes that are updated.
 
+REMOTES[[REMOTES]]
+------------------
+
+The name of one of the following can be used by the various git
+commands instead of a URL as `<repository>` argument:
+
+* a remote in the git configuration file: `$GIT_DIR/config`,
+* a file in the `$GIT_DIR/remotes` directory, or
+* a file in the `$GIT_DIR/branches` directory.
+
+All of these also allow you to omit the refspec from the command line
+because they each contain a refspec which git will use by default.
+
+Named remote in configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can choose to provide the name of a remote which you had previously
+configured using 'git remote', linkgit:git-config[1]
+or by a manual edit to the `$GIT_DIR/config` file.  The URL of
+this remote will be used to access the repository.  The refspec
+of this remote will be used by default when you do
+not provide a refspec on the command line.  The section in the
+config file would appear like this:
+
+------------
+	[remote "<name>"]
+		vcs = <transport>
+		url = <url>
+		pushurl = <pushurl>
+		push = <refspec>
+		fetch = <refspec>
+------------
+
+If no 'vcs' item is present, the 'url' is mandatory and identifies
+the repository.
+Any URL understood by git will work (see linkgit:giturl[7])
+except for the name of a remote.
+
+The `<pushurl>` is used for pushes only. It is optional and defaults
+to `<url>`.
+
+A 'vcs' item can be used to request that a particular
+'git remote-`<transport>`' helper (see linkgit:git-remote-helpers[7])
+be used to communicate with the remote repository.
+This facility is intended for interoperability with version control
+systems that require more configuration than a URL to identify a repository.
+The 'url' variable in such a section is optional and its interpretation
+depends on the helper.
+
+Named file in `$GIT_DIR/remotes`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can choose to provide the name of a
+file in `$GIT_DIR/remotes`.  The URL
+in this file will be used to access the repository.  The refspec
+in this file will be used as default when you do not
+provide a refspec on the command line.  This file should have the
+following format:
+
+------------
+	URL: one of the above URL format
+	Push: <refspec>
+	Pull: <refspec>
+
+------------
+
+`Push:` lines are used by 'git push' and
+`Pull:` lines are used by 'git pull' and 'git fetch'.
+Multiple `Push:` and `Pull:` lines may
+be specified for additional branch mappings.
+
+Named file in `$GIT_DIR/branches`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can choose to provide the name of a
+file in `$GIT_DIR/branches`.
+The URL in this file will be used to access the repository.
+This file should have the following format:
+
+
+------------
+	<url>#<head>
+------------
+
+`<url>` is required; `#<head>` is optional.
+
+Depending on the operation, git will use one of the following
+refspecs, if you don't provide one on the command line.
+`<branch>` is the name of this file in `$GIT_DIR/branches` and
+`<head>` defaults to `master`.
+
+git fetch uses:
+
+------------
+	refs/heads/<head>:refs/heads/<branch>
+------------
+
+git push uses:
+
+------------
+	HEAD:refs/heads/<head>
+------------
 
 DISCUSSION
 ----------
 
-The remote configuration is achieved using the `remote.origin.url` and
-`remote.origin.fetch` configuration variables.  (See
-linkgit:git-config[1]).
+The remote configuration managed by 'git remote' is achieved using the
+`remote.origin.url` and `remote.origin.fetch` configuration variables.
+(See linkgit:git-config[1]).
 
 Examples
 --------
@@ -194,6 +296,7 @@ SEE ALSO
 linkgit:git-fetch[1]
 linkgit:git-branch[1]
 linkgit:git-config[1]
+linkgit:giturl[7]
 
 Author
 ------
diff --git a/Documentation/giturl.txt b/Documentation/giturl.txt
new file mode 100644
index 0000000..dfe4551
--- /dev/null
+++ b/Documentation/giturl.txt
@@ -0,0 +1,105 @@
+giturl(7)
+=========
+
+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{startsb}:port{endsb}/path/to/repo.git/
+- git://host.xz{startsb}:port{endsb}/~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.
+
+- {startsb}user@{endsb}host.xz:/path/to/repo.git/
+- {startsb}user@{endsb}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://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}otheruser{endsb}/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 linkgit:git-remote-helpers[7] for details.
+
+- http{startsb}s{endsb}://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/
+- ftp{startsb}s{endsb}://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/
+- file:///path/to/repo.git/
+- rsync://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
+- http::http://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/
+
+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
+use will be rewritten into URLs that work), you can create a
+configuration section of the form:
+
+------------
+	[url "<actual url base>"]
+		insteadOf = <other url base>
+------------
+
+For example, with this:
+
+------------
+	[url "git://git.host.xz/"]
+		insteadOf = host.xz:/path/to/
+		insteadOf = work:
+------------
+
+a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
+rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".
+
+If you want to rewrite URLs for push only, you can create a
+configuration section of the form:
+
+------------
+	[url "<actual url base>"]
+		pushInsteadOf = <other url base>
+------------
+
+For example, with this:
+
+------------
+	[url "ssh://example.org/"]
+		pushInsteadOf = git://example.org/
+------------
+
+a URL like "git://example.org/path/to/repo.git" will be rewritten to
+"ssh://example.org/path/to/repo.git" for pushes, but pulls will still
+use the original URL.
diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt
dissimilarity index 99%
index 00f7e79..7ba74f0 100644
--- a/Documentation/urls-remotes.txt
+++ b/Documentation/urls-remotes.txt
@@ -1,94 +1 @@
-include::urls.txt[]
-
-REMOTES[[REMOTES]]
-------------------
-
-The name of one of the following can be used instead
-of a URL as `<repository>` argument:
-
-* a remote in the git configuration file: `$GIT_DIR/config`,
-* a file in the `$GIT_DIR/remotes` directory, or
-* a file in the `$GIT_DIR/branches` directory.
-
-All of these also allow you to omit the refspec from the command line
-because they each contain a refspec which git will use by default.
-
-Named remote in configuration file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can choose to provide the name of a remote which you had previously
-configured using linkgit:git-remote[1], linkgit:git-config[1]
-or even by a manual edit to the `$GIT_DIR/config` file.  The URL of
-this remote will be used to access the repository.  The refspec
-of this remote will be used by default when you do
-not provide a refspec on the command line.  The entry in the
-config file would appear like this:
-
-------------
-	[remote "<name>"]
-		url = <url>
-		pushurl = <pushurl>
-		push = <refspec>
-		fetch = <refspec>
-------------
-
-The `<pushurl>` is used for pushes only. It is optional and defaults
-to `<url>`.
-
-Named file in `$GIT_DIR/remotes`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can choose to provide the name of a
-file in `$GIT_DIR/remotes`.  The URL
-in this file will be used to access the repository.  The refspec
-in this file will be used as default when you do not
-provide a refspec on the command line.  This file should have the
-following format:
-
-------------
-	URL: one of the above URL format
-	Push: <refspec>
-	Pull: <refspec>
-
-------------
-
-`Push:` lines are used by 'git push' and
-`Pull:` lines are used by 'git pull' and 'git fetch'.
-Multiple `Push:` and `Pull:` lines may
-be specified for additional branch mappings.
-
-Named file in `$GIT_DIR/branches`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can choose to provide the name of a
-file in `$GIT_DIR/branches`.
-The URL in this file will be used to access the repository.
-This file should have the following format:
-
-
-------------
-	<url>#<head>
-------------
-
-`<url>` is required; `#<head>` is optional.
-
-Depending on the operation, git will use one of the following
-refspecs, if you don't provide one on the command line.
-`<branch>` is the name of this file in `$GIT_DIR/branches` and
-`<head>` defaults to `master`.
-
-git fetch uses:
-
-------------
-	refs/heads/<head>:refs/heads/<branch>
-------------
-
-git push uses:
-
-------------
-	HEAD:refs/heads/<head>
-------------
-
-
-
-
+include::urls.txt[]
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
dissimilarity index 98%
index 459a394..01ee49b 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -1,81 +1,5 @@
-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/
-- {startsb}user@{endsb}host.xz:path/to/repo.git
-
-To sync with a local directory, you can use:
-
-- /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.
-endif::git-clone[]
-
-ifdef::git-clone[]
-They are equivalent, except the former implies --local option.
-endif::git-clone[]
-
-
-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
-use will be rewritten into URLs that work), you can create a
-configuration section of the form:
-
-------------
-	[url "<actual url base>"]
-		insteadOf = <other url base>
-------------
-
-For example, with this:
-
-------------
-	[url "git://git.host.xz/"]
-		insteadOf = host.xz:/path/to/
-		insteadOf = work:
-------------
-
-a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
-rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".
-
-If you want to rewrite URLs for push only, you can create a
-configuration section of the form:
-
-------------
-	[url "<actual url base>"]
-		pushInsteadOf = <other url base>
-------------
-
-For example, with this:
-
-------------
-	[url "ssh://example.org/"]
-		pushInsteadOf = git://example.org/
-------------
-
-a URL like "git://example.org/path/to/repo.git" will be rewritten to
-"ssh://example.org/path/to/repo.git" for pushes, but pulls will still
-use the original URL.
+GIT URLS[[URLS]]
+----------------
+See linkgit:giturl[7] for an explanation of the supported values for
+`<repository>` (such as `git://host.xz/path`, `http://host.xz/path`,
+and `origin`).
-- 
1.7.0.4.369.g62d9d

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

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> The main idea driving this for me is that the reference manual should be
> something that a sufficiently interested person could read from cover to
> cover.  As it is, there’s too much repetition for that.

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.  While I fully share your
"cover-to-cover" concern, the current organization was chosen to minimize
such indirection.  It is optimized for different audiences than we are (I
am also from "cover-to-cover" school) who want to pick only the pages
relevant to the task at hand.

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

[Ramkumar Ramachandra]

Hi,

> While I fully share your
> "cover-to-cover" concern, the current organization was chosen to minimize
> such indirection.  It is optimized for different audiences than we are (I
> am also from "cover-to-cover" school) who want to pick only the pages
> relevant to the task at hand.

I am of the opinion that we can have both. Jonathan's document can be
a more elaborate version of the standard urls.txt included in all
these documents. I can see several usecases- for example, in documents
like remote-helpers.txt, including a full section from urls.txt would
be a bit of an overkill; we could include a reference to this document
instead. Is redundancy an issue? We'd have to update both urls.txt and
this document everytime we change something.

-- Ram

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

[Jonathan Nieder]

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:/".