refs: Partial rewrite for read-only refs

This new version of the references code is significantly faster and
hopefully easier to read.

External API stays the same. A new method `git_reference_reload()` has
been added to force updating a memory reference from disk. In-memory
references are no longer updated automagically -- this was killing us.

If a reference is deleted externally and the user doesn't reload the
memory object, nothing critical happens: any functions using that
reference should fail gracefully (e.g. deletion, renaming, and so on).

All generated references from the API are read only and must be free'd
by the user. There is no reference counting and no traces of generated
references are kept in the library.

There is no longer an internal representation for references. There is
only one reference struct `git_reference`, and symbolic/oid targets are
stored inside an union.

Packfile references are stored using an optimized struct with flex array
for reference names. This should significantly reduce the memory cost of
loading the packfile from disk.

Author: Vicent Marti

include/git2/refs.h

@@ -116,8 +116,13 @@ GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
  * Thie method iteratively peels a symbolic reference
  * until it resolves to a direct reference to an OID.
  *
+ * The peeled reference is returned in the `resolved_ref`
+ * argument, and must be freed manually once it's no longer
+ * needed.
+ *
  * If a direct reference is passed as an argument,
- * that reference is returned immediately
+ * a copy of that reference is returned. This copy must
+ * be manually freed too.
  *
  * @param resolved_ref Pointer to the peeled reference
  * @param ref The reference
@@ -170,11 +175,19 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
  * The new name will be checked for validity and may be
  * modified into a normalized form.
  *
- * The given git_reference will be updated.
+ * The given git_reference will be updated in place.
  *
  * The reference will be immediately renamed in-memory
  * and on disk.
  *
+ * If the `force` flag is not enabled, and there's already
+ * a reference with the given name, the renaming will fail.
+ *
+ * @param ref The reference to rename
+ * @param new_name The new name for the reference
+ * @param force Overwrite an existing reference
+ * @return GIT_SUCCESS or an error code
+ *
  */
 GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force);
 
@@ -186,6 +199,8 @@ GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, i
  * The reference will be immediately removed on disk and from
  * memory. The given reference pointer will no longer be valid.
  *
+ * @param ref The reference to remove
+ * @return GIT_SUCCESS or an error code
  */
 GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 
@@ -250,13 +265,33 @@ GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo,
 GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);
 
 /**
- * Check if a reference is packed
+ * Check if a reference has been loaded from a packfile
  *
- * @param ref git_reference
+ * @param ref A git reference
  * @return 0 in case it's not packed; 1 otherwise
  */
 GIT_EXTERN(int) git_reference_is_packed(git_reference *ref);
 
+/**
+ * Reload a reference from disk
+ *
+ * Reference pointers may become outdated if the Git
+ * repository is accessed simultaneously by other clients
+ * whilt the library is open.
+ *
+ * This method forces a reload of the reference from disk,
+ * to ensure that the provided information is still
+ * reliable.
+ *
+ * If the reload fails (e.g. the reference no longer exists
+ * on disk, or has become corrupted), an error code will be
+ * returned and the reference pointer will be invalidated.
+ *
+ * @param ref The reference to reload
+ * @return GIT_SUCCESS on success, or an error code
+ */
+GIT_EXTERN(int) git_reference_reload(git_reference *ref);
+
 /**
  * Free the given reference
  *