Browse Source

Cleanup and correct resolve Javadoc

We didn't fully cover what we support and what we don't.  It was
also a bit hard to follow the syntaxes supported.  Clean that up
by documenting it.

Change-Id: I7b96fa6cbefcc2364a51f336712ad361ae42df2d
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
stable-0.9
Shawn O. Pearce 14 years ago
parent
commit
3a972f8664
  1. 40
      org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java

40
org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java

@ -374,20 +374,34 @@ public abstract class Repository {
/**
* Parse a git revision string and return an object id.
*
* Currently supported is combinations of these.
* Combinations of these operators are supported:
* <ul>
* <li>SHA-1 - a SHA-1</li>
* <li>refs/... - a ref name</li>
* <li>ref^n - nth parent reference</li>
* <li>ref~n - distance via parent reference</li>
* <li>ref@{n} - nth version of ref</li>
* <li>ref^{tree} - tree references by ref</li>
* <li>ref^{commit} - commit references by ref</li>
* <li><b>HEAD</b>, <b>MERGE_HEAD</b>, <b>FETCH_HEAD</b></li>
* <li><b>SHA-1</b>: a complete or abbreviated SHA-1</li>
* <li><b>refs/...</b>: a complete reference name</li>
* <li><b>short-name</b>: a short reference name under {@code refs/heads},
* {@code refs/tags}, or {@code refs/remotes} namespace</li>
* <li><b>tag-NN-gABBREV</b>: output from describe, parsed by treating
* {@code ABBREV} as an abbreviated SHA-1.</li>
* <li><i>id</i><b>^</b>: first parent of commit <i>id</i>, this is the same
* as {@code id^1}</li>
* <li><i>id</i><b>^0</b>: ensure <i>id</i> is a commit</li>
* <li><i>id</i><b>^n</b>: n-th parent of commit <i>id</i></li>
* <li><i>id</i><b>~n</b>: n-th historical ancestor of <i>id</i>, by first
* parent. {@code id~3} is equivalent to {@code id^1^1^1} or {@code id^^^}.</li>
* <li><i>id</i><b>:path</b>: Lookup path under tree named by <i>id</i></li>
* <li><i>id</i><b>^{commit}</b>: ensure <i>id</i> is a commit</li>
* <li><i>id</i><b>^{tree}</b>: ensure <i>id</i> is a tree</li>
* <li><i>id</i><b>^{tag}</b>: ensure <i>id</i> is a tag</li>
* <li><i>id</i><b>^{blob}</b>: ensure <i>id</i> is a blob</li>
* </ul>
*
* Not supported is:
* <p>
* The following operators are specified by Git conventions, but are not
* supported by this method:
* <ul>
* <li>timestamps in reflogs, ref@{full or relative timestamp}</li>
* <li><b>ref@{n}</b>: n-th version of ref as given by its reflog</li>
* <li><b>ref@{time}</b>: value of ref at the designated time</li>
* </ul>
*
* @param revstr
@ -397,6 +411,12 @@ public abstract class Repository {
* {@code revstr} contains an abbreviated ObjectId and this
* repository contains more than one object which match to the
* input abbreviation.
* @throws IncorrectObjectTypeException
* the id parsed does not meet the type required to finish
* applying the operators in the expression.
* @throws RevisionSyntaxException
* the expression is not supported by this implementation, or
* does not meet the standard syntax.
* @throws IOException
* on serious errors
*/

Loading…
Cancel
Save