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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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.

Suggested-by: Junio C Hamano <gitster@xxxxxxxxx>
Signed-off-by: Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx>
---
This is on top of the ":path" patch to git-rev-parse.txt.

I chose not to rewrap the paragraphs so that the diff is clearer,
especially with --color-words.
I don't know what the best patch workflow guideline is here. Maybe
rewrapping a v2?

 Documentation/git-rev-parse.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index d525e57..da5cdf4 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^") means the first parent of
   that commit object.  '{caret}<n>' means the <n>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.
-- 
1.7.1.621.g01d76

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]