[PATCH] refs: improve comments about "reading" argument of "resolve_ref"
From: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
refs.c | 30 ++++++++++++++++++++++++------
1 files changed, 24 insertions(+), 6 deletions(-)
Junio wrote:
> So how about improving the comment that is misleading?
Ok, let's do that. On top of your patch, I added a comment based
on your previous email as a function header. Feel free to discard
it or move it to "cache.h".
Thanks,
Christian.
diff --git a/refs.c b/refs.c
index 39a3b23..d61893b 100644
--- a/refs.c
+++ b/refs.c
@@ -390,6 +390,21 @@ int resolve_gitlink_ref(const char *path, const char *refname, unsigned char *re
return retval;
}
+/*
+ * resolve_ref: find what a ref points at
+ *
+ * If the "reading" argument is set, this function finds out what _object_
+ * the ref points at. This is called "reading" the ref, and the ref, if it
+ * is not symbolic, has to exist, and if it is symbolic, it has to point at
+ * an existing ref, because the "read" goes through the symref to the ref
+ * it points at.
+ *
+ * Otherwise, the access that is not "reading" does not have to be "writing";
+ * it can be merely checking _where it leads to_. If it is a prelude to
+ * "writing" to the ref, a write to a symref that points at yet-to-be-born
+ * ref will create the real ref pointed by the symref, so such a symref is
+ * not an error.
+ */
const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *flag)
{
int depth = MAXDEPTH;
@@ -409,12 +424,15 @@ const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *
if (--depth < 0)
return NULL;
- /* Special case: non-existing file.
- * Not having the refs/heads/new-branch is OK
- * if we are writing into it, so is .git/HEAD
- * that points at refs/heads/master still to be
- * born. It is NOT OK if we are resolving for
- * reading.
+ /*
+ * Special case: non-existing file.
+ * Not having the refs/heads/new-branch is not OK if
+ * we are resolving for reading. But not everybody
+ * calls this function to learn what object the ref
+ * points at. E.g. it can be called to learn what the
+ * symref points at. Also if we are writing into it,
+ * it is Ok for .git/HEAD to point at refs/heads/master
+ * that does not exist yet.
*/
if (lstat(path, &st) < 0) {
struct ref_list *list = get_packed_refs();
--
1.6.0.1.338.g5e95.dirty
Christian Couder <chriscool@tuxfamily.org>