{"thread":{"id":"13723","subject":"[DOC-PATCH v2] Clarify description of <repository> argument to pull/fetch for naming remotes.","startedAt":"2008-05-29T17:32:31Z","lastAt":"2008-05-29T17:32:31Z","messageCount":1,"participants":["John J. Franey"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"78065","messageId":"1212082351.12242.6.camel@isidore.myhome.westell.com","threadId":"13723","inReplyTo":null,"subject":"[DOC-PATCH v2] Clarify description of <repository> argument to pull/fetch for naming remotes.","fromName":"John J. Franey","fromEmail":"jjfraney@gmail.com","sentAt":"2008-05-29T17:32:31Z","receivedAt":"2008-05-29T17:32:31Z","isPatch":true,"sender":{"key":"jjfraney@gmail.com","avatar":null},"body":"\nAlter the description of <repository> in OPTIONS section to\nexplicitly state that a 'remote name' is accepted.\nRewrite REMOTES section to more directly identify the\ndifferent kinds of remote-name permitted.\n\nSigned-off-by: John J. Franey <jjfraney@gmail.com>\n---\n\n Here is a second version of a proposal to change the\n wording in git-pull/git-fetch.  I believe I have addressed all\n of Junio's comments.\n\n Documentation/pull-fetch-param.txt |    4 +-\n Documentation/urls-remotes.txt     |   93 +++++++++++++++++++++++-------------\n 2 files changed, 63 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex b6eb7fc..cbee369 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -1,6 +1,8 @@\n <repository>::\n \tThe \"remote\" repository that is the source of a fetch\n-\tor pull operation.  See the section <<URLS,GIT URLS>> below.\n+\tor pull operation.  This parameter can be either a URL\n+\t(see the section <<URLS,GIT URLS>> below) or the name\n+\tof a remote (see the section <<REMOTES,REMOTES>> below).\n \n <refspec>::\n \tThe canonical format of a <refspec> parameter is\ndiff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt\nindex 5dd1f83..9975300 100644\n--- a/Documentation/urls-remotes.txt\n+++ b/Documentation/urls-remotes.txt\n@@ -1,55 +1,82 @@\n include::urls.txt[]\n \n-REMOTES\n--------\n+REMOTES[[REMOTES]]\n+------------------\n \n-In addition to the above, as a short-hand, the name of a\n-file in `$GIT_DIR/remotes` directory can be given; the\n-named file should be in the following format:\n+The name of one of the following can be used instead\n+of a URL as `<repository>` argument:\n \n-------------\n-\tURL: one of the above URL format\n-\tPush: <refspec>\n-\tPull: <refspec>\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-------------\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-Then such a short-hand is specified in place of\n-<repository> without <refspec> parameters on the command\n-line, <refspec> specified on `Push:` lines or `Pull:`\n-lines are used for `git-push` and `git-fetch`/`git-pull`,\n-respectively.  Multiple `Push:` and `Pull:` lines may\n-be specified for additional branch mappings.\n+Named remote in configuration file\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-Or, equivalently, in the `$GIT_DIR/config` (note the use\n-of `fetch` instead of `Pull:`):\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 \"<remote>\"]\n+\t[remote \"<name>\"]\n \t\turl = <url>\n \t\tpush = <refspec>\n \t\tfetch = <refspec>\n-\n ------------\n \n-The name of a file in `$GIT_DIR/branches` directory can be\n-specified as an older notation short-hand; the named\n-file should contain a single line, a URL in one of the\n-above formats, optionally followed by a hash `#` and the\n-name of remote head (URL fragment notation).\n-`$GIT_DIR/branches/<remote>` file that stores a <url>\n-without the fragment is equivalent to have this in the\n-corresponding file in the `$GIT_DIR/remotes/` directory.\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: <refspec>\n+\tPull: <refspec>\n \n ------------\n-\tURL: <url>\n-\tPull: refs/heads/master:<remote>\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<url>#<head>\n ------------\n \n-while having `<url>#<head>` is equivalent to\n+`<url>` is required; `#<head>` is optional.\n+When you do not provide a refspec on the command line,\n+git will use the following refspec, where `<head>` defaults to `master`,\n+and `<repository>` is the name of this file\n+you provided in the command line.\n \n ------------\n-\tURL: <url>\n-\tPull: refs/heads/<head>:<remote>\n+\trefs/heads/<head>:<repository>\n ------------\n+\n+\n+\n+\n-- \n1.5.4.3\n"}]}