@matheusbsbs / matheus-bagliano / commits / df8baa42fe
Fork 0

[PATCH] Random documentation fixes

The fixes focuses on improving the HTML output. Most noteworthy: - Fix the Makefile to also make various *.html files depend on included files. - Consistently use 'NOTE: ...' instead of '[ ... ]' for additional info. - Fix ending '::' for description lists in OPTION section etc. - Fix paragraphs in description lists ending up as preformated text. - Always use listingblocks (preformatted text wrapped in lines with -----) for examples that span empty lines, so they are put in only one HTML block. - Use '1.' instead of '(1)' for numbered lists. - Fix linking to other GIT docs. - git-rev-list.txt: put option descriptions in an OPTION section. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>

Jonas Fonseca committed Oct 3, 2005 at 19:16 UTC df8baa42fe4eeb5a021ac262caf601f44d2a5746
26 files changed +209 -192
Documentation/Makefile
+3
@@ -53,6 +53,9 @@ install: man
53 $(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
54 diff-format.txt diff-options.txt
55 $(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
56 +$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
57 + diff-format.txt diff-options.txt
58 +$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt
59 git.7: ../README
60
61 clean:
Documentation/cvs-migration.txt
+4 -4
@@ -229,10 +229,10 @@ does rename or copy would not show in the output, and if the
229 "o-file.c", it would find the commit that changed the statement
230 when it was in "o-file.c".
231
232 -[ BTW, the current versions of "git-diff-tree -C" is not eager
232 +NOTE: The current versions of "git-diff-tree -C" is not eager
233 enough to find copies, and it will miss the fact that a-file.c
234 was created by copying o-file.c unless o-file.c was somehow
235 - changed in the same commit.]
235 + changed in the same commit.
236
237 You can use the --pickaxe-all flag in addition to the -S flag.
238 This causes the differences from all the files contained in
@@ -243,6 +243,6 @@ that contain this changed "if" statement:
243 nitfol();
244 }' --pickaxe-all
245
246 -[ Side note. This option is called "--pickaxe-all" because -S
246 +NOTE: This option is called "--pickaxe-all" because -S
247 option is internally called "pickaxe", a tool for software
248 - archaeologists.]
248 + archaeologists.
Documentation/diffcore.txt
+6 -6
@@ -254,11 +254,11 @@ As an example, typical orderfile for the core GIT probably
254 would look like this:
255
256 ------------------------------------------------
257 - README
258 - Makefile
259 - Documentation
260 - *.h
261 - *.c
262 - t
257 +README
258 +Makefile
259 +Documentation
260 +*.h
261 +*.c
262 +t
263 ------------------------------------------------
264
Documentation/git-applypatch.txt
+1 -1
@@ -30,7 +30,7 @@ OPTIONS
30 <patch>::
31 The patch to apply.
32
33 -<info>:
33 +<info>::
34 Author and subject information extracted from e-mail,
35 used on "author" line and as the first line of the
36 commit log message.
Documentation/git-bisect.txt
+1 -1
@@ -91,7 +91,7 @@ Author
91 Written by Linus Torvalds <torvalds@osdl.org>
92
93 Documentation
94 ---------------
94 +-------------
95 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
96
97 GIT
Documentation/git-cherry-pick.txt
+3 -3
@@ -38,9 +38,9 @@ OPTIONS
38 option is used, your working tree does not have to match
39 the HEAD commit. The cherry-pick is done against the
40 beginning state of your working tree.
41 -
42 - This is useful when cherry-picking more than one commits'
43 - effect to your working tree in a row.
41 ++
42 +This is useful when cherry-picking more than one commits'
43 +effect to your working tree in a row.
44
45
46 Author
Documentation/git-commit-tree.txt
+3 -3
@@ -58,11 +58,11 @@ following environment variables.
58 GIT_COMMITTER_NAME
59 GIT_COMMITTER_EMAIL
60
61 -(nb <,> and '\n's are stripped)
61 +(nb "<", ">" and "\n"s are stripped)
62
63 A commit comment is read from stdin (max 999 chars). If a changelog
64 -entry is not provided via '<' redirection, "git-commit-tree" will just wait
65 -for one to be entered and terminated with ^D
64 +entry is not provided via "<" redirection, "git-commit-tree" will just wait
65 +for one to be entered and terminated with ^D.
66
67 Diagnostics
68 -----------
Documentation/git-cvsimport.txt
+5 -5
@@ -51,15 +51,15 @@ OPTIONS
51 The 'HEAD' branch from CVS is imported to the 'origin' branch within
52 the git repository, as 'HEAD' already has a special meaning for git.
53 Use this option if you want to import into a different branch.
54 -
55 - Use '-o master' for continuing an import that was initially done by
56 - the old cvs2git tool.
54 ++
55 +Use '-o master' for continuing an import that was initially done by
56 +the old cvs2git tool.
57
58 -p <options-for-cvsps>::
59 Additional options for cvsps.
60 The options '-u' and '-A' are implicit and should not be used here.
61 -
62 - If you need to pass multiple options, separate them with a comma.
61 ++
62 +If you need to pass multiple options, separate them with a comma.
63
64 -m::
65 Attempt to detect merges based on the commit message. This option
Documentation/git-diff-index.txt
+4 -4
@@ -86,8 +86,8 @@ the more useful of the two in that what it does can't be emulated with
86 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
87 The non-cached version asks the question:
88
89 - show me the differences between HEAD and the currently checked out
90 - tree - index contents _and_ files that aren't up-to-date
89 + show me the differences between HEAD and the currently checked out
90 + tree - index contents _and_ files that aren't up-to-date
91
92 which is obviously a very useful question too, since that tells you what
93 you *could* commit. Again, the output matches the "git-diff-tree -r"
@@ -107,13 +107,13 @@ not up-to-date and may contain new stuff. The all-zero sha1 means that to
107 get the real diff, you need to look at the object in the working directory
108 directly rather than do an object-to-object diff.
109
110 -NOTE! As with other commands of this type, "git-diff-index" does not
110 +NOTE: As with other commands of this type, "git-diff-index" does not
111 actually look at the contents of the file at all. So maybe
112 `kernel/sched.c` hasn't actually changed, and it's just that you
113 touched it. In either case, it's a note that you need to
114 "git-upate-cache" it to make the cache be in sync.
115
116 -NOTE 2! You can have a mixture of files show up as "has been updated"
116 +NOTE: You can have a mixture of files show up as "has been updated"
117 and "is still dirty in the working directory" together. You can always
118 tell which file is in which state, since the "has been updated" ones
119 show a valid sha1, and the "not in sync with the index" ones will
Documentation/git-diff-tree.txt
+12 -10
@@ -101,16 +101,18 @@ An example of normal usage is:
101 which tells you that the last commit changed just one file (it's from
102 this one:
103
104 - commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
105 - tree 5319e4d609cdd282069cc4dce33c1db559539b03
106 - parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
107 - author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
108 - committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
109 -
110 - Make "git-fsck-objects" print out all the root commits it finds.
111 -
112 - Once I do the reference tracking, I'll also make it print out all the
113 - HEAD commits it finds, which is even more interesting.
104 +-----------------------------------------------------------------------------
105 +commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
106 +tree 5319e4d609cdd282069cc4dce33c1db559539b03
107 +parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
108 +author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
109 +committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
110 +
111 +Make "git-fsck-objects" print out all the root commits it finds.
112 +
113 +Once I do the reference tracking, I'll also make it print out all the
114 +HEAD commits it finds, which is even more interesting.
115 +-----------------------------------------------------------------------------
116
117 in case you care).
118
Documentation/git-fetch.txt
+1 -1
@@ -39,7 +39,7 @@ Written by Linus Torvalds <torvalds@osdl.org> and
39 Junio C Hamano <junkio@cox.net>
40
41 Documentation
42 ---------------
42 +-------------
43 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
44
45 GIT
Documentation/git-fsck-objects.txt
+4 -4
@@ -19,9 +19,9 @@ OPTIONS
19 -------
20 <object>::
21 An object to treat as the head of an unreachability trace.
22 -
23 - If no objects are given, git-fsck-objects defaults to using the
24 - index file and all SHA1 references in .git/refs/* as heads.
22 ++
23 +If no objects are given, git-fsck-objects defaults to using the
24 +index file and all SHA1 references in .git/refs/* as heads.
25
26 --unreachable::
27 Print out objects that exist but that aren't readable from any
@@ -128,7 +128,7 @@ GIT_OBJECT_DIRECTORY::
128 GIT_INDEX_FILE::
129 used to specify the index file of the cache
130
131 -GIT_ALTERNATE_OBJECT_DIRECTORIES:
131 +GIT_ALTERNATE_OBJECT_DIRECTORIES::
132 used to specify additional object database roots (usually unset)
133
134 Author
Documentation/git-ls-files.txt
+11 -9
@@ -70,11 +70,11 @@ OPTIONS
70 -t::
71 Identify the file status with the following tags (followed by
72 a space) at the start of each line:
73 - H cached
74 - M unmerged
75 - R removed/deleted
76 - C modifed/changed
77 - K to be killed
73 + H:: cached
74 + M:: unmerged
75 + R:: removed/deleted
76 + C:: modifed/changed
77 + K:: to be killed
78 ? other
79
80 --::
@@ -110,13 +110,13 @@ flags --others or --ignored are specified.
110
111 These exclude patterns come from these places:
112
113 - (1) command line flag --exclude=<pattern> specifies a single
113 + 1. command line flag --exclude=<pattern> specifies a single
114 pattern.
115
116 - (2) command line flag --exclude-from=<file> specifies a list of
116 + 2. command line flag --exclude-from=<file> specifies a list of
117 patterns stored in a file.
118
119 - (3) command line flag --exclude-per-directory=<name> specifies
119 + 3. command line flag --exclude-per-directory=<name> specifies
120 a name of the file in each directory 'git-ls-files'
121 examines, and if exists, its contents are used as an
122 additional list of patterns.
@@ -168,12 +168,13 @@ An exclude pattern is of the following format:
168 - otherwise, it is a shell glob pattern, suitable for
169 consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
170 slash in the pattern must match a slash in the pathname.
171 - "Documentation/*.html" matches "Documentation/git.html" but
171 + "Documentation/\*.html" matches "Documentation/git.html" but
172 not "ppc/ppc.html". As a natural exception, "/*.c" matches
173 "cat-file.c" but not "mozilla-sha1/sha1.c".
174
175 An example:
176
177 +--------------------------------------------------------------
178 $ cat .git/ignore
179 # ignore objects and archives, anywhere in the tree.
180 *.[oa]
@@ -186,6 +187,7 @@ An example:
187 --exclude='Documentation/*.[0-9]' \
188 --exclude-from=.git/ignore \
189 --exclude-per-directory=.gitignore
190 +--------------------------------------------------------------
191
192
193 See Also
Documentation/git-pack-objects.txt
+2 -1
@@ -76,7 +76,8 @@ Documentation by Junio C Hamano
76
77 See-Also
78 --------
79 -git-repack(1) git-prune-packed(1)
79 +gitlink:git-repack[1]
80 +gitlink:git-prune-packed[1]
81
82 GIT
83 ---
Documentation/git-prune-packed.txt
+2 -1
@@ -34,7 +34,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
34
35 See-Also
36 --------
37 -git-pack-objects(1) git-repack(1)
37 +gitlink:git-pack-objects[1]
38 +gitlink:git-repack[1]
39
40 GIT
41 ---
Documentation/git-read-tree.txt
+2 -2
@@ -84,10 +84,10 @@ fast forward situation).
84 When two trees are specified, the user is telling git-read-tree
85 the following:
86
87 - (1) The current index and work tree is derived from $H, but
87 + 1. The current index and work tree is derived from $H, but
88 the user may have local changes in them since $H;
89
90 - (2) The user wants to fast-forward to $M.
90 + 2. The user wants to fast-forward to $M.
91
92 In this case, the "git-read-tree -m $H $M" command makes sure
93 that no local change is lost as the result of this "merge".
Documentation/git-repack.txt
+2 -1
@@ -51,7 +51,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
51
52 See-Also
53 --------
54 -git-pack-objects(1) git-prune-packed(1)
54 +gitlink:git-pack-objects[1]
55 +gitlink:git-prune-packed[1]
56
57 GIT
58 ---
Documentation/git-rev-list.txt
+38 -34
@@ -22,65 +22,69 @@ that point. Their parents are implied. "git-rev-list foo bar ^baz" thus
22 means "list all the commits which are included in 'foo' and 'bar', but
23 not in 'baz'".
24
25 -If *--pretty* is specified, print the contents of the commit changesets
26 -in human-readable form.
27 -
28 -The *--objects* flag causes 'git-rev-list' to print the object IDs of
29 -any object referenced by the listed commits. 'git-rev-list --objects foo
30 -^bar' thus means "send me all object IDs which I need to download if
31 -I have the commit object 'bar', but not 'foo'".
32 -
33 -The *--bisect* flag limits output to the one commit object which is
34 -roughly halfway between the included and excluded commits. Thus,
35 -if 'git-rev-list --bisect foo ^bar
36 -^baz' outputs 'midpoint', the output
37 -of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
38 -^bar
39 -^baz'
40 -would be of roughly the same length. Finding the change which introduces
41 -a regression is thus reduced to a binary search: repeatedly generate and
42 -test new 'midpoint's until the commit chain is of length one.
43 -
44 -If *--merge-order* is specified, the commit history is decomposed into a
45 -unique sequence of minimal, non-linear epochs and maximal, linear epochs.
46 -Non-linear epochs are then linearised by sorting them into merge order, which
47 -is described below.
48 -
25 +OPTIONS
26 +-------
27 +--pretty::
28 + Print the contents of the commit changesets in human-readable form.
29 +
30 +--objects::
31 + Print the object IDs of any object referenced by the listed commits.
32 + 'git-rev-list --objects foo ^bar' thus means "send me all object IDs
33 + which I need to download if I have the commit object 'bar', but
34 + not 'foo'".
35 +
36 +--bisect::
37 + Limit output to the one commit object which is roughly halfway
38 + between the included and excluded commits. Thus, if 'git-rev-list
39 + --bisect foo ^bar ^baz' outputs 'midpoint', the output
40 + of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
41 + ^bar ^baz' would be of roughly the same length. Finding the change
42 + which introduces a regression is thus reduced to a binary search:
43 + repeatedly generate and test new 'midpoint's until the commit chain
44 + is of length one.
45 +
46 +--merge-order::
47 + When specified the commit history is decomposed into a unique
48 + sequence of minimal, non-linear epochs and maximal, linear epochs.
49 + Non-linear epochs are then linearised by sorting them into merge
50 + order, which is described below.
51 ++
52 Maximal, linear epochs correspond to periods of sequential development.
53 Minimal, non-linear epochs correspond to periods of divergent development
54 followed by a converging merge. The theory of epochs is described in more
55 detail at
56 link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].
54 -
57 ++
58 The merge order for a non-linear epoch is defined as a linearisation for which
59 the following invariants are true:
57 -
60 ++
61 1. if a commit P is reachable from commit N, commit P sorts after commit N
62 in the linearised list.
63 2. if Pi and Pj are any two parents of a merge M (with i < j), then any
64 commit N, such that N is reachable from Pj but not reachable from Pi,
65 sorts before all commits reachable from Pi.
63 -
66 ++
67 Invariant 1 states that later commits appear before earlier commits they are
68 derived from.
66 -
69 ++
70 Invariant 2 states that commits unique to "later" parents in a merge, appear
71 before all commits from "earlier" parents of a merge.
72
70 -If *--show-breaks* is specified, each item of the list is output with a
71 -2-character prefix consisting of one of: (|), (^), (=) followed by a space.
72 -
73 +--show-breaks::
74 + Each item of the list is output with a 2-character prefix consisting
75 + of one of: (|), (^), (=) followed by a space.
76 ++
77 Commits marked with (=) represent the boundaries of minimal, non-linear epochs
78 and correspond either to the start of a period of divergent development or to
79 the end of such a period.
76 -
80 ++
81 Commits marked with (|) are direct parents of commits immediately preceding
82 the marked commit in the list.
79 -
83 ++
84 Commits marked with (^) are not parents of the immediately preceding commit.
85 These "breaks" represent necessary discontinuities implied by trying to
86 represent an arbtirary DAG in a linear form.
83 -
87 ++
88 *--show-breaks* is only valid if *--merge-order* is also specified.
89
90 Author
Documentation/git-revert.txt
+3 -3
@@ -29,9 +29,9 @@ OPTIONS
29 working tree does not have to match the HEAD commit.
30 The revert is done against the beginning state of your
31 working tree.
32 -
33 - This is useful when reverting more than one commits'
34 - effect to your working tree in a row.
32 ++
33 +This is useful when reverting more than one commits'
34 +effect to your working tree in a row.
35
36
37 Author
Documentation/git-send-email.txt
+9 -7
@@ -21,35 +21,37 @@ The header of the email is configurable by command line options. If not
21 specified on the command line, the user will be prompted with a ReadLine
22 enabled interface to provide the necessary information.
23
24 +OPTIONS
25 +-------
26 The options available are:
27
26 - --to
28 +--to::
29 Specify the primary recipient of the emails generated.
30 Generally, this will be the upstream maintainer of the
31 project involved.
32
31 - --from
33 +--from::
34 Specify the sender of the emails. This will default to
35 the value GIT_COMMITTER_IDENT, as returned by "git-var -l".
36 The user will still be prompted to confirm this entry.
37
36 - --compose
38 +--compose::
39 Use \$EDITOR to edit an introductory message for the
40 patch series.
41
40 - --subject
42 +--subject::
43 Specify the initial subject of the email thread.
44 Only necessary if --compose is also set. If --compose
45 is not set, this will be prompted for.
46
45 - --in-reply-to
47 +--in-reply-to::
48 Specify the contents of the first In-Reply-To header.
49 Subsequent emails will refer to the previous email
50 instead of this if --chain-reply-to is set (the default)
51 Only necessary if --compose is also set. If --compose
52 is not set, this will be prompted for.
53
52 - --chain-reply-to, --no-chain-reply-to
54 +--chain-reply-to, --no-chain-reply-to::
55 If this is set, each email will be sent as a reply to the previous
56 email sent. If disabled with "--no-chain-reply-to", all emails after
57 the first will be sent as replies to the first email sent. When using
@@ -57,7 +59,7 @@ The options available are:
59 entire patch series.
60 Default is --chain-reply-to
61
60 - --smtp-server
62 +--smtp-server::
63 If set, specifies the outgoing SMTP server to use. Defaults to
64 localhost.
65
Documentation/git-send-pack.txt
+4 -4
@@ -61,9 +61,9 @@ this flag.
61 Without '--all' and without any '<ref>', the refs that exist
62 both on the local side and on the remote side are updated.
63
64 -When '<ref>'s are specified explicitly, it can be either a
64 +When one or more '<ref>' are specified explicitly, it can be either a
65 single pattern, or a pair of such pattern separated by a colon
66 -':' (this means that a ref name cannot have a colon in it). A
66 +":" (this means that a ref name cannot have a colon in it). A
67 single pattern '<name>' is just a shorthand for '<name>:<name>'.
68
69 Each pattern pair consists of the source side (before the colon)
@@ -79,10 +79,10 @@ destination side.
79
80 - If <dst> does not match any remote ref, either
81
82 - - it has to start with "refs/"; <dst> is used as the
82 + * it has to start with "refs/"; <dst> is used as the
83 destination literally in this case.
84
85 - - <src> == <dst> and the ref that matched the <src> must not
85 + * <src> == <dst> and the ref that matched the <src> must not
86 exist in the set of remote refs; the ref matched <src>
87 locally is used as the name of the destination.
88
Documentation/git-sh-setup.txt
+5 -4
@@ -14,11 +14,12 @@ DESCRIPTION
14
15 Sets up the normal git environment variables and a few helper functions
16 (currently just "die()"), and returns ok if it all looks like a git archive.
17 -So use it something like
17 +So, to make the rest of the git scripts more careful and readable,
18 +use it as follows:
19
19 - . git-sh-setup || die "Not a git archive"
20 -
21 -to make the rest of the git scripts more careful and readable.
20 +-------------------------------------------------
21 +. git-sh-setup || die "Not a git archive"
22 +-------------------------------------------------
23
24 Author
25 ------
Documentation/git-update-index.txt
+1 -1
@@ -101,7 +101,7 @@ Using --cacheinfo or --info-only
101 current working directory. This is useful for minimum-checkout
102 merging.
103
104 - To pretend you have a file with mode and sha1 at path, say:
104 +To pretend you have a file with mode and sha1 at path, say:
105
106 $ git-update-index --cacheinfo mode sha1 path
107
Documentation/git-var.txt
+8 -6
@@ -15,21 +15,23 @@ DESCRIPTION
15 -----------
16 Prints a git logical variable.
17
18 --l causes the logical variables to be listed.
18 +OPTIONS
19 +-------
20 +-l::
21 + Cause the logical variables to be listed.
22
23 EXAMPLE
24 --------
22 -$git-var GIT_AUTHOR_IDENT
23 -
24 -Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600
25 + $ git-var GIT_AUTHOR_IDENT
26 + Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600
27
28
29 VARIABLES
30 ----------
29 -GIT_AUTHOR_IDENT
31 +GIT_AUTHOR_IDENT::
32 The author of a piece of code.
33
32 -GIT_COMMITTER_IDENT
34 +GIT_COMMITTER_IDENT::
35 The person who put a piece of code into git.
36
37 Diagnostics
Documentation/git-verify-pack.txt
+9 -5
@@ -25,15 +25,19 @@ OPTIONS
25
26 -v::
27 After verifying the pack, show list of objects contained
28 - in the pack. The format used is:
28 + in the pack.
29
30 - SHA1 type size offset-in-packfile
30 +OUTPUT FORMAT
31 +-------------
32 +When specifying the -v option the format used is:
33
32 - for objects that are not deltified in the pack, and
34 + SHA1 type size offset-in-packfile
35
34 - SHA1 type size offset-in-packfile depth base-SHA1
36 +for objects that are not deltified in the pack, and
37
36 - for objects that are deltified.
38 + SHA1 type size offset-in-packfile depth base-SHA1
39 +
40 +for objects that are deltified.
41
42 Author
43 ------
Documentation/pull-fetch-param.txt
+66 -72
@@ -2,84 +2,78 @@
2 The "remote" repository to pull from. One of the
3 following notations can be used to name the repository
4 to pull from:
5 -
6 - Rsync URL
7 - rsync://remote.machine/path/to/repo.git/
8 -
9 - HTTP(s) URL
10 - http://remote.machine/path/to/repo.git/
11 -
12 - GIT URL
13 - git://remote.machine/path/to/repo.git/
14 - remote.machine:/path/to/repo.git/
15 -
16 - Local directory
17 - /path/to/repo.git/
18 -
19 - In addition to the above, as a short-hand, the name of a
20 - file in $GIT_DIR/remotes directory can be given; the
21 - named file should be in the following format:
22 -
23 - URL: one of the above URL format
24 - Push: <refspec>...
25 - Pull: <refspec>...
26 -
27 - When such a short-hand is specified in place of
28 - <repository> without <refspec> parameters on the command
29 - line, <refspec>... specified on Push lines or Pull lines
30 - are used for "git push" and "git fetch/pull",
31 - respectively.
32 -
33 - The name of a file in $GIT_DIR/branches directory can be
34 - specified as an older notation short-hand; the named
35 - file should contain a single line, a URL in one of the
36 - above formats, optionally followed by a hash '#' and the
37 - name of remote head (URL fragment notation).
38 - $GIT_DIR/branches/<remote> file that stores a <url>
39 - without the fragment is equivalent to have this in the
40 - corresponding file in the $GIT_DIR/remotes/ directory
41 -
42 - URL: <url>
43 - Pull: refs/heads/master:<remote>
44 -
45 - while having <url>#<head> is equivalent to
46 -
47 - URL: <url>
48 - Pull: refs/heads/<head>:<remote>
5 ++
6 +===============================================================
7 +- Rsync URL: rsync://remote.machine/path/to/repo.git/
8 +- HTTP(s) URL: http://remote.machine/path/to/repo.git/
9 +- GIT URL: git://remote.machine/path/to/repo.git/
10 + or remote.machine:/path/to/repo.git/
11 +- Local directory: /path/to/repo.git/
12 +===============================================================
13 ++
14 +In addition to the above, as a short-hand, the name of a
15 +file in $GIT_DIR/remotes directory can be given; the
16 +named file should be in the following format:
17 ++
18 + URL: one of the above URL format
19 + Push: <refspec>...
20 + Pull: <refspec>...
21 ++
22 +When such a short-hand is specified in place of
23 +<repository> without <refspec> parameters on the command
24 +line, <refspec>... specified on Push lines or Pull lines
25 +are used for "git push" and "git fetch/pull",
26 +respectively.
27 ++
28 +The name of a file in $GIT_DIR/branches directory can be
29 +specified as an older notation short-hand; the named
30 +file should contain a single line, a URL in one of the
31 +above formats, optionally followed by a hash '#' and the
32 +name of remote head (URL fragment notation).
33 +$GIT_DIR/branches/<remote> file that stores a <url>
34 +without the fragment is equivalent to have this in the
35 +corresponding file in the $GIT_DIR/remotes/ directory
36 ++
37 + URL: <url>
38 + Pull: refs/heads/master:<remote>
39 ++
40 +while having <url>#<head> is equivalent to
41 ++
42 + URL: <url>
43 + Pull: refs/heads/<head>:<remote>
44
45 <refspec>::
46 The canonical format of a <refspec> parameter is
47 '+?<src>:<dst>'; that is, an optional plus '+', followed
48 by the source ref, followed by a colon ':', followed by
49 the destination ref.
55 -
56 - When used in "git push", the <src> side can be an
57 - arbitrary "SHA1 expression" that can be used as an
58 - argument to "git-cat-file -t". E.g. "master~4" (push
59 - four parents before the current master head).
60 -
61 - For "git push", the local ref that matches <src> is used
62 - to fast forward the remote ref that matches <dst>. If
63 - the optional plus '+' is used, the remote ref is updated
64 - even if it does not result in a fast forward update.
65 -
66 - For "git fetch/pull", the remote ref that matches <src>
67 - is fetched, and if <dst> is not empty string, the local
68 - ref that matches it is fast forwarded using <src>.
69 - Again, if the optional plus '+' is used, the local ref
70 - is updated even if it does not result in a fast forward
71 - update.
72 -
73 - Some short-cut notations are also supported.
74 -
75 - * For backward compatibility, "tag" is almost ignored;
76 - it just makes the following parameter <tag> to mean a
77 - refspec "refs/tags/<tag>:refs/tags/<tag>".
78 -
79 - * A parameter <ref> without a colon is equivalent to
80 - <ref>: when pulling/fetching, and <ref>:<ref> when
81 - pushing. That is, do not store it locally if
82 - fetching, and update the same name if pushing.
50 ++
51 +When used in "git push", the <src> side can be an
52 +arbitrary "SHA1 expression" that can be used as an
53 +argument to "git-cat-file -t". E.g. "master~4" (push
54 +four parents before the current master head).
55 ++
56 +For "git push", the local ref that matches <src> is used
57 +to fast forward the remote ref that matches <dst>. If
58 +the optional plus '+' is used, the remote ref is updated
59 +even if it does not result in a fast forward update.
60 ++
61 +For "git fetch/pull", the remote ref that matches <src>
62 +is fetched, and if <dst> is not empty string, the local
63 +ref that matches it is fast forwarded using <src>.
64 +Again, if the optional plus '+' is used, the local ref
65 +is updated even if it does not result in a fast forward
66 +update.
67 ++
68 +Some short-cut notations are also supported.
69 ++
70 +* For backward compatibility, "tag" is almost ignored;
71 + it just makes the following parameter <tag> to mean a
72 + refspec "refs/tags/<tag>:refs/tags/<tag>".
73 +* A parameter <ref> without a colon is equivalent to
74 + <ref>: when pulling/fetching, and <ref>:<ref> when
75 + pushing. That is, do not store it locally if
76 + fetching, and update the same name if pushing.
77
78 -a, \--append::
79 Append ref names and object names of fetched refs to the