From 3f3abe3c5aa94a37bb57365262a9ad451c422e36 Mon Sep 17 00:00:00 2001 From: Michael J Gruber Date: Sun, 27 Jun 2010 15:15:22 +0200 Subject: [PATCH 1/2] git-rev-parse.txt: Document ":path" specifier The empty treeish in ":path" means "index". This is actually a special case of the ":stage:path" syntax where it is documented, but mentioning it also together with "treeish:path" is helpful, so do it. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 8db600f6ba..d525e577b8 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -291,7 +291,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. * A suffix ':' followed by a path; this names the blob or tree at the given path in the tree-ish object named by the part - before the colon. + before the colon. ":path" (with an empty part before the colon) + is a special case of the syntax described next: content + recorded in the index at the given path. * A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path; this names a blob object in the From b8a6610d84202d1451362cb3e7f4e2da17ed1a39 Mon Sep 17 00:00:00 2001 From: Michael J Gruber Date: Mon, 28 Jun 2010 21:01:07 +0200 Subject: [PATCH 2/2] 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 Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index d525e577b8..833a2a29cc 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. the branch the ref is set to build on top of. Missing ref defaults to the current branch. -* A suffix '{caret}' to a revision parameter means the first parent of +* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of that commit object. '{caret}' means the th parent (i.e. 'rev{caret}' 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. and dereference the tag recursively until a non-tag object is found. -* A colon, followed by a slash, followed by a text: this names +* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names a commit whose commit message starts with the specified text. This name returns the youngest matching commit which is reachable from any ref. If the commit message starts with a '!', you have to repeat that; the special sequence ':/!', followed by something else than '!' is reserved for now. -* A suffix ':' followed by a path; this names the blob or tree +* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree at the given path in the tree-ish object named by the part - before the colon. ":path" (with an empty part before the colon) + before the colon. + ':path' (with an empty part before the colon, e.g. `:README`) is a special case of the syntax described next: content recorded in the index at the given path. * A colon, optionally followed by a stage number (0 to 3) and a - colon, followed by a path; this names a blob object in the - index at the given path. Missing stage number (and the colon - that follows it) names a stage 0 entry. During a merge, stage + colon, followed by a path (e.g. `:0:README`); this names a blob object in the + index at the given path. Missing stage number (and the colon + that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch's version (typically the current branch), and stage 3 is the version from the branch being merged.