include/got_reference.h

   1 /*
   2  * Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
   3  *
   4  * Permission to use, copy, modify, and distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* A reference which points to an arbitrary object. */
  18 struct got_reference;
  19
  20 /* Well-known reference names. */
  21 #define GOT_REF_HEAD            "HEAD"
  22 #define GOT_REF_ORIG_HEAD       "ORIG_HEAD"
  23 #define GOT_REF_MERGE_HEAD      "MERGE_HEAD"
  24 #define GOT_REF_FETCH_HEAD      "FETCH_HEAD"
  25
  26 struct got_repository;
  27 struct got_object_id;
  28
  29 /* Determine whether a given reference name is valid. */
  30 int got_ref_name_is_valid(const char *);
  31
  32 /*
  33  * Attempt to open the reference with the provided name in a repository.
  34  * The caller must dispose of the reference with got_ref_close().
  35  * Optionally, the underlying reference file can be locked before it is opened
  36  * to prevent concurrent modification of the reference, in which case the file
  37  * must be unlocked with got_ref_unlock() before got_ref_close() is called.
  38  */
  39 const struct got_error *got_ref_open(struct got_reference **,
  40     struct got_repository *, const char *, int);
  41
  42 /*
  43  * Allocate a new reference for a given object ID.
  44  * The caller must dispose of it with got_ref_close().
  45  */
  46 const struct got_error *got_ref_alloc(struct got_reference **, const char *,
  47     struct got_object_id *);
  48
  49 /*
  50  * Allocate a new symbolic reference which points at a given reference.
  51  * The caller must dispose of it with got_ref_close().
  52  */
  53 const struct got_error *got_ref_alloc_symref(struct got_reference **,
  54     const char *, struct got_reference *);
  55
  56 /* Dispose of a reference. */
  57 void got_ref_close(struct got_reference *);
  58
  59 /* Get the name of the reference. */
  60 const char *got_ref_get_name(struct got_reference *);
  61
  62 /* Get the name of the reference which a symoblic reference points at. */
  63 const char *got_ref_get_symref_target(struct got_reference *);
  64
  65 /* Get the last modification timestamp of the reference. */
  66 time_t got_ref_get_mtime(struct got_reference *);
  67
  68 /*
  69  * Create a duplicate copy of a reference.
  70  * The caller must dispose of this copy with got_ref_close().
  71  */
  72 struct got_reference *got_ref_dup(struct got_reference *);
  73
  74 /* Attempt to resolve a symbolic reference to a non-symbolic one. */
  75 const struct got_error *got_ref_resolve_symbolic(struct got_reference **,
  76     struct got_repository *, struct got_reference *);
  77
  78 /* Attempt to resolve a reference (symbolic or not) to an object ID. */
  79 const struct got_error *got_ref_resolve(struct got_object_id **,
  80     struct got_repository *, struct got_reference *);
  81
  82 /*
  83  * Return a string representation of a reference.
  84  * The caller must dispose of it with free(3).
  85  */
  86 char *got_ref_to_str(struct got_reference *);
  87
  88 /* List of references. */
  89 struct got_reflist_entry {
  90         TAILQ_ENTRY(got_reflist_entry) entry;
  91         struct got_reference *ref;
  92 };
  93 TAILQ_HEAD(got_reflist_head, got_reflist_entry);
  94
  95 /* Duplicate a reference list entry. Caller must dispose of it with free(3). */
  96 const struct got_error *got_reflist_entry_dup(struct got_reflist_entry **,
  97     struct got_reflist_entry *);
  98
  99 /* A function which compares two references. Used with got_ref_list(). */
 100 typedef const struct got_error *(*got_ref_cmp_cb)(void *, int *,
 101     struct got_reference *, struct got_reference *);
 102
 103 /* An implementation of got_ref_cmp_cb which compares two references by name. */
 104 const struct got_error *got_ref_cmp_by_name(void *, int *,
 105     struct got_reference *, struct got_reference *);
 106
 107 /* An implementation of got_ref_cmp_cb which compares two tags. */
 108 const struct got_error *got_ref_cmp_tags(void *, int *,
 109     struct got_reference *, struct got_reference *);
 110
 111 /*
 112  * An implementation of got_ref_cmp_cb which compares commit timestamps.
 113  * Requires a struct got_repository * as the void * argument.
 114  */
 115 const struct got_error *got_ref_cmp_by_commit_timestamp_descending(void *,
 116     int *, struct got_reference *, struct got_reference *);
 117
 118 /*
 119  * Append all known references to a caller-provided ref list head.
 120  * Optionally limit references returned to those within a given
 121  * reference namespace. Sort the list with the provided reference comparison
 122  * function, usually got_ref_cmp_by_name().
 123  */
 124 const struct got_error *got_ref_list(struct got_reflist_head *,
 125     struct got_repository *, const char *, got_ref_cmp_cb, void *);
 126
 127 /* Free all references on a ref list. */
 128 void got_ref_list_free(struct got_reflist_head *);
 129
 130 /*
 131  * Insert a reference into a reference list.
 132  * Return a pointer to the newly allocated list entry in *newp.
 133  * If *newp is NULL and no error occured then the specified reference was
 134  * already an element of the list. If *newp is not NULL then the reference
 135  * was shallow-copied onto the list and should no longer be closed with
 136  * got_ref_close(). Instead it will be closed along with other list
 137  * elements by got_ref_list_free().
 138  */
 139 const struct got_error *
 140 got_reflist_insert(struct got_reflist_entry **newp,
 141     struct got_reflist_head *refs, struct got_reference *ref,
 142     got_ref_cmp_cb cmp_cb, void *cmp_arg);
 143
 144 /* Sort a list of references with the provided comparison callback. */
 145 const struct got_error *
 146 got_reflist_sort(struct got_reflist_head *refs, got_ref_cmp_cb cmp_cb,
 147     void *cmp_arg);
 148
 149 /* Indicate whether the provided reference is symbolic (points at another
 150  * refernce) or not (points at an object ID). */
 151 int got_ref_is_symbolic(struct got_reference *);
 152
 153 /* Change the object ID a reference points to. */
 154 const struct got_error *
 155 got_ref_change_ref(struct got_reference *, struct got_object_id *);
 156
 157 /* Change the reference name a symbolic reference points to. */
 158 const struct got_error *got_ref_change_symref(struct got_reference *,
 159     const char *);
 160
 161 /*
 162  * Change a symbolic reference into a regular reference which points to
 163  * the provided object ID.
 164  */
 165 const struct got_error *got_ref_change_symref_to_ref(struct got_reference *,
 166     struct got_object_id *);
 167
 168 /* Write a reference to its on-disk path in the repository. */
 169 const struct got_error *got_ref_write(struct got_reference *,
 170     struct got_repository *);
 171
 172 /* Delete a reference from its on-disk path in the repository. */
 173 const struct got_error *got_ref_delete(struct got_reference *,
 174     struct got_repository *);
 175
 176 /* Unlock a reference which was opened in locked state. */
 177 const struct got_error *got_ref_unlock(struct got_reference *);
 178
 179 /* Map object IDs to references. */
 180 struct got_reflist_object_id_map;
 181
 182 /*
 183  * Create and populate an object ID map for a given list of references.
 184  * Map entries will contain deep-copies of elements of the reflist.
 185  * The caller must dispose of the map with got_reflist_object_id_map_free().
 186  */
 187 const struct got_error *got_reflist_object_id_map_create(
 188     struct got_reflist_object_id_map **, struct got_reflist_head *,
 189     struct got_repository *);
 190
 191 /*
 192  * Return a list of references which correspond to a given object ID.
 193  * The returned list must be considered read-only.
 194  * The caller must _not_ call free(3) on the returned pointer!
 195  * If no references are associated with the ID, return NULL.
 196  */
 197 struct got_reflist_head *
 198 got_reflist_object_id_map_lookup(struct got_reflist_object_id_map *,
 199     struct got_object_id *);
 200
 201 /* Free the specified object ID map. */
 202 void got_reflist_object_id_map_free(struct got_reflist_object_id_map *);