is_refname_available(): revamp the comments
Change the comments to a running example of running the function with refname set to "refs/foo/bar". Add some more explanation of the logic. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Michael Haggerty committed
May 11, 2015 at 17:25 UTC
49e818762aaf08791504d4de2076027e7d275844
1 file changed
+47
-22
refs.c
+47
-22
@@ -876,9 +876,9 @@ static void report_refname_conflict(struct ref_entry *entry,
876
* operation).
877
*
878
* Two reference names conflict if one of them exactly matches the
879
- * leading components of the other; e.g., "foo/bar" conflicts with
880
- * both "foo" and with "foo/bar/baz" but not with "foo/bar" or
881
- * "foo/barbados".
879
+ * leading components of the other; e.g., "refs/foo/bar" conflicts
880
+ * with both "refs/foo" and with "refs/foo/bar/baz" but not with
881
+ * "refs/foo/bar" or "refs/foo/barbados".
882
*
883
* skip must be sorted.
884
*/
@@ -891,19 +891,39 @@ static int is_refname_available(const char *refname,
891
int pos;
892
char *dirname;
893
894
+ /*
895
+ * For the sake of comments in this function, suppose that
896
+ * refname is "refs/foo/bar".
897
+ */
898
+
899
for (slash = strchr(refname, '/'); slash; slash = strchr(slash + 1, '/')) {
900
/*
896
- * We are still at a leading dir of the refname; we are
897
- * looking for a conflict with a leaf entry.
898
- *
899
- * If we find one, we still must make sure it is
900
- * not in "skip".
901
+ * We are still at a leading dir of the refname (e.g.,
902
+ * "refs/foo"; if there is a reference with that name,
903
+ * it is a conflict, *unless* it is in skip.
904
*/
905
pos = search_ref_dir(dir, refname, slash - refname);
906
if (pos >= 0) {
907
+ /*
908
+ * We found a reference whose name is a proper
909
+ * prefix of refname; e.g., "refs/foo".
910
+ */
911
struct ref_entry *entry = dir->entries[pos];
905
- if (entry_matches(entry, skip))
912
+ if (entry_matches(entry, skip)) {
913
+ /*
914
+ * The reference we just found, e.g.,
915
+ * "refs/foo", is also in skip, so it
916
+ * is not considered a conflict.
917
+ * Moreover, the fact that "refs/foo"
918
+ * exists means that there cannot be
919
+ * any references anywhere under the
920
+ * "refs/foo/" namespace (because they
921
+ * would have conflicted with
922
+ * "refs/foo"). So we can stop looking
923
+ * now and return true.
924
+ */
925
return 1;
926
+ }
927
report_refname_conflict(entry, refname);
928
return 0;
929
}
@@ -911,19 +931,29 @@ static int is_refname_available(const char *refname,
931
932
/*
933
* Otherwise, we can try to continue our search with
914
- * the next component; if we come up empty, we know
915
- * there is nothing under this whole prefix.
934
+ * the next component. So try to look up the
935
+ * directory, e.g., "refs/foo/".
936
*/
937
pos = search_ref_dir(dir, refname, slash + 1 - refname);
918
- if (pos < 0)
938
+ if (pos < 0) {
939
+ /*
940
+ * There was no directory "refs/foo/", so
941
+ * there is nothing under this whole prefix,
942
+ * and we are OK.
943
+ */
944
return 1;
945
+ }
946
947
dir = get_ref_dir(dir->entries[pos]);
948
}
949
950
/*
925
- * We are at the leaf of our refname; we want to
926
- * make sure there are no directories which match it.
951
+ * We are at the leaf of our refname (e.g., "refs/foo/bar").
952
+ * There is no point in searching for a reference with that
953
+ * name, because a refname isn't considered to conflict with
954
+ * itself. But we still need to check for references whose
955
+ * names are in the "refs/foo/bar/" namespace, because they
956
+ * *do* conflict.
957
*/
958
len = strlen(refname);
959
dirname = xmallocz(len + 1);
@@ -933,9 +963,9 @@ static int is_refname_available(const char *refname,
963
964
if (pos >= 0) {
965
/*
936
- * We found a directory named "refname". It is a
937
- * problem iff it contains any ref that is not
938
- * in "skip".
966
+ * We found a directory named "$refname/" (e.g.,
967
+ * "refs/foo/bar/"). It is a problem iff it contains
968
+ * any ref that is not in "skip".
969
*/
970
struct ref_entry *entry = dir->entries[pos];
971
struct ref_dir *dir = get_ref_dir(entry);
@@ -950,11 +980,6 @@ static int is_refname_available(const char *refname,
980
return 0;
981
}
982
953
- /*
954
- * There is no point in searching for another leaf
955
- * node which matches it; such an entry would be the
956
- * ref we are looking for, not a conflict.
957
- */
983
return 1;
984
}
985