{"thread":{"id":"15441","subject":"[PATCH] refs: improve comments about \"reading\" argument of \"resolve_ref\"","startedAt":"2008-09-09T05:10:56Z","lastAt":"2008-09-09T05:10:56Z","messageCount":1,"participants":["Christian Couder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"90166","messageId":"20080909071056.2521c510.chriscool@tuxfamily.org","threadId":"15441","inReplyTo":null,"subject":"[PATCH] refs: improve comments about \"reading\" argument of \"resolve_ref\"","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2008-09-09T05:10:56Z","receivedAt":"2008-09-09T05:10:56Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"From: Junio C Hamano <gitster@pobox.com>\n\nSigned-off-by: Christian Couder <chriscool@tuxfamily.org>\n---\n refs.c |   30 ++++++++++++++++++++++++------\n 1 files changed, 24 insertions(+), 6 deletions(-)\n\n\tJunio wrote:\n\t> So how about improving the comment that is misleading?\n\n\tOk, let's do that. On top of your patch, I added a comment based\n\ton your previous email as a function header. Feel free to discard\n\tit or move it to \"cache.h\".\n\n\tThanks,\n\tChristian. \n\ndiff --git a/refs.c b/refs.c\nindex 39a3b23..d61893b 100644\n--- a/refs.c\n+++ b/refs.c\n@@ -390,6 +390,21 @@ int resolve_gitlink_ref(const char *path, const char *refname, unsigned char *re\n \treturn retval;\n }\n \n+/*\n+ * resolve_ref: find what a ref points at\n+ *\n+ * If the \"reading\" argument is set, this function finds out what _object_\n+ * the ref points at. This is called \"reading\" the ref, and the ref, if it\n+ * is not symbolic, has to exist, and if it is symbolic, it has to point at\n+ * an existing ref, because the \"read\" goes through the symref to the ref\n+ * it points at.\n+ *\n+ * Otherwise, the access that is not \"reading\" does not have to be \"writing\";\n+ * it can be merely checking _where it leads to_. If it is a prelude to\n+ * \"writing\" to the ref, a write to a symref that points at yet-to-be-born\n+ * ref will create the real ref pointed by the symref, so such a symref is\n+ * not an error.\n+ */\n const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *flag)\n {\n \tint depth = MAXDEPTH;\n@@ -409,12 +424,15 @@ const char *resolve_ref(const char *ref, unsigned char *sha1, int reading, int *\n \t\tif (--depth < 0)\n \t\t\treturn NULL;\n \n-\t\t/* Special case: non-existing file.\n-\t\t * Not having the refs/heads/new-branch is OK\n-\t\t * if we are writing into it, so is .git/HEAD\n-\t\t * that points at refs/heads/master still to be\n-\t\t * born.  It is NOT OK if we are resolving for\n-\t\t * reading.\n+\t\t/*\n+\t\t * Special case: non-existing file.\n+\t\t * Not having the refs/heads/new-branch is not OK if\n+\t\t * we are resolving for reading.  But not everybody\n+\t\t * calls this function to learn what object the ref\n+\t\t * points at.  E.g. it can be called to learn what the\n+\t\t * symref points at.  Also if we are writing into it,\n+\t\t * it is Ok for .git/HEAD to point at refs/heads/master\n+\t\t * that does not exist yet.\n \t\t */\n \t\tif (lstat(path, &st) < 0) {\n \t\t\tstruct ref_list *list = get_packed_refs();\n-- \n1.6.0.1.338.g5e95.dirty\n"}]}