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 symbolic 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  * Get the modification timestamp of the commit pointed at by the
  70  * given reference. Will return zero if the commit timestamp is
  71  * unknown or if the reference does not point at a commit.
  72  *
  73  * The cached timestamp will be known after got_ref_list() was called
  74  * with either got_ref_cmp_by_commit_timestamp_descending() or
  75  * with got_ref_cmp_tags().
  76  */
  77 time_t got_ref_get_cached_committer_time(struct got_reference *);
  78
  79 /*
  80  * Create a duplicate copy of a reference.
  81  * The caller must dispose of this copy with got_ref_close().
  82  */
  83 struct got_reference *got_ref_dup(struct got_reference *);
  84
  85 /* Attempt to resolve a symbolic reference to a non-symbolic one. */
  86 const struct got_error *got_ref_resolve_symbolic(struct got_reference **,
  87     struct got_repository *, struct got_reference *);
  88
  89 /* Attempt to resolve a reference (symbolic or not) to an object ID. */
  90 const struct got_error *got_ref_resolve(struct got_object_id **,
  91     struct got_repository *, struct got_reference *);
  92
  93 /*
  94  * Return a string representation of a reference.
  95  * The caller must dispose of it with free(3).
  96  */
  97 char *got_ref_to_str(struct got_reference *);
  98
  99 /* List of references. */
 100 struct got_reflist_entry {
 101         TAILQ_ENTRY(got_reflist_entry) entry;
 102         struct got_reference *ref;
 103 };
 104 TAILQ_HEAD(got_reflist_head, got_reflist_entry);
 105
 106 /* Duplicate a reference list entry. Caller must dispose of it with free(3). */
 107 const struct got_error *got_reflist_entry_dup(struct got_reflist_entry **,
 108     struct got_reflist_entry *);
 109
 110 /* A function which compares two references. Used with got_ref_list(). */
 111 typedef const struct got_error *(*got_ref_cmp_cb)(void *, int *,
 112     struct got_reference *, struct got_reference *);
 113
 114 /* An implementation of got_ref_cmp_cb which compares two references by name. */
 115 const struct got_error *got_ref_cmp_by_name(void *, int *,
 116     struct got_reference *, struct got_reference *);
 117
 118 /* An implementation of got_ref_cmp_cb which compares two tags. */
 119 const struct got_error *got_ref_cmp_tags(void *, int *,
 120     struct got_reference *, struct got_reference *);
 121
 122 /*
 123  * An implementation of got_ref_cmp_cb which compares commit timestamps.
 124  * Requires a struct got_repository * as the void * argument.
 125  */
 126 const struct got_error *got_ref_cmp_by_commit_timestamp_descending(void *,
 127     int *, struct got_reference *, struct got_reference *);
 128
 129 /*
 130  * Append all known references to a caller-provided ref list head.
 131  * Optionally limit references returned to those within a given
 132  * reference namespace. Sort the list with the provided reference comparison
 133  * function, usually got_ref_cmp_by_name().
 134  */
 135 const struct got_error *got_ref_list(struct got_reflist_head *,
 136     struct got_repository *, const char *, got_ref_cmp_cb, void *);
 137
 138 /* Free all references on a ref list. */
 139 void got_ref_list_free(struct got_reflist_head *);
 140
 141 /*
 142  * Insert a reference into a reference list.
 143  * Return a pointer to the newly allocated list entry in *newp.
 144  * If *newp is NULL and no error occurred then the specified reference was
 145  * already an element of the list. If *newp is not NULL then the reference
 146  * was shallow-copied onto the list and should no longer be closed with
 147  * got_ref_close(). Instead it will be closed along with other list
 148  * elements by got_ref_list_free().
 149  */
 150 const struct got_error *
 151 got_reflist_insert(struct got_reflist_entry **newp,
 152     struct got_reflist_head *refs, struct got_reference *ref,
 153     got_ref_cmp_cb cmp_cb, void *cmp_arg);
 154
 155 /* Sort a list of references with the provided comparison callback. */
 156 const struct got_error *
 157 got_reflist_sort(struct got_reflist_head *refs, got_ref_cmp_cb cmp_cb,
 158     void *cmp_arg);
 159
 160 /* Indicate whether the provided reference is symbolic (points at another
 161  * reference) or not (points at an object ID). */
 162 int got_ref_is_symbolic(struct got_reference *);
 163
 164 /* Change the object ID a reference points to. */
 165 const struct got_error *
 166 got_ref_change_ref(struct got_reference *, struct got_object_id *);
 167
 168 /* Change the reference name a symbolic reference points to. */
 169 const struct got_error *got_ref_change_symref(struct got_reference *,
 170     const char *);
 171
 172 /*
 173  * Change a symbolic reference into a regular reference which points to
 174  * the provided object ID.
 175  */
 176 const struct got_error *got_ref_change_symref_to_ref(struct got_reference *,
 177     struct got_object_id *);
 178
 179 /* Write a reference to its on-disk path in the repository. */
 180 const struct got_error *got_ref_write(struct got_reference *,
 181     struct got_repository *);
 182
 183 /* Delete a reference from its on-disk path in the repository. */
 184 const struct got_error *got_ref_delete(struct got_reference *,
 185     struct got_repository *);
 186
 187 /* Unlock a reference which was opened in locked state. */
 188 const struct got_error *got_ref_unlock(struct got_reference *);
 189
 190 /* Map object IDs to references. */
 191 struct got_reflist_object_id_map;
 192
 193 /*
 194  * Create and populate an object ID map for a given list of references.
 195  * Map entries will contain deep-copies of elements of the reflist.
 196  * The caller must dispose of the map with got_reflist_object_id_map_free().
 197  */
 198 const struct got_error *got_reflist_object_id_map_create(
 199     struct got_reflist_object_id_map **, struct got_reflist_head *,
 200     struct got_repository *);
 201
 202 /*
 203  * Return a list of references which correspond to a given object ID.
 204  * The returned list must be considered read-only.
 205  * The caller must _not_ call free(3) on the returned pointer!
 206  * If no references are associated with the ID, return NULL.
 207  */
 208 struct got_reflist_head *
 209 got_reflist_object_id_map_lookup(struct got_reflist_object_id_map *,
 210     struct got_object_id *);
 211
 212 /* Free the specified object ID map. */
 213 void got_reflist_object_id_map_free(struct got_reflist_object_id_map *);