git-rev-parse.txt: Add more examples for caret and colon

Several items in the caret, colon and friends section contain examples already. Make sure they all come with examples, and that examples come early so that they serve as a visual guide, as well. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Michael J Gruber committed Jun 28, 2010 at 21:01 UTC b8a6610d84202d1451362cb3e7f4e2da17ed1a39

1 file changed +8 -7

Documentation/git-rev-parse.txt

+8 -7

@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.

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 means the first parent of

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,

@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.

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: this names

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; this names the blob or tree

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. ":path" (with an empty part before the colon)

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

299 - colon, followed by a path; this names a blob object in the

300 - index at the given path. Missing stage number (and the colon

301 - that follows it) names a stage 0 entry. During a merge, stage

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.