Clarify description of <repository> argument to pull/fetch for naming remotes.
Alter the description of <repository> in OPTIONS section to explicitly state that a 'remote name' is accepted. Rewrite REMOTES section to more directly identify the different kinds of remote-name permitted. Signed-off-by: John J. Franey <jjfraney@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
John J. Franey committed
May 29, 2008 at 13:32 UTC
5812473335161e3d8e5a1e085c5894a247472bdb
2 files changed
+63
-34
Documentation/pull-fetch-param.txt
+3
-1
@@ -1,6 +1,8 @@
1
<repository>::
2
The "remote" repository that is the source of a fetch
3
- or pull operation. See the section <<URLS,GIT URLS>> below.
3
+ or pull operation. This parameter can be either a URL
4
+ (see the section <<URLS,GIT URLS>> below) or the name
5
+ of a remote (see the section <<REMOTES,REMOTES>> below).
6
7
<refspec>::
8
The canonical format of a <refspec> parameter is
Documentation/urls-remotes.txt
+60
-33
@@ -1,55 +1,82 @@
1
include::urls.txt[]
2
3
-REMOTES
4
--------
3
+REMOTES[[REMOTES]]
4
+------------------
5
6
-In addition to the above, as a short-hand, the name of a
7
-file in `$GIT_DIR/remotes` directory can be given; the
8
-named file should be in the following format:
6
+The name of one of the following can be used instead
7
+of a URL as `<repository>` argument:
8
10
-------------
11
- URL: one of the above URL format
12
- Push: <refspec>
13
- Pull: <refspec>
9
+* a remote in the git configuration file: `$GIT_DIR/config`,
10
+* a file in the `$GIT_DIR/remotes` directory, or
11
+* a file in the `$GIT_DIR/branches` directory.
12
15
-------------
13
+All of these also allow you to omit the refspec from the command line
14
+because they each contain a refspec which git will use by default.
15
17
-Then such a short-hand is specified in place of
18
-<repository> without <refspec> parameters on the command
19
-line, <refspec> specified on `Push:` lines or `Pull:`
20
-lines are used for `git-push` and `git-fetch`/`git-pull`,
21
-respectively. Multiple `Push:` and `Pull:` lines may
22
-be specified for additional branch mappings.
16
+Named remote in configuration file
17
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18
24
-Or, equivalently, in the `$GIT_DIR/config` (note the use
25
-of `fetch` instead of `Pull:`):
19
+You can choose to provide the name of a remote which you had previously
20
+configured using linkgit:git-remote[1], linkgit:git-config[1]
21
+or even by a manual edit to the `$GIT_DIR/config` file. The URL of
22
+this remote will be used to access the repository. The refspec
23
+of this remote will be used by default when you do
24
+not provide a refspec on the command line. The entry in the
25
+config file would appear like this:
26
27
------------
28
- [remote "<remote>"]
28
+ [remote "<name>"]
29
url = <url>
30
push = <refspec>
31
fetch = <refspec>
32
-
32
------------
33
35
-The name of a file in `$GIT_DIR/branches` directory can be
36
-specified as an older notation short-hand; the named
37
-file should contain a single line, a URL in one of the
38
-above formats, optionally followed by a hash `#` and the
39
-name of remote head (URL fragment notation).
40
-`$GIT_DIR/branches/<remote>` file that stores a <url>
41
-without the fragment is equivalent to have this in the
42
-corresponding file in the `$GIT_DIR/remotes/` directory.
34
+
35
+Named file in `$GIT_DIR/remotes`
36
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37
+
38
+You can choose to provide the name of a
39
+file in `$GIT_DIR/remotes`. The URL
40
+in this file will be used to access the repository. The refspec
41
+in this file will be used as default when you do not
42
+provide a refspec on the command line. This file should have the
43
+following format:
44
+
45
+------------
46
+ URL: one of the above URL format
47
+ Push: <refspec>
48
+ Pull: <refspec>
49
50
------------
45
- URL: <url>
46
- Pull: refs/heads/master:<remote>
51
52
+`Push:` lines are used by `git-push` and
53
+`Pull:` lines are used by `git-pull` and `git-fetch`.
54
+Multiple `Push:` and `Pull:` lines may
55
+be specified for additional branch mappings.
56
+
57
+Named file in `$GIT_DIR/branches`
58
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
+
60
+You can choose to provide the name of a
61
+file in `$GIT_DIR/branches`.
62
+The URL in this file will be used to access the repository.
63
+This file should have the following format:
64
+
65
+
66
+------------
67
+ <url>#<head>
68
------------
69
50
-while having `<url>#<head>` is equivalent to
70
+`<url>` is required; `#<head>` is optional.
71
+When you do not provide a refspec on the command line,
72
+git will use the following refspec, where `<head>` defaults to `master`,
73
+and `<repository>` is the name of this file
74
+you provided in the command line.
75
76
------------
53
- URL: <url>
54
- Pull: refs/heads/<head>:<remote>
77
+ refs/heads/<head>:<repository>
78
------------
79
+
80
+
81
+
82
+