Merge nulltoken's reference parsing code

All the commits have been squashed into a single one before refactoring
the final code, to keep everything tidy.

Individual commit messages are as follows:

Added repository reference looking up functionality placeholder.

Added basic reference database definition and caching infrastructure.

Removed useless constant.

Added GIT_EINVALIDREFNAME error and description. Added missing description for GIT_EBAREINDEX.

Added GIT_EREFCORRUPTED error and description.

Added GIT_ETOONESTEDSYMREF error and description.

Added resolving of direct and symbolic references.

Prepared the packed-refs parsing.

Added parsing of the packed-refs file content.

When no loose reference has been found, the full content of the packed-refs file is parsed. All of the new (i.e. not previously parsed as a loose reference) references are eagerly stored in the cached references storage.

The method packed_reference_file__parse() is in deer need of some refactoring. :-)

Extracted to a method the parsing of the peeled target of a tag.

Extracted to a method the parsing of a standard packed ref.

Fixed leaky removal of the cached references.

Ensured that a previously parsed packed reference isn't returned if a more up-to-date loose reference exists.

Enhanced documentation of git_repository_reference_lookup().

Moved some refs related constants from repository.c to refs.h.

Made parsing of a packed tag reference more robust.

Updated git_repository_reference_lookup() documentation.

Added some references to the test repository.

Added some tests covering tag references looking up.

Added some tests covering symbolic and head references looking up.

Added some tests covering packed references looking up.

3 files changed, 45 insertions, 1 deletions

diff --git a/src/git2/common.h b/src/git2/common.h
index 350429f5c..aae707cb6 100644
--- a/src/git2/common.h
+++ b/src/git2/common.h
@@ -134,7 +134,19 @@
 #define GIT_EBUSY (GIT_ERROR - 13)
 
 /** The index file is not backed up by an existing repository */
-#define GIT_EBAREINDEX (GIT_ERROR -14)
+#define GIT_EBAREINDEX (GIT_ERROR - 14)
+
+/** The name of the reference is not valid */
+#define GIT_EINVALIDREFNAME (GIT_ERROR - 15)
+
+/** The specified reference has its data corrupted */
+#define GIT_EREFCORRUPTED  (GIT_ERROR - 16)
+
+/** The specified symbolic reference is too deeply nested */
+#define GIT_ETOONESTEDSYMREF (GIT_ERROR - 17)
+
+/** The pack-refs file is either corrupted of its format is not currently supported */
+#define GIT_EPACKEDREFSCORRUPTED (GIT_ERROR - 18)
 
 /** The path is invalid */
 #define GIT_EINVALIDPATH (GIT_ERROR - 19)
diff --git a/src/git2/repository.h b/src/git2/repository.h
index 37a541f24..129d3bb5f 100644
--- a/src/git2/repository.h
+++ b/src/git2/repository.h
@@ -215,6 +215,22 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo);
  */
 GIT_EXTERN(int) git_repository_init(git_repository **repo_out, const char *path, unsigned is_bare);
 
+/**
+ * Lookup a reference by its name in the repository.
+ *
+ * The generated reference is owned by the repository and
+ * should not be freed by the user.
+ *
+ * TODO:
+ *	- Ensure the reference name is valid
+ *
+ * @param reference_out pointer to the looked-up reference
+ * @param repo the repository to look up the reference
+ * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...)
+ * @return a reference to the reference
+ */
+GIT_EXTERN(int) git_repository_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);
+	
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/src/git2/types.h b/src/git2/types.h
index cfc0cf379..389f32868 100644
--- a/src/git2/types.h
+++ b/src/git2/types.h
@@ -135,6 +135,22 @@ typedef struct git_signature {
 	git_time when; /** time when the action happened */
 } git_signature;
 
+/** In-memory representation of a reference. */
+typedef struct git_reference git_reference;
+
+/** In-memory representation of a reference to an object id. */
+typedef struct git_reference_object_id git_reference_object_id;
+
+/** In-memory representation of a reference which points at another reference. The target reference is embedded. */
+typedef struct git_reference_symbolic git_reference_symbolic;
+
+/** Basic type of any Git reference. */
+typedef enum {
+	GIT_REF_ANY = -2,		/** Reference can be any of the following */
+	GIT_REF_OBJECT_ID = 0,	/** A reference which points at an object id */
+	GIT_REF_SYMBOLIC = 1,	/** A reference which points at another reference */
+} git_rtype;
+
 /** @} */
 GIT_END_DECL