{"thread":{"id":"23235","subject":"[RFC PATCH] Write new giturl(7) manpage","startedAt":"2010-03-29T14:59:26Z","lastAt":"2010-04-06T21:33:41Z","messageCount":13,"participants":["Ramkumar Ramachandra","Daniel Barkalow","Ilari Liusvaara","Sverre Rabbelier","Jonathan Nieder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"138093","messageId":"f3271551003290759g154b149fl7877d9b83e1313e6@mail.gmail.com","threadId":"23235","inReplyTo":null,"subject":"[RFC PATCH] Write new giturl(7) manpage","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-29T14:59:26Z","receivedAt":"2010-03-29T14:59:26Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Write a new manpage for documenting how different URLs are handled by\nremote helpers.\n---\n It severely lacks polish, but I thought I'd send in an early draft requesting\n comments. Also, I've made it more cryptic than Jonathan's revision and\n included more references.\n\n I'm not entirely happy with it because the remote vcs setting doesn't\n quite fit here. Plus, it seems like a dirty hack to me. The name doesn't do\n justice: giturl exists to host Ilari's remote helper notes. How can it be\n expanded to be more general?\n\n Why doesn't urls.txt document ::
syntax? Should I\n fix this?\n\n Documentation/giturl.txt | 85 ++++++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 85 insertions(+), 0 deletions(-)\n create mode 100644 Documentation/giturl.txt\n\ndiff --git a/Documentation/giturl.txt b/Documentation/giturl.txt\nnew file mode 100644\nindex 0000000..9ffd17c\n--- /dev/null\n+++ b/Documentation/giturl.txt\n@@ -0,0 +1,85 @@\n+giturl(7)\n+=========\n+\n+NAME\n+----\n+giturl - An overview on how different URLs are handled by Git\n+\n+SYNOPSIS\n+--------\n+git *\n+\n+DESCRIPTION\n+-----------\n+\n+URLs are used in two places. Directly on the command line by the end\n+user, and in remotes configuration (see REMOTES section below). They\n+all have the general structure described in the URLS section\n+below. While most of them are handled by Git internally, some of them\n+are handled by remote helper programs. When a URL thatgit doesn't\n+handle internally is encountered either on the command line or in the\n+remotes configuration, a remote helper that does will be used\n+transparently by the transport machinery of git (i.e., by commands\n+such as git ls-remote, git send-pack, and git archive --remote). The\n+following is a list of such URLs:\n+\n+::
\n+~~~~~~~~~~~~~~~~~~~~~~\n+A URL of the form `::` is used on the command\n+line by the end-user.\n+\n+The 'git remote-' helper will be invoked with the full\n+:: URL as the first argument and
as\n+the second argument.\n+\n+ with vcs set\n+~~~~~~~~~~~~~~~~~~~\n+`remote..vcs` is set to `` (see\n+git-config[1]). `remote..url` is optionally set to a URL of the\n+form `://`.\n+\n+If the `remote..url` is set, the helper will be invoked with\n+`` as the first argument and `` as the second\n+argument. Otherwise, the helper will be invoked with a single\n+argument, ``.\n+\n+ with vcs unset\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+`remote..url` is set to a URL of the form\n+`://`.\n+\n+The ‘git remote-’ helper will be invoked with the\n+`` as first argument and `://` as the\n+second argument.\n+\n+Exception: the built-in 'rsync', 'file', 'git', 'ssh', 'git+ssh', and\n+'ssh+git' transports are not handled using remote helpers.\n+\n+://\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+A URL of the form `://` is used on the command\n+line by the end-user.\n+\n+If 'transport' is not one of the built-in protocols listed above, the\n+'git remote-' helper will be invoked with two arguments,\n+both equal to the full `://` URL.\n+\n+include::urls-remotes.txt[]\n+\n+SEE ALSO\n+--------\n+linkgit:git-remote-helpers[1]\n+linkgit:git-remote[1]\n+linkgit:git-config[1]\n+\n+Author\n+------\n+Written by Ramkumar Ramachandra\n+\n+Documentation\n+-------------\n+Documentation by Ilari Liusvaara and the git-list \n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n-- \n1.7.0.3\n"},{"id":"138098","messageId":"alpine.LNX.2.00.1003291140270.14365@iabervon.org","threadId":"23235","inReplyTo":"f3271551003290759g154b149fl7877d9b83e1313e6@mail.gmail.com","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2010-03-29T15:48:18Z","receivedAt":"2010-03-29T15:48:18Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Mon, 29 Mar 2010, Ramkumar Ramachandra wrote:\n\n> Write a new manpage for documenting how different URLs are handled by\n> remote helpers.\n> ---\n> It severely lacks polish, but I thought I'd send in an early draft requesting\n> comments. Also, I've made it more cryptic than Jonathan's revision and\n> included more references.\n> \n> I'm not entirely happy with it because the remote vcs setting doesn't\n> quite fit here. Plus, it seems like a dirty hack to me. The name doesn't do\n> justice: giturl exists to host Ilari's remote helper notes. How can it be\n> expanded to be more general?\n> \n> Why doesn't urls.txt document ::
syntax? Should I\n> fix this?\n\nOne useful way of answering questions like this is to find the commits \nthat added the ::
syntax (probably easiest with git \nblame), and at the commits that touched urls.txt (probably with git log), \nand see if the reading the messages makes it obvious. I'd guess (without \nactually looking myself) that it was just overlooked.\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"138099","messageId":"20100329155523.GA31829@LK-Perkele-V2.elisa-laajakaista.fi","threadId":"23235","inReplyTo":"alpine.LNX.2.00.1003291140270.14365@iabervon.org","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Ilari Liusvaara","fromEmail":"ilari.liusvaara@elisanet.fi","sentAt":"2010-03-29T15:55:23Z","receivedAt":"2010-03-29T15:55:23Z","isPatch":true,"sender":{"key":"ilari.liusvaara@elisanet.fi","avatar":null},"body":"On Mon, Mar 29, 2010 at 11:48:18AM -0400, Daniel Barkalow wrote:\n> On Mon, 29 Mar 2010, Ramkumar Ramachandra wrote:\n> \n> > Why doesn't urls.txt document ::
syntax? Should I\n> > fix this?\n> \n> One useful way of answering questions like this is to find the commits \n> that added the ::
syntax (probably easiest with git \n> blame), and at the commits that touched urls.txt (probably with git log), \n> and see if the reading the messages makes it obvious. I'd guess (without \n> actually looking myself) that it was just overlooked.\n\nI think the following commit added that syntax:\n\ncommit 87422439d100f020cadb63b5da8495e5fbfb8fa3\nAuthor: Johannes Schindelin \nDate: Wed Nov 18 02:42:26 2009 +0100\n\n Allow specifying the remote helper in the url\n \n The common case for remote helpers will be to import some repository\n which can be specified by a single URL. Support this use case by\n allowing users to say:\n \n git clone hg::https://soc.googlecode.com/hg/ soc\n \n Signed-off-by: Johannes Schindelin \n Signed-off-by: Sverre Rabbelier \n Signed-off-by: Junio C Hamano \n\nAFAICT, urls.txt hasn't been touched since this commit.\n\n-Ilari\n"},{"id":"138101","messageId":"fabb9a1e1003290859p25be2d7aqc7dcb46f3ec7ba4f@mail.gmail.com","threadId":"23235","inReplyTo":"20100329155523.GA31829@LK-Perkele-V2.elisa-laajakaista.fi","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-03-29T15:59:52Z","receivedAt":"2010-03-29T15:59:52Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Mar 29, 2010 at 09:55, Ilari Liusvaara\n wrote:\n> AFAICT, urls.txt hasn't been touched since this commit.\n\nYup, my bad for not updating urls.txt (mainly because I didn't know it\nexisted :P). I think Ramkumar's patch [0] to fix that is a step in the\nright direction :).\n\n[] http://mid.gmane.org/f3271551003290810u4edbbbd0x2432bc7411333800@mail.gmail.com\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"138114","messageId":"f3271551003291005rf2d2e57p90dad68e451e1ff3@mail.gmail.com","threadId":"23235","inReplyTo":"fabb9a1e1003290859p25be2d7aqc7dcb46f3ec7ba4f@mail.gmail.com","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-29T17:05:12Z","receivedAt":"2010-03-29T17:05:12Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> One useful way of answering questions like this is to find the commits\n> that added the ::
syntax (probably easiest with git\n> blame), and at the commits that touched urls.txt (probably with git log),\n> and see if the reading the messages makes it obvious. I'd guess (without\n> actually looking myself) that it was just overlooked.\n\nGot it.\n\n> Yup, my bad for not updating urls.txt (mainly because I didn't know it\n> existed :P). I think Ramkumar's patch [0] to fix that is a step in the\n> right direction :).\n\nThanks :) I've prepared a second revision, which is a complete rewrite\nof urls. In the meantime, could you review this patch?\n\n-- Ram\n"},{"id":"138122","messageId":"20100329191832.GA26842@progeny.tock","threadId":"23235","inReplyTo":"f3271551003290759g154b149fl7877d9b83e1313e6@mail.gmail.com","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-29T19:18:32Z","receivedAt":"2010-03-29T19:18:32Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> I'm not entirely happy with it because the remote vcs setting doesn't\n> quite fit here. Plus, it seems like a dirty hack to me. The name doesn't do\n> justice: giturl exists to host Ilari's remote helper notes.\n\nI suppose you are right. I was imagining something like this:\n\n NAME\n ----\n giturl - Specifying remote repositories to Git\n\n SYNOPSIS\n --------\n ://, :, ::
, \n\n DESCRIPTION\n -----------\n To specify a remote repository using Git’s native protocol, one can\n use a traditional-looking URL.\n\n . git://host.xz[:port]/path/to/repo.git/\n . git://host.xz[:port]/~user/path/to/repo.git/\n\n For the SSH protocol, often used with 'git push', use the traditional syntax\n supported by 'scp'. You can optionally specify which user to log in as.\n\n . [user@]host.xz:/path/to/repo.git/\n . [user@]host.xz:path/to/repo.git/\n\n That syntax does not allow specifying a port number. For this, a more\n verbose URL-style syntax is supported.\n\n . ssh://[user@]host.xz[:port]/path/to/repo.git/\n . ssh://[user@]host.xz[:port]/~[otheruser]/path/to/repo.git/\n\n Frequently-accessed repositories can be given a short alphanumeric\n nickname. For example, the 'parent repository' for a new clone is\n automatically given the nickname 'origin'. See linkgit:git-remote[1] for\n details.\n\n . nickname\n\n A path on the current machine can be used directly. If a repository is\n specified in this way to the linkgit:git-clone[1] command, the clone will\n automatically use the --local option (which see). The file:// syntax\n can be used to avoid this behavior.\n\n . /path/to/repo.git/\n . path/to/repo.git/\n\n Other protocols (most notably HTTP) can be specified with the\n schema://path syntax. Support for the 'rsync', 'file', 'git', 'ssh',\n 'git+ssh', and 'ssh+git' transports is built in.\n\n If Git was installed with HTTP support, then the 'http', 'https',\n 'ftp', and 'ftps' schemata will be supported through helper programs.\n Third-party helpers may support other protocols, for example for\n interaction with other version control systems. The syntax\n `transport::schema://path` can be used, or `transport://path` if\n the helper is already named after a URL schema. The\n 'git remote-' helper will be used to service the request,\n with `schema://path` passed as the associated URL.\n See also linkgit:git-remote-helpers[7].\n\n . http[s]://[user@]host.xz[:port]/[~user/]path/to/repo.git/\n . ftp[s]://[user@]host.xz[:port]/[~user/]path/to/repo.git/\n . file:///path/to/repo.git/\n . rsync://[user@]host.xz[:port]/path/to/repo.git/\n . http::http://[user@]host.xz[:port]/[~user/]path/to/repo.git/\n . etc\n\ngit-remote(1) would include the information currently in remote-urls.txt\nabout remote nicknames, plus:\n\n - how to specify a relevant vcs helper\n - the pushurl setting\n\nPages such as git-clone(1) that currently include urls.txt or\nremote-urls.txt could have the remote section replaced with something\nshorter:\n\n See giturls(7) for an explanation of the supported values for \n (git://host.xz/path, http://host.xz/path, and so on).\n\nBut this is more major surgery than the purpose of your patch calls\nfor. If you find a simpler way to convey the relevant information in\nthe meantime, I can prepare a patch this weekend.\n\nThanks,\nJonathan\n"},{"id":"138123","messageId":"fabb9a1e1003291221m4a3ec9b1lac7eda1a3d896d79@mail.gmail.com","threadId":"23235","inReplyTo":"20100329191832.GA26842@progeny.tock","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-03-29T19:21:13Z","receivedAt":"2010-03-29T19:21:13Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Mar 29, 2010 at 13:18, Jonathan Nieder wrote:\n> I suppose you are right.  I was imagining something like this:\n\nWow, nice. I like it. Well written :).\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"138124","messageId":"f3271551003291224s7fb0d8d3sce75b7c893fabfa8@mail.gmail.com","threadId":"23235","inReplyTo":"20100329191832.GA26842@progeny.tock","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-29T19:24:23Z","receivedAt":"2010-03-29T19:24:23Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"On Tue, Mar 30, 2010 at 12:48 AM, Jonathan Nieder wrote:\n> I suppose you are right.  I was imagining something like this:\n\nYour patch looks awesome. It looks like I didn't have the right idea.\nI'll drop this patch- you can write one.\n\n-- Ram\n"},{"id":"138125","messageId":"f3271551003291235p690dc200mfff119270768d873@mail.gmail.com","threadId":"23235","inReplyTo":"f3271551003291224s7fb0d8d3sce75b7c893fabfa8@mail.gmail.com","subject":"Re: [RFC PATCH] Write new giturl(7) manpage","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-29T19:35:06Z","receivedAt":"2010-03-29T19:35:06Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> On Tue, Mar 30, 2010 at 12:48 AM, Jonathan Nieder wrote:\n> I suppose you are right.  I was imagining something like this:\n\nMy only concern is that it shouldn't duplicate too much of the\ninformation in urls.txt. Also, it'll be nice if it's consistent with\nthe new urls.txt after my patch [1].\n\n-- Ram\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/143499\n"},{"id":"138711","messageId":"20100406060606.GA26629@progeny.tock","threadId":"23235","inReplyTo":"f3271551003291224s7fb0d8d3sce75b7c893fabfa8@mail.gmail.com","subject":"[PATCH/RFC] Documentation: reorganize documentation of URLs understood by git","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-04-06T06:06:07Z","receivedAt":"2010-04-06T06:06:07Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Currently, the git documentation includes several copies of the same\nexplanation of the format of git URLs and git remotes. On one hand,\nthis makes some manual pages (e.g., git-fetch(1) and git-pull(1))\nappear longer than they really ought to be, and on the other hand, it\nmakes it difficult to find a single appropriate page to link to online\nto answer questions about these topics.\n\nSo add a new giturl(7) page describing the format of URLs understood\nby git, move the explanation of remote nicknames to git-remote(1), and\nreplace urls.txt and urls-remote.txt with pointers to these pages.\n\nWhile at it, add some explanation of the new mechanisms for accessing\na repository using a third-party tool. This is meant to be more\nuseful for users learning to use git than for tool authors, but with\nsome tweaks it should be useful for the latter, too.\n\nThis documentation was improved with feedback from Ilari, Ram,\nSverre, and Daniel. It is still very rough.\n\nCc: Daniel Barkalow \nCc: Ilari Liusvaara \nCc: Sverre Rabbelier \nCc: Ramkumar Ramachandra \nSigned-off-by: Jonathan Nieder \n---\nHi,\n\nHere is the suggested page explaining URLs recognized by git I mentioned\nbefore. It was harder to find time this weekend for this then I thought\n--- sorry.\n\nAbout half of the patch is taken up by moving text from urls-remotes.txt\nto git-remote.txt. If anyone has ideas for making this more convenient\nto read, I’m all ears.\n\nThe main idea driving this for me is that the reference manual should be\nsomething that a sufficiently interested person could read from cover to\ncover. As it is, there’s too much repetition for that. I also would\nlike each topic to be documented clearly and thoroughly in an easy-to-find\nplace; it seems unlikely this achieves those first two criteria, but at\nleast this way I think the information about Git URLs should be easy to\nfind.\n\nSuggestions on language and organization are especially welcome. This\nis just to get the ball rolling; hopefully someone more capable of\nwriting clear documentation can help meld the page into something\npeople can use.\n\nPatch is against master.\n\nThoughts?\nJonathan\n\n Documentation/Makefile | 2 +-\n Documentation/git-remote.txt | 109 ++++++++++++++++++++++++++++++++++++++-\n Documentation/giturl.txt | 105 ++++++++++++++++++++++++++++++++++++++\n Documentation/urls-remotes.txt | 95 +----------------------------------\n Documentation/urls.txt | 86 ++-----------------------------\n 5 files changed, 218 insertions(+), 179 deletions(-)\n create mode 100644 Documentation/giturl.txt\n rewrite Documentation/urls-remotes.txt (99%)\n rewrite Documentation/urls.txt (98%)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 8a8a395..97c41ed 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -4,7 +4,7 @@ MAN1_TXT= \\\n \tgitk.txt git.txt\n MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \\\n \tgitrepository-layout.txt\n-MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \\\n+MAN7_TXT=gitcli.txt giturl.txt gittutorial.txt gittutorial-2.txt \\\n \tgitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \\\n \tgitdiffcore.txt gitworkflows.txt\n \ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 3fc599c..352e762 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -146,13 +146,115 @@ be updated. (See linkgit:git-config[1]).\n +\n With `--prune` option, prune all the remotes that are updated.\n \n+REMOTES[[REMOTES]]\n+------------------\n+\n+The name of one of the following can be used by the various git\n+commands instead of a URL as `` argument:\n+\n+* a remote in the git configuration file: `$GIT_DIR/config`,\n+* a file in the `$GIT_DIR/remotes` directory, or\n+* a file in the `$GIT_DIR/branches` directory.\n+\n+All of these also allow you to omit the refspec from the command line\n+because they each contain a refspec which git will use by default.\n+\n+Named remote in configuration file\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+You can choose to provide the name of a remote which you had previously\n+configured using 'git remote', linkgit:git-config[1]\n+or by a manual edit to the `$GIT_DIR/config` file. The URL of\n+this remote will be used to access the repository. The refspec\n+of this remote will be used by default when you do\n+not provide a refspec on the command line. The section in the\n+config file would appear like this:\n+\n+------------\n+\t[remote \"\"]\n+\t\tvcs = \n+\t\turl = \n+\t\tpushurl = \n+\t\tpush = \n+\t\tfetch = \n+------------\n+\n+If no 'vcs' item is present, the 'url' is mandatory and identifies\n+the repository.\n+Any URL understood by git will work (see linkgit:giturl[7])\n+except for the name of a remote.\n+\n+The `` is used for pushes only. It is optional and defaults\n+to ``.\n+\n+A 'vcs' item can be used to request that a particular\n+'git remote-``' helper (see linkgit:git-remote-helpers[7])\n+be used to communicate with the remote repository.\n+This facility is intended for interoperability with version control\n+systems that require more configuration than a URL to identify a repository.\n+The 'url' variable in such a section is optional and its interpretation\n+depends on the helper.\n+\n+Named file in `$GIT_DIR/remotes`\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+You can choose to provide the name of a\n+file in `$GIT_DIR/remotes`. The URL\n+in this file will be used to access the repository. The refspec\n+in this file will be used as default when you do not\n+provide a refspec on the command line. This file should have the\n+following format:\n+\n+------------\n+\tURL: one of the above URL format\n+\tPush: \n+\tPull: \n+\n+------------\n+\n+`Push:` lines are used by 'git push' and\n+`Pull:` lines are used by 'git pull' and 'git fetch'.\n+Multiple `Push:` and `Pull:` lines may\n+be specified for additional branch mappings.\n+\n+Named file in `$GIT_DIR/branches`\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+You can choose to provide the name of a\n+file in `$GIT_DIR/branches`.\n+The URL in this file will be used to access the repository.\n+This file should have the following format:\n+\n+\n+------------\n+\t#\n+------------\n+\n+`` is required; `#` is optional.\n+\n+Depending on the operation, git will use one of the following\n+refspecs, if you don't provide one on the command line.\n+`` is the name of this file in `$GIT_DIR/branches` and\n+`` defaults to `master`.\n+\n+git fetch uses:\n+\n+------------\n+\trefs/heads/:refs/heads/\n+------------\n+\n+git push uses:\n+\n+------------\n+\tHEAD:refs/heads/\n+------------\n \n DISCUSSION\n ----------\n \n-The remote configuration is achieved using the `remote.origin.url` and\n-`remote.origin.fetch` configuration variables. (See\n-linkgit:git-config[1]).\n+The remote configuration managed by 'git remote' is achieved using the\n+`remote.origin.url` and `remote.origin.fetch` configuration variables.\n+(See linkgit:git-config[1]).\n \n Examples\n --------\n@@ -194,6 +296,7 @@ SEE ALSO\n linkgit:git-fetch[1]\n linkgit:git-branch[1]\n linkgit:git-config[1]\n+linkgit:giturl[7]\n \n Author\n ------\ndiff --git a/Documentation/giturl.txt b/Documentation/giturl.txt\nnew file mode 100644\nindex 0000000..dfe4551\n--- /dev/null\n+++ b/Documentation/giturl.txt\n@@ -0,0 +1,105 @@\n+giturl(7)\n+=========\n+\n+NAME\n+----\n+giturl - Specifying remote repositories to Git\n+\n+SYNOPSIS\n+--------\n+://, :, ::
, \n+\n+DESCRIPTION\n+-----------\n+To specify a remote repository using Git's native protocol, one can\n+use a traditional-looking URL.\n+\n+- git://host.xz{startsb}:port{endsb}/path/to/repo.git/\n+- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/\n+\n+For the SSH protocol, often used with 'git push', use the traditional syntax\n+supported by 'scp'. You can optionally specify which user to log in as.\n+\n+- {startsb}user@{endsb}host.xz:/path/to/repo.git/\n+- {startsb}user@{endsb}host.xz:path/to/repo.git/\n+\n+That syntax does not allow specifying a port number. For this, a more\n+verbose URL-style syntax is supported.\n+\n+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/\n+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}otheruser{endsb}/path/to/repo.git/\n+\n+Frequently-accessed repositories can be given a short alphanumeric\n+nickname. For example, the parent repository for a new clone is\n+automatically given the nickname 'origin'. See linkgit:git-remote[1] for\n+details.\n+\n+- nickname\n+\n+A path on the current machine can be used directly. If a repository is\n+specified in this way to the linkgit:git-clone[1] command, the clone will\n+automatically use the `--local` option (which see). The `file://` syntax\n+can be used to avoid this behavior.\n+\n+- /path/to/repo.git/\n+- path/to/repo.git/\n+\n+Other protocols (most notably HTTP) can be specified with the\n+`schema://path` syntax. Support for the 'rsync', 'file', 'git', 'ssh',\n+'git+ssh', and 'ssh+git' transports is built in.\n+\n+If Git was installed with HTTP support, then the 'http', 'https',\n+'ftp', and 'ftps' schemata will be supported through helper programs.\n+Third-party helpers may support other protocols, for example for\n+interaction with other version control systems. The syntax\n+`transport::schema://path` can be used, or `transport://path` if\n+the helper is already named after a URL schema. The\n+'git remote-' helper will be used to service the request,\n+with `schema://path` passed as the associated URL.\n+See linkgit:git-remote-helpers[7] for details.\n+\n+- http{startsb}s{endsb}://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/\n+- ftp{startsb}s{endsb}://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/\n+- file:///path/to/repo.git/\n+- rsync://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/\n+- http::http://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/{startsb}~user/{endsb}path/to/repo.git/\n+\n+If there are a large number of similarly-named remote repositories and\n+you want to use a different format for them (such that the URLs you\n+use will be rewritten into URLs that work), you can create a\n+configuration section of the form:\n+\n+------------\n+\t[url \"\"]\n+\t\tinsteadOf = \n+------------\n+\n+For example, with this:\n+\n+------------\n+\t[url \"git://git.host.xz/\"]\n+\t\tinsteadOf = host.xz:/path/to/\n+\t\tinsteadOf = work:\n+------------\n+\n+a URL like \"work:repo.git\" or like \"host.xz:/path/to/repo.git\" will be\n+rewritten in any context that takes a URL to be \"git://git.host.xz/repo.git\".\n+\n+If you want to rewrite URLs for push only, you can create a\n+configuration section of the form:\n+\n+------------\n+\t[url \"\"]\n+\t\tpushInsteadOf = \n+------------\n+\n+For example, with this:\n+\n+------------\n+\t[url \"ssh://example.org/\"]\n+\t\tpushInsteadOf = git://example.org/\n+------------\n+\n+a URL like \"git://example.org/path/to/repo.git\" will be rewritten to\n+\"ssh://example.org/path/to/repo.git\" for pushes, but pulls will still\n+use the original URL.\ndiff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt\ndissimilarity index 99%\nindex 00f7e79..7ba74f0 100644\n--- a/Documentation/urls-remotes.txt\n+++ b/Documentation/urls-remotes.txt\n@@ -1,94 +1 @@\n-include::urls.txt[]\n-\n-REMOTES[[REMOTES]]\n-------------------\n-\n-The name of one of the following can be used instead\n-of a URL as `` argument:\n-\n-* a remote in the git configuration file: `$GIT_DIR/config`,\n-* a file in the `$GIT_DIR/remotes` directory, or\n-* a file in the `$GIT_DIR/branches` directory.\n-\n-All of these also allow you to omit the refspec from the command line\n-because they each contain a refspec which git will use by default.\n-\n-Named remote in configuration file\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You can choose to provide the name of a remote which you had previously\n-configured using linkgit:git-remote[1], linkgit:git-config[1]\n-or even by a manual edit to the `$GIT_DIR/config` file. The URL of\n-this remote will be used to access the repository. The refspec\n-of this remote will be used by default when you do\n-not provide a refspec on the command line. The entry in the\n-config file would appear like this:\n-\n-------------\n-\t[remote \"\"]\n-\t\turl = \n-\t\tpushurl = \n-\t\tpush = \n-\t\tfetch = \n-------------\n-\n-The `` is used for pushes only. It is optional and defaults\n-to ``.\n-\n-Named file in `$GIT_DIR/remotes`\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You can choose to provide the name of a\n-file in `$GIT_DIR/remotes`. The URL\n-in this file will be used to access the repository. The refspec\n-in this file will be used as default when you do not\n-provide a refspec on the command line. This file should have the\n-following format:\n-\n-------------\n-\tURL: one of the above URL format\n-\tPush: \n-\tPull: \n-\n-------------\n-\n-`Push:` lines are used by 'git push' and\n-`Pull:` lines are used by 'git pull' and 'git fetch'.\n-Multiple `Push:` and `Pull:` lines may\n-be specified for additional branch mappings.\n-\n-Named file in `$GIT_DIR/branches`\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You can choose to provide the name of a\n-file in `$GIT_DIR/branches`.\n-The URL in this file will be used to access the repository.\n-This file should have the following format:\n-\n-\n-------------\n-\t#\n-------------\n-\n-`` is required; `#` is optional.\n-\n-Depending on the operation, git will use one of the following\n-refspecs, if you don't provide one on the command line.\n-`` is the name of this file in `$GIT_DIR/branches` and\n-`` defaults to `master`.\n-\n-git fetch uses:\n-\n-------------\n-\trefs/heads/:refs/heads/\n-------------\n-\n-git push uses:\n-\n-------------\n-\tHEAD:refs/heads/\n-------------\n-\n-\n-\n-\n+include::urls.txt[]\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\ndissimilarity index 98%\nindex 459a394..01ee49b 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -1,81 +1,5 @@\n-GIT URLS[[URLS]]\n-----------------\n-\n-One of the following notations can be used\n-to name the remote repository:\n-\n-- rsync://host.xz/path/to/repo.git/\n-- http://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- https://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/\n-- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git\n-\n-SSH is the default transport protocol over the network. You can\n-optionally specify which user to log-in as, and an alternate,\n-scp-like syntax is also supported. Both syntaxes support\n-username expansion, as does the native git protocol, but\n-only the former supports port specification. The following\n-three are identical to the last three above, respectively:\n-\n-- {startsb}user@{endsb}host.xz:/path/to/repo.git/\n-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/\n-- {startsb}user@{endsb}host.xz:path/to/repo.git\n-\n-To sync with a local directory, you can use:\n-\n-- /path/to/repo.git/\n-- file:///path/to/repo.git/\n-\n-ifndef::git-clone[]\n-They are mostly equivalent, except when cloning. See\n-linkgit:git-clone[1] for details.\n-endif::git-clone[]\n-\n-ifdef::git-clone[]\n-They are equivalent, except the former implies --local option.\n-endif::git-clone[]\n-\n-\n-If there are a large number of similarly-named remote repositories and\n-you want to use a different format for them (such that the URLs you\n-use will be rewritten into URLs that work), you can create a\n-configuration section of the form:\n-\n-------------\n-\t[url \"\"]\n-\t\tinsteadOf = \n-------------\n-\n-For example, with this:\n-\n-------------\n-\t[url \"git://git.host.xz/\"]\n-\t\tinsteadOf = host.xz:/path/to/\n-\t\tinsteadOf = work:\n-------------\n-\n-a URL like \"work:repo.git\" or like \"host.xz:/path/to/repo.git\" will be\n-rewritten in any context that takes a URL to be \"git://git.host.xz/repo.git\".\n-\n-If you want to rewrite URLs for push only, you can create a\n-configuration section of the form:\n-\n-------------\n-\t[url \"\"]\n-\t\tpushInsteadOf = \n-------------\n-\n-For example, with this:\n-\n-------------\n-\t[url \"ssh://example.org/\"]\n-\t\tpushInsteadOf = git://example.org/\n-------------\n-\n-a URL like \"git://example.org/path/to/repo.git\" will be rewritten to\n-\"ssh://example.org/path/to/repo.git\" for pushes, but pulls will still\n-use the original URL.\n+GIT URLS[[URLS]]\n+----------------\n+See linkgit:giturl[7] for an explanation of the supported values for\n+`` (such as `git://host.xz/path`, `http://host.xz/path`,\n+and `origin`).\n-- \n1.7.0.4.369.g62d9d\n"},{"id":"138716","messageId":"7v6345jcfq.fsf@alter.siamese.dyndns.org","threadId":"23235","inReplyTo":"20100406060606.GA26629@progeny.tock","subject":"Re: [PATCH/RFC] Documentation: reorganize documentation of URLs understood by git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-06T06:57:13Z","receivedAt":"2010-04-06T06:57:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> The main idea driving this for me is that the reference manual should be\n> something that a sufficiently interested person could read from cover to\n> cover. As it is, there’s too much repetition for that.\n\nI am of two minds. It is frustrating if \"git clone\" (or \"git fetch\", or\n\"git remote\") page didn't list any examples an intelligent person (or at\nleast one who thinks he is intelligent enough) to mimic and instead\nreferred him with \"look there\" indirections. While I fully share your\n\"cover-to-cover\" concern, the current organization was chosen to minimize\nsuch indirection. It is optimized for different audiences than we are (I\nam also from \"cover-to-cover\" school) who want to pick only the pages\nrelevant to the task at hand.\n"},{"id":"138720","messageId":"l2hf3271551004060040v4eca088ck8f1ab3376c0f889c@mail.gmail.com","threadId":"23235","inReplyTo":"7v6345jcfq.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC] Documentation: reorganize documentation of URLs understood by git","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-04-06T07:40:44Z","receivedAt":"2010-04-06T07:40:44Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\n> While I fully share your\n> \"cover-to-cover\" concern, the current organization was chosen to minimize\n> such indirection.  It is optimized for different audiences than we are (I\n> am also from \"cover-to-cover\" school) who want to pick only the pages\n> relevant to the task at hand.\n\nI am of the opinion that we can have both. Jonathan's document can be\na more elaborate version of the standard urls.txt included in all\nthese documents. I can see several usecases- for example, in documents\nlike remote-helpers.txt, including a full section from urls.txt would\nbe a bit of an overkill; we could include a reference to this document\ninstead. Is redundancy an issue? We'd have to update both urls.txt and\nthis document everytime we change something.\n\n-- Ram\n"},{"id":"138782","messageId":"20100406213341.GA8448@progeny.tock","threadId":"23235","inReplyTo":"7v6345jcfq.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC] Documentation: reorganize documentation of URLs understood by git","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-04-06T21:33:41Z","receivedAt":"2010-04-06T21:33:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> I am of two minds. It is frustrating if \"git clone\" (or \"git fetch\", or\n> \"git remote\") page didn't list any examples an intelligent person (or at\n> least one who thinks he is intelligent enough) to mimic and instead\n> referred him with \"look there\" indirections.\n\nMakes sense. So it should be self-contained for at least the common cases.\nSomething like:\n\nGIT URLS\n\n\tOne of the following notations can be used to name the remote repository:\n\n\t· git://host.xz[:port]/path/to/repo.git/\n\t· git://host.xz[:port]/~user/path/to/repo.git/\n\t· [user@]host.xz:~user/path/to/repo.git/\n\t· [user@]host.xz:/path/to/repo.git/\n\t· [user@]host.xz:path/to/repo.git/\n\t· ssh://host.xz[:port]/path/to/repo.git/\n\t· ssh://host.xz[:port]/~user/path/to/repo.git/\n\t· /path/to/local/repo.git/\n\t· path/to/local/repo.git/\n\t· file:///path/to/repo.git/\n\t· svn::http://host.xz[:port]/path/to/repo/\n\n\tSchemas supported include git, ssh, file, rsync, and if HTTP support\n\tis installed, http, https, ftp, and ftps.\n\n\tGit can be taught to support additional schemas by installing a\n\t'git-remote-' helper to your $PATH. See git-remote-helpers(7)\n\tif you want to write one.\n\n\tThe url.*.insteadOf and url.*.pushInsteadOf configuration items\n\taffect URLs supplied to this command. This can be useful if\n\tthere are a large number of similarly-named remote repositories\n\tand you want to use a different format for them. See gitconfig(5)\n\tfor details on setting this up.\n\nUnfortunately, that leaves out any explanation of which transport you would\nwant to use; in particular, it doesn’t say\n\n * Using local paths implies a request for \"clone --local\" unless the\n louder file:// syntax is used;\n\n * If you were thinking of using host.xz:port:/path/to/, use ssh://\n instead. [1]\n\n * The git protocol is very nice, but it does not support authentication.\n If that is a problem for you, use ssh instead for pushing.\n\n The rsync protocol support is bitrotting.\n\n http and ftp can be used as “smart” or “dumb” protocols; the former\n requires that the server administrator install a CGI script to serve\n requests efficiently; the latter is all some hosting services\n provide, and it has some caveats like requiring update-server-info.\n\nNot sure where this should go.\n\nThanks for the food for thought,\nJonathan\n\n[1] Aside: Is there any reason for git and scp not to learn to support\nthe two-colon syntax? I would think directories named 1087: are a rather\nrare beast, and they could still be accessed as \"host.xz:./1087:/\".\n"}]}