Skip to contentSkip to conversation

Add revspec documentation for ':path', ':[0-3]:path' and git-describe

PATCH In review [email protected] 2 participants 3 messages Jun 15, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Add revspec documentation for ':path', ':[0-3]:path' and git-describe

---
 Documentation/git-rev-parse.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

As I'm not very good at English, please correct any mistake I made

Documentation/git-rev-parse.txt +9 -0
index 2f1306c..f8f4920 100644
@@ -119,11 +119,17 @@ syntax.
   name the same commit object if there are no other object in
   your repository whose object name starts with dae86e.
 
+* The result of `git-describe`
+
 * A symbolic ref name.  E.g. 'master' typically means the commit
   object referenced by $GIT_DIR/refs/heads/master.  If you
   happen to have both heads/master and tags/master, you can
   explicitly say 'heads/master' to tell git which one you mean.
 
+* A colon at the beginning, followed by path name to specify
+  a file in index. If you want to specify a file in a stage,
+  use expression ':[0-3]:<path>' instead.
+
 * A suffix '@' followed by a date specification enclosed in a brace
   pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
@@ -156,6 +162,9 @@ syntax.
   and dereference the tag recursively until a non-tag object is
   found.
 
+* A suffix ':' followed by path name to specify a specific file
+  in that commit/tag/tree.
+
 Here is an illustration, by Jon Loeliger.  Both node B and C are
 a commit parents of commit node A.  Parent commits are ordered
 left-to-right.
Signature · 1 line
1.4.3.rc2.g0503-dirty
#1 lore raw
Quoted 1 line

As I'm not very good at English, please correct any mistake I made

Thanks. I do not know about English, but I'd move things around to group them better. Most talk about committish but the colon-path are about trees and blobs.

Documentation/git-rev-parse.txt +15 -1
index 2f1306c..412bafb 100644
@@ -111,7 +111,9 @@ SPECIFYING REVISIONS
 
 A revision parameter typically, but not necessarily, names a
 commit object.  They use what is called an 'extended SHA1'
-syntax.
+syntax.  Here are various ways to spell object names.  The
+ones listed near the end of this list are to name trees and
+blobs contained in a commit.
 
 * The full SHA1 object name (40-byte hexadecimal string), or
   a substring of such that is unique within the repository.
@@ -119,6 +121,9 @@ syntax.
   name the same commit object if there are no other object in
   your repository whose object name starts with dae86e.
 
+* An output from `git-describe`; i.e. a closest tag, followed by a
+  dash, a 'g', and an abbreviated object name.
+
 * A symbolic ref name.  E.g. 'master' typically means the commit
   object referenced by $GIT_DIR/refs/heads/master.  If you
   happen to have both heads/master and tags/master, you can
@@ -156,6 +161,15 @@ syntax.
   and dereference the tag recursively until a non-tag object is
   found.
 
+* 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.
+
+* 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 an stage 0 entry.
+
 Here is an illustration, by Jon Loeliger.  Both node B and C are
 a commit parents of commit node A.  Parent commits are ordered
 left-to-right.
#2 lore raw
Quoted 5 lines · Junio C Hamano
Quoted 1 line

As I'm not very good at English, please correct any mistake I made

Thanks. I do not know about English, but I'd move things around to group them better. Most talk about committish but the colon-path are about trees and blobs.

It's ok to me.

Signature · 1 line
Duy