@matheusbsbs / matheus-bagliano / commits / 3598a30808
Fork 0

Docs: split up pull-fetch-param.txt

The push and pull man pages include a bunch of shared text from pull-fetch-param.txt. This simplifies maintenance somewhat, but there's actually quite a bit of text that applies only to one or the other. So, separate out the push- and pull/fetch-specific text into pull-fetch-param.txt and git-push.txt, then include the largest chunk of common stuff (the description of protocols and url's) from urls.txt. That cuts some irrelevant stuff from the man pages without making us duplicate too much. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>

J. Bruce Fields committed Feb 5, 2006 at 17:43 UTC 3598a308086d4a41cab1e941df7763f2004e53c5
3 files changed +94 -81
Documentation/git-push.txt
+26 -1
@@ -23,7 +23,32 @@ documentation for gitlink:git-receive-pack[1].
23
24 OPTIONS
25 -------
26 -include::pull-fetch-param.txt[]
26 +<repository>::
27 + The "remote" repository that is destination of a push operation.
28 +include::urls.txt[]
29 +
30 +<refspec>::
31 + The canonical format of a <refspec> parameter is
32 + `+?<src>:<dst>`; that is, an optional plus `+`, followed
33 + by the source ref, followed by a colon `:`, followed by
34 + the destination ref.
35 ++
36 +The <src> side can be an
37 +arbitrary "SHA1 expression" that can be used as an
38 +argument to `git-cat-file -t`. E.g. `master~4` (push
39 +four parents before the current master head).
40 ++
41 +The local ref that matches <src> is used
42 +to fast forward the remote ref that matches <dst>. If
43 +the optional plus `+` is used, the remote ref is updated
44 +even if it does not result in a fast forward update.
45 ++
46 +Some short-cut notations are also supported.
47 ++
48 +* `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
49 +* A parameter <ref> without a colon is equivalent to
50 + <ref>`:`<ref>, hence updates <ref> in the destination from <ref>
51 + in the source.
52
53 \--all::
54 Instead of naming each ref to push, specifies all refs
Documentation/pull-fetch-param.txt
+6 -80
@@ -1,68 +1,7 @@
1 <repository>::
2 The "remote" repository that is the source of a fetch
3 - or pull operation, or the destination of a push operation.
4 - One of the following notations can be used
5 - to name the remote repository:
6 -+
7 -===============================================================
8 -- rsync://host.xz/path/to/repo.git/
9 -- http://host.xz/path/to/repo.git/
10 -- https://host.xz/path/to/repo.git/
11 -- git://host.xz/path/to/repo.git/
12 -- git://host.xz/~user/path/to/repo.git/
13 -- ssh://host.xz/path/to/repo.git/
14 -- ssh://host.xz/~user/path/to/repo.git/
15 -- ssh://host.xz/~/path/to/repo.git
16 -===============================================================
17 -+
18 -SSH Is the default transport protocol and also supports an
19 -scp-like syntax. Both syntaxes support username expansion,
20 -as does the native git protocol. The following three are
21 -identical to the last three above, respectively:
22 -+
23 -===============================================================
24 -- host.xz:/path/to/repo.git/
25 -- host.xz:~user/path/to/repo.git/
26 -- host.xz:path/to/repo.git
27 -===============================================================
28 -+
29 -To sync with a local directory, use:
30 -+
31 -===============================================================
32 -- /path/to/repo.git/
33 -===============================================================
34 -+
35 -In addition to the above, as a short-hand, the name of a
36 -file in `$GIT_DIR/remotes` directory can be given; the
37 -named file should be in the following format:
38 -+
39 - URL: one of the above URL format
40 - Push: <refspec>
41 - Pull: <refspec>
42 -+
43 -When such a short-hand is specified in place of
44 -<repository> without <refspec> parameters on the command
45 -line, <refspec> specified on `Push:` lines or `Pull:`
46 -lines are used for `git-push` and `git-fetch`/`git-pull`,
47 -respectively. Multiple `Push:` and and `Pull:` lines may
48 -be specified for additional branch mappings.
49 -+
50 -The name of a file in `$GIT_DIR/branches` directory can be
51 -specified as an older notation short-hand; the named
52 -file should contain a single line, a URL in one of the
53 -above formats, optionally followed by a hash `#` and the
54 -name of remote head (URL fragment notation).
55 -`$GIT_DIR/branches/<remote>` file that stores a <url>
56 -without the fragment is equivalent to have this in the
57 -corresponding file in the `$GIT_DIR/remotes/` directory.
58 -+
59 - URL: <url>
60 - Pull: refs/heads/master:<remote>
61 -+
62 -while having `<url>#<head>` is equivalent to
63 -+
64 - URL: <url>
65 - Pull: refs/heads/<head>:<remote>
3 + or pull operation.
4 +include::urls.txt[]
5
6 <refspec>::
7 The canonical format of a <refspec> parameter is
@@ -70,17 +9,7 @@ while having `<url>#<head>` is equivalent to
9 by the source ref, followed by a colon `:`, followed by
10 the destination ref.
11 +
73 -When used in `git-push`, the <src> side can be an
74 -arbitrary "SHA1 expression" that can be used as an
75 -argument to `git-cat-file -t`. E.g. `master~4` (push
76 -four parents before the current master head).
77 -+
78 -For `git-push`, the local ref that matches <src> is used
79 -to fast forward the remote ref that matches <dst>. If
80 -the optional plus `+` is used, the remote ref is updated
81 -even if it does not result in a fast forward update.
82 -+
83 -For `git-fetch` and `git-pull`, the remote ref that matches <src>
12 +The remote ref that matches <src>
13 is fetched, and if <dst> is not empty string, the local
14 ref that matches it is fast forwarded using <src>.
15 Again, if the optional plus `+` is used, the local ref
@@ -135,10 +64,7 @@ is often useful.
64 Some short-cut notations are also supported.
65 +
66 * `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`;
138 - used with pull or fetch, it requests fetching everything up to
139 - the given tag.
67 + it requests fetching everything up to the given tag.
68 * A parameter <ref> without a colon is equivalent to
141 - <ref>: when pulling/fetching, and <ref>`:`<ref> when
142 - pushing. That is, do not store it locally if
143 - fetching, and update the same name if pushing.
144 -
69 + <ref>: when pulling/fetching, so it merges <ref> into the current
70 + branch without storing the remote branch anywhere locally
Documentation/urls.txt new
+62
@@ -0,0 +1,62 @@
1 +One of the following notations can be used
2 +to name the remote repository:
3 ++
4 +===============================================================
5 +- rsync://host.xz/path/to/repo.git/
6 +- http://host.xz/path/to/repo.git/
7 +- https://host.xz/path/to/repo.git/
8 +- git://host.xz/path/to/repo.git/
9 +- git://host.xz/~user/path/to/repo.git/
10 +- ssh://host.xz/path/to/repo.git/
11 +- ssh://host.xz/~user/path/to/repo.git/
12 +- ssh://host.xz/~/path/to/repo.git
13 +===============================================================
14 ++
15 +SSH Is the default transport protocol and also supports an
16 +scp-like syntax. Both syntaxes support username expansion,
17 +as does the native git protocol. The following three are
18 +identical to the last three above, respectively:
19 ++
20 +===============================================================
21 +- host.xz:/path/to/repo.git/
22 +- host.xz:~user/path/to/repo.git/
23 +- host.xz:path/to/repo.git
24 +===============================================================
25 ++
26 +To sync with a local directory, use:
27 ++
28 +===============================================================
29 +- /path/to/repo.git/
30 +===============================================================
31 ++
32 +In addition to the above, as a short-hand, the name of a
33 +file in `$GIT_DIR/remotes` directory can be given; the
34 +named file should be in the following format:
35 ++
36 + URL: one of the above URL format
37 + Push: <refspec>
38 + Pull: <refspec>
39 ++
40 +When such a short-hand is specified in place of
41 +<repository> without <refspec> parameters on the command
42 +line, <refspec> specified on `Push:` lines or `Pull:`
43 +lines are used for `git-push` and `git-fetch`/`git-pull`,
44 +respectively. Multiple `Push:` and and `Pull:` lines may
45 +be specified for additional branch mappings.
46 ++
47 +The name of a file in `$GIT_DIR/branches` directory can be
48 +specified as an older notation short-hand; the named
49 +file should contain a single line, a URL in one of the
50 +above formats, optionally followed by a hash `#` and the
51 +name of remote head (URL fragment notation).
52 +`$GIT_DIR/branches/<remote>` file that stores a <url>
53 +without the fragment is equivalent to have this in the
54 +corresponding file in the `$GIT_DIR/remotes/` directory.
55 ++
56 + URL: <url>
57 + Pull: refs/heads/master:<remote>
58 ++
59 +while having `<url>#<head>` is equivalent to
60 ++
61 + URL: <url>
62 + Pull: refs/heads/<head>:<remote>