resolve_ref(): expand documentation
Record information about resolve_ref(), hard-won via reverse engineering, in a comment for future spelunkers. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Sep 15, 2011 at 23:10 UTC
7cb368421f62318f2c0f0e19a83ca34c201aebaa
2 files changed
+33
-13
cache.h
+33
-1
@@ -831,7 +831,39 @@ extern int get_sha1_hex(const char *hex, unsigned char *sha1);
831
832
extern char *sha1_to_hex(const unsigned char *sha1); /* static buffer result! */
833
extern int read_ref(const char *filename, unsigned char *sha1);
834
-extern const char *resolve_ref(const char *path, unsigned char *sha1, int, int *);
834
+
835
+/*
836
+ * Resolve a reference, recursively following symbolic refererences.
837
+ *
838
+ * Store the referred-to object's name in sha1 and return the name of
839
+ * the non-symbolic reference that ultimately pointed at it. The
840
+ * return value, if not NULL, is a pointer into either a static buffer
841
+ * or the input ref.
842
+ *
843
+ * If the reference cannot be resolved to an object, the behavior
844
+ * depends on the "reading" argument:
845
+ *
846
+ * - If reading is set, return NULL.
847
+ *
848
+ * - If reading is not set, clear sha1 and return the name of the last
849
+ * reference name in the chain, which will either be a non-symbolic
850
+ * reference or an undefined reference. If this is a prelude to
851
+ * "writing" to the ref, the return value is the name of the ref
852
+ * that will actually be created or changed.
853
+ *
854
+ * If flag is non-NULL, set the value that it points to the
855
+ * combination of REF_ISPACKED (if the reference was found among the
856
+ * packed references) and REF_ISSYMREF (if the initial reference was a
857
+ * symbolic reference).
858
+ *
859
+ * If ref is not a properly-formatted, normalized reference, return
860
+ * NULL. If more than MAXDEPTH recursive symbolic lookups are needed,
861
+ * give up and return NULL.
862
+ *
863
+ * errno is sometimes set on errors, but not always.
864
+ */
865
+extern const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *flag);
866
+
867
extern int dwim_ref(const char *str, int len, unsigned char *sha1, char **ref);
868
extern int dwim_log(const char *str, int len, unsigned char *sha1, char **ref);
869
extern int interpret_branch_name(const char *str, struct strbuf *);
refs.c
-12
@@ -482,18 +482,6 @@ static int get_packed_ref(const char *ref, unsigned char *sha1)
482
return -1;
483
}
484
485
-/*
486
- * If the "reading" argument is set, this function finds out what _object_
487
- * the ref points at by "reading" the ref. The ref, if it is not symbolic,
488
- * has to exist, and if it is symbolic, it has to point at an existing ref,
489
- * because the "read" goes through the symref to the ref it points at.
490
- *
491
- * The access that is not "reading" may often be "writing", but does not
492
- * have to; it can be merely checking _where it leads to_. If it is a
493
- * prelude to "writing" to the ref, a write to a symref that points at
494
- * yet-to-be-born ref will create the real ref pointed by the symref.
495
- * reading=0 allows the caller to check where such a symref leads to.
496
- */
485
const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *flag)
486
{
487
int depth = MAXDEPTH;