Repository: Introduce exactRef and findRef, deprecate getRef

The Repository class provides only one method to look up a ref by
name, getRef.  If I request refs/heads/master and that ref does not
exist, getRef will look further in the search path:

 ref/refs/heads/master
 refs/heads/refs/heads/master
 refs/remotes/refs/heads/master

This behavior is counterintuitive, needlessly inexpensive, and usually
not what the caller expects.

Allow callers to specify whether to use the search path by providing
two separate methods:

- exactRef, which looks up a ref when its exact name is known
- findRef, which looks for a ref along the search path

For backward compatibility, keep getRef as a deprecated synonym for
findRef.

This change introduces findRef and exactRef but does not update
callers outside tests to use them yet.

Change-Id: I35375d942baeb3ded15520388f8ebb9c0cc86f8c
Signed-off-by: Jonathan Nieder <jrn@google.com>

1 files changed, 35 insertions, 0 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
index c91f2dab72..49a970d03a 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
@@ -964,9 +964,44 @@ public abstract class Repository implements AutoCloseable {
 	 *            "refs/heads/master" if "refs/heads/master" already exists.
 	 * @return the Ref with the given name, or {@code null} if it does not exist
 	 * @throws IOException
+	 * @deprecated Use {@link #exactRef(String)} or {@link #findRef(String)}
+	 * instead.
 	 */
+	@Deprecated
 	@Nullable
 	public Ref getRef(final String name) throws IOException {
+		return findRef(name);
+	}
+
+	/**
+	 * Get a ref by name.
+	 *
+	 * @param name
+	 *            the name of the ref to lookup. Must not be a short-hand
+	 *            form; e.g., "master" is not automatically expanded to
+	 *            "refs/heads/master".
+	 * @return the Ref with the given name, or {@code null} if it does not exist
+	 * @throws IOException
+	 * @since 4.2
+	 */
+	@Nullable
+	public Ref exactRef(String name) throws IOException {
+		return getRefDatabase().exactRef(name);
+	}
+
+	/**
+	 * Search for a ref by (possibly abbreviated) name.
+	 *
+	 * @param name
+	 *            the name of the ref to lookup. May be a short-hand form, e.g.
+	 *            "master" which is is automatically expanded to
+	 *            "refs/heads/master" if "refs/heads/master" already exists.
+	 * @return the Ref with the given name, or {@code null} if it does not exist
+	 * @throws IOException
+	 * @since 4.2
+	 */
+	@Nullable
+	public Ref findRef(String name) throws IOException {
 		return getRefDatabase().getRef(name);
 	}