Documentation: split off rev doc into include file
Currently, the documentation for revisions and ranges sits in the git-rev-parse man page, i.e. a plumbing man page, along with the documentation of all rev-parse modes. Split off the revisions and ranges section into an included file to prepare for restructuring. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael J Gruber committed
Jul 5, 2010 at 18:11 UTC
5a8f311789b98cf812343f0ef854561b02144b1a
2 files changed
+200
-199
Documentation/git-rev-parse.txt
+1
-199
@@ -174,205 +174,7 @@ shown. If the pattern does not contain a globbing character (`?`,
174
Flags and parameters to be parsed.
175
176
177
-SPECIFYING REVISIONS
178
---------------------
179
-
180
-A revision parameter typically, but not necessarily, names a
181
-commit object. They use what is called an 'extended SHA1'
182
-syntax. Here are various ways to spell object names. The
183
-ones listed near the end of this list are to name trees and
184
-blobs contained in a commit.
185
-
186
-* The full SHA1 object name (40-byte hexadecimal string), or
187
- a substring of such that is unique within the repository.
188
- E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
189
- name the same commit object if there are no other object in
190
- your repository whose object name starts with dae86e.
191
-
192
-* An output from 'git describe'; i.e. a closest tag, optionally
193
- followed by a dash and a number of commits, followed by a dash, a
194
- `g`, and an abbreviated object name.
195
-
196
-* A symbolic ref name. E.g. 'master' typically means the commit
197
- object referenced by refs/heads/master. If you
198
- happen to have both heads/master and tags/master, you can
199
- explicitly say 'heads/master' to tell git which one you mean.
200
- When ambiguous, a `<name>` is disambiguated by taking the
201
- first match in the following rules:
202
-
203
- . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
204
- useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
205
-
206
- . otherwise, `refs/<name>` if exists;
207
-
208
- . otherwise, `refs/tags/<name>` if exists;
209
-
210
- . otherwise, `refs/heads/<name>` if exists;
211
-
212
- . otherwise, `refs/remotes/<name>` if exists;
213
-
214
- . otherwise, `refs/remotes/<name>/HEAD` if exists.
215
-+
216
-HEAD names the commit your changes in the working tree is based on.
217
-FETCH_HEAD records the branch you fetched from a remote repository
218
-with your last 'git fetch' invocation.
219
-ORIG_HEAD is created by commands that moves your HEAD in a drastic
220
-way, to record the position of the HEAD before their operation, so that
221
-you can change the tip of the branch back to the state before you ran
222
-them easily.
223
-MERGE_HEAD records the commit(s) you are merging into your branch
224
-when you run 'git merge'.
225
-+
226
-Note that any of the `refs/*` cases above may come either from
227
-the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
228
-
229
-* A ref followed by the suffix '@' with a date specification
230
- enclosed in a brace
231
- pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
232
- second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
233
- of the ref at a prior point in time. This suffix may only be
234
- used immediately following a ref name and the ref must have an
235
- existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
236
- of your *local* ref at a given time; e.g., what was in your local
237
- `master` branch last week. If you want to look at commits made during
238
- certain times, see `--since` and `--until`.
239
-
240
-* A ref followed by the suffix '@' with an ordinal specification
241
- enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
242
- the n-th prior value of that ref. For example 'master@\{1\}'
243
- is the immediate prior value of 'master' while 'master@\{5\}'
244
- is the 5th prior value of 'master'. This suffix may only be used
245
- immediately following a ref name and the ref must have an existing
246
- log ($GIT_DIR/logs/<ref>).
247
-
248
-* You can use the '@' construct with an empty ref part to get at a
249
- reflog of the current branch. For example, if you are on the
250
- branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
251
-
252
-* The special construct '@\{-<n>\}' means the <n>th branch checked out
253
- before the current one.
254
-
255
-* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to
256
- the branch the ref is set to build on top of. Missing ref defaults
257
- to the current branch.
258
-
259
-* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of
260
- that commit object. '{caret}<n>' means the <n>th parent (i.e.
261
- 'rev{caret}'
262
- is equivalent to 'rev{caret}1'). As a special rule,
263
- 'rev{caret}0' means the commit itself and is used when 'rev' is the
264
- object name of a tag object that refers to a commit object.
265
-
266
-* A suffix '{tilde}<n>' to a revision parameter means the commit
267
- object that is the <n>th generation grand-parent of the named
268
- commit object, following only the first parent. I.e. rev~3 is
269
- equivalent to rev{caret}{caret}{caret} which is equivalent to
270
- rev{caret}1{caret}1{caret}1. See below for a illustration of
271
- the usage of this form.
272
-
273
-* A suffix '{caret}' followed by an object type name enclosed in
274
- brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
275
- could be a tag, and dereference the tag recursively until an
276
- object of that type is found or the object cannot be
277
- dereferenced anymore (in which case, barf). `rev{caret}0`
278
- introduced earlier is a short-hand for `rev{caret}\{commit\}`.
279
-
280
-* A suffix '{caret}' followed by an empty brace pair
281
- (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
282
- and dereference the tag recursively until a non-tag object is
283
- found.
284
-
285
-* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names
286
- a commit whose commit message starts with the specified text.
287
- This name returns the youngest matching commit which is
288
- reachable from any ref. If the commit message starts with a
289
- '!', you have to repeat that; the special sequence ':/!',
290
- followed by something else than '!' is reserved for now.
291
-
292
-* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree
293
- at the given path in the tree-ish object named by the part
294
- before the colon.
295
- ':path' (with an empty part before the colon, e.g. `:README`)
296
- is a special case of the syntax described next: content
297
- recorded in the index at the given path.
298
-
299
-* A colon, optionally followed by a stage number (0 to 3) and a
300
- colon, followed by a path (e.g. `:0:README`); this names a blob object in the
301
- index at the given path. Missing stage number (and the colon
302
- that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage
303
- 1 is the common ancestor, stage 2 is the target branch's version
304
- (typically the current branch), and stage 3 is the version from
305
- the branch being merged.
306
-
307
-Here is an illustration, by Jon Loeliger. Both commit nodes B
308
-and C are parents of commit node A. Parent commits are ordered
309
-left-to-right.
310
-
311
-........................................
312
-G H I J
313
- \ / \ /
314
- D E F
315
- \ | / \
316
- \ | / |
317
- \|/ |
318
- B C
319
- \ /
320
- \ /
321
- A
322
-........................................
323
-
324
- A = = A^0
325
- B = A^ = A^1 = A~1
326
- C = A^2 = A^2
327
- D = A^^ = A^1^1 = A~2
328
- E = B^2 = A^^2
329
- F = B^3 = A^^3
330
- G = A^^^ = A^1^1^1 = A~3
331
- H = D^2 = B^^2 = A^^^2 = A~2^2
332
- I = F^ = B^3^ = A^^3^
333
- J = F^2 = B^3^2 = A^^3^2
334
-
335
-
336
-SPECIFYING RANGES
337
------------------
338
-
339
-History traversing commands such as 'git log' operate on a set
340
-of commits, not just a single commit. To these commands,
341
-specifying a single revision with the notation described in the
342
-previous section means the set of commits reachable from that
343
-commit, following the commit ancestry chain.
344
-
345
-To exclude commits reachable from a commit, a prefix `{caret}`
346
-notation is used. E.g. `{caret}r1 r2` means commits reachable
347
-from `r2` but exclude the ones reachable from `r1`.
348
-
349
-This set operation appears so often that there is a shorthand
350
-for it. When you have two commits `r1` and `r2` (named according
351
-to the syntax explained in SPECIFYING REVISIONS above), you can ask
352
-for commits that are reachable from r2 excluding those that are reachable
353
-from r1 by `{caret}r1 r2` and it can be written as `r1..r2`.
354
-
355
-A similar notation `r1\...r2` is called symmetric difference
356
-of `r1` and `r2` and is defined as
357
-`r1 r2 --not $(git merge-base --all r1 r2)`.
358
-It is the set of commits that are reachable from either one of
359
-`r1` or `r2` but not from both.
360
-
361
-Two other shorthands for naming a set that is formed by a commit
362
-and its parent commits exist. The `r1{caret}@` notation means all
363
-parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
364
-all of its parents.
365
-
366
-Here are a handful of examples:
367
-
368
- D G H D
369
- D F G H I J D F
370
- ^G D H D
371
- ^D B E I J F B
372
- B...C G H D E B C
373
- ^D B C E I J F B C
374
- C^@ I J F
375
- F^! D G H D F
177
+include::revisions.txt[]
178
179
PARSEOPT
180
--------
Documentation/revisions.txt
new
+199
@@ -0,0 +1,199 @@
1
+SPECIFYING REVISIONS
2
+--------------------
3
+
4
+A revision parameter typically, but not necessarily, names a
5
+commit object. They use what is called an 'extended SHA1'
6
+syntax. Here are various ways to spell object names. The
7
+ones listed near the end of this list are to name trees and
8
+blobs contained in a commit.
9
+
10
+* The full SHA1 object name (40-byte hexadecimal string), or
11
+ a substring of such that is unique within the repository.
12
+ E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
13
+ name the same commit object if there are no other object in
14
+ your repository whose object name starts with dae86e.
15
+
16
+* An output from 'git describe'; i.e. a closest tag, optionally
17
+ followed by a dash and a number of commits, followed by a dash, a
18
+ `g`, and an abbreviated object name.
19
+
20
+* A symbolic ref name. E.g. 'master' typically means the commit
21
+ object referenced by refs/heads/master. If you
22
+ happen to have both heads/master and tags/master, you can
23
+ explicitly say 'heads/master' to tell git which one you mean.
24
+ When ambiguous, a `<name>` is disambiguated by taking the
25
+ first match in the following rules:
26
+
27
+ . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
28
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
29
+
30
+ . otherwise, `refs/<name>` if exists;
31
+
32
+ . otherwise, `refs/tags/<name>` if exists;
33
+
34
+ . otherwise, `refs/heads/<name>` if exists;
35
+
36
+ . otherwise, `refs/remotes/<name>` if exists;
37
+
38
+ . otherwise, `refs/remotes/<name>/HEAD` if exists.
39
++
40
+HEAD names the commit your changes in the working tree is based on.
41
+FETCH_HEAD records the branch you fetched from a remote repository
42
+with your last 'git fetch' invocation.
43
+ORIG_HEAD is created by commands that moves your HEAD in a drastic
44
+way, to record the position of the HEAD before their operation, so that
45
+you can change the tip of the branch back to the state before you ran
46
+them easily.
47
+MERGE_HEAD records the commit(s) you are merging into your branch
48
+when you run 'git merge'.
49
++
50
+Note that any of the `refs/*` cases above may come either from
51
+the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
52
+
53
+* A ref followed by the suffix '@' with a date specification
54
+ enclosed in a brace
55
+ pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
56
+ second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
57
+ of the ref at a prior point in time. This suffix may only be
58
+ used immediately following a ref name and the ref must have an
59
+ existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
60
+ of your *local* ref at a given time; e.g., what was in your local
61
+ `master` branch last week. If you want to look at commits made during
62
+ certain times, see `--since` and `--until`.
63
+
64
+* A ref followed by the suffix '@' with an ordinal specification
65
+ enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
66
+ the n-th prior value of that ref. For example 'master@\{1\}'
67
+ is the immediate prior value of 'master' while 'master@\{5\}'
68
+ is the 5th prior value of 'master'. This suffix may only be used
69
+ immediately following a ref name and the ref must have an existing
70
+ log ($GIT_DIR/logs/<ref>).
71
+
72
+* You can use the '@' construct with an empty ref part to get at a
73
+ reflog of the current branch. For example, if you are on the
74
+ branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
75
+
76
+* The special construct '@\{-<n>\}' means the <n>th branch checked out
77
+ before the current one.
78
+
79
+* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to
80
+ the branch the ref is set to build on top of. Missing ref defaults
81
+ to the current branch.
82
+
83
+* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of
84
+ that commit object. '{caret}<n>' means the <n>th parent (i.e.
85
+ 'rev{caret}'
86
+ is equivalent to 'rev{caret}1'). As a special rule,
87
+ 'rev{caret}0' means the commit itself and is used when 'rev' is the
88
+ object name of a tag object that refers to a commit object.
89
+
90
+* A suffix '{tilde}<n>' to a revision parameter means the commit
91
+ object that is the <n>th generation grand-parent of the named
92
+ commit object, following only the first parent. I.e. rev~3 is
93
+ equivalent to rev{caret}{caret}{caret} which is equivalent to
94
+ rev{caret}1{caret}1{caret}1. See below for a illustration of
95
+ the usage of this form.
96
+
97
+* A suffix '{caret}' followed by an object type name enclosed in
98
+ brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
99
+ could be a tag, and dereference the tag recursively until an
100
+ object of that type is found or the object cannot be
101
+ dereferenced anymore (in which case, barf). `rev{caret}0`
102
+ introduced earlier is a short-hand for `rev{caret}\{commit\}`.
103
+
104
+* A suffix '{caret}' followed by an empty brace pair
105
+ (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
106
+ and dereference the tag recursively until a non-tag object is
107
+ found.
108
+
109
+* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names
110
+ a commit whose commit message starts with the specified text.
111
+ This name returns the youngest matching commit which is
112
+ reachable from any ref. If the commit message starts with a
113
+ '!', you have to repeat that; the special sequence ':/!',
114
+ followed by something else than '!' is reserved for now.
115
+
116
+* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree
117
+ at the given path in the tree-ish object named by the part
118
+ before the colon.
119
+ ':path' (with an empty part before the colon, e.g. `:README`)
120
+ is a special case of the syntax described next: content
121
+ recorded in the index at the given path.
122
+
123
+* A colon, optionally followed by a stage number (0 to 3) and a
124
+ colon, followed by a path (e.g. `:0:README`); this names a blob object in the
125
+ index at the given path. Missing stage number (and the colon
126
+ that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage
127
+ 1 is the common ancestor, stage 2 is the target branch's version
128
+ (typically the current branch), and stage 3 is the version from
129
+ the branch being merged.
130
+
131
+Here is an illustration, by Jon Loeliger. Both commit nodes B
132
+and C are parents of commit node A. Parent commits are ordered
133
+left-to-right.
134
+
135
+........................................
136
+G H I J
137
+ \ / \ /
138
+ D E F
139
+ \ | / \
140
+ \ | / |
141
+ \|/ |
142
+ B C
143
+ \ /
144
+ \ /
145
+ A
146
+........................................
147
+
148
+ A = = A^0
149
+ B = A^ = A^1 = A~1
150
+ C = A^2 = A^2
151
+ D = A^^ = A^1^1 = A~2
152
+ E = B^2 = A^^2
153
+ F = B^3 = A^^3
154
+ G = A^^^ = A^1^1^1 = A~3
155
+ H = D^2 = B^^2 = A^^^2 = A~2^2
156
+ I = F^ = B^3^ = A^^3^
157
+ J = F^2 = B^3^2 = A^^3^2
158
+
159
+
160
+SPECIFYING RANGES
161
+-----------------
162
+
163
+History traversing commands such as 'git log' operate on a set
164
+of commits, not just a single commit. To these commands,
165
+specifying a single revision with the notation described in the
166
+previous section means the set of commits reachable from that
167
+commit, following the commit ancestry chain.
168
+
169
+To exclude commits reachable from a commit, a prefix `{caret}`
170
+notation is used. E.g. `{caret}r1 r2` means commits reachable
171
+from `r2` but exclude the ones reachable from `r1`.
172
+
173
+This set operation appears so often that there is a shorthand
174
+for it. When you have two commits `r1` and `r2` (named according
175
+to the syntax explained in SPECIFYING REVISIONS above), you can ask
176
+for commits that are reachable from r2 excluding those that are reachable
177
+from r1 by `{caret}r1 r2` and it can be written as `r1..r2`.
178
+
179
+A similar notation `r1\...r2` is called symmetric difference
180
+of `r1` and `r2` and is defined as
181
+`r1 r2 --not $(git merge-base --all r1 r2)`.
182
+It is the set of commits that are reachable from either one of
183
+`r1` or `r2` but not from both.
184
+
185
+Two other shorthands for naming a set that is formed by a commit
186
+and its parent commits exist. The `r1{caret}@` notation means all
187
+parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
188
+all of its parents.
189
+
190
+Here are a handful of examples:
191
+
192
+ D G H D
193
+ D F G H I J D F
194
+ ^G D H D
195
+ ^D B E I J F B
196
+ B...C G H D E B C
197
+ ^D B C E I J F B C
198
+ C^@ I J F
199
+ F^! D G H D F