[PATCH v2 00/14] Tidying up references code

From: Michael Haggerty <mhagger@alum.mit.edu>

Patch series re-rolled against v4 of "Provide API to invalidate refs cache", with the following additional changes to address Junio's comments (thanks!):

* Tweaked the comments for git_path() and git_path_submodule().

* Several (clerical!) fixes to comments and log messages that still
  referred to "ref_list".

* Clarified log message for patch "refs: rename parameters result ->
  sha1".

* Improved comment for resolve_gitlink_ref().

I also moved patch "resolve_gitlink_ref(): improve docstring" later in the patch series to put it closer to other changes to that area of the code.

BTW, whenever I add comments to existing code, it is just an attempt to record information that I have inferred from reverse-engineering. My belief is that even a phenomenological description of the behavior of a function is usually better than nothing (which is often the status quo). But I will be delighted if somebody improves/rewrites the comments to be more insightful or simply more consistent with the terminology used elsewhere.

Original description of patch series:

This is the next installment of the reference changes that I have been working on. This batch includes a lot of tidying up in preparation for the real changes.

The last few patches have a little bit of meat on them. They start changing the innards of refs.c to work less with strings and more with objects. This work will continue in later patches with the ultimate goal of swapping the data structure used to store cached references out from under the module--changing it from a sorted array of pointers into a hierarchical tree shaped like the reference namespace tree.

Michael Haggerty (14):
  cache.h: add comments for git_path() and git_path_submodule()
  struct ref_entry: document name member
  refs: rename "refname" variables
  refs: rename parameters result -> sha1
  clear_ref_array(): rename from free_ref_array()
  is_refname_available(): remove the "quiet" argument
  parse_ref_line(): add docstring
  add_ref(): add docstring
  is_dup_ref(): extract function from sort_ref_array()
  refs: change signatures of get_packed_refs() and get_loose_refs()
  get_ref_dir(): change signature
  resolve_gitlink_ref(): improve docstring
  Pass a (ref_cache *) to the resolve_gitlink_*() helper functions
  resolve_gitlink_ref_recursive(): change to work with struct ref_cache

 cache.h |   18 +++
 refs.c  |  416 +++++++++++++++++++++++++++++++++-----------------------------
 refs.h  |   34 +++--
 3 files changed, 260 insertions(+), 208 deletions(-)