include/git2/refs.h

   1 /*
   2  * Copyright (C) 2009-2011 the libgit2 contributors
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_refs_h__
   8 #define INCLUDE_git_refs_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/refs.h
  16  * @brief Git reference management routines
  17  * @defgroup git_reference Git reference management routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Lookup a reference by its name in a repository.
  25  *
  26  * The generated reference is owned by the repository and
  27  * should not be freed by the user.
  28  *
  29  * @param reference_out pointer to the looked-up reference
  30  * @param repo the repository to look up the reference
  31  * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...)
  32  * @return GIT_SUCCESS or an error code
  33  */
  34 GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);
  35
  36 /**
  37  * Create a new symbolic reference.
  38  *
  39  * The reference will be created in the repository and written
  40  * to the disk.
  41  *
  42  * This reference is owned by the repository and shall not
  43  * be free'd by the user.
  44  *
  45  * If `force` is true and there already exists a reference
  46  * with the same name, it will be overwritten.
  47  *
  48  * @param ref_out Pointer to the newly created reference
  49  * @param repo Repository where that reference will live
  50  * @param name The name of the reference
  51  * @param target The target of the reference
  52  * @param force Overwrite existing references
  53  * @return GIT_SUCCESS or an error code
  54  */
  55 GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force);
  56
  57 /**
  58  * Create a new object id reference.
  59  *
  60  * The reference will be created in the repository and written
  61  * to the disk.
  62  *
  63  * This reference is owned by the repository and shall not
  64  * be free'd by the user.
  65  *
  66  * If `force` is true and there already exists a reference
  67  * with the same name, it will be overwritten.
  68  *
  69  * @param ref_out Pointer to the newly created reference
  70  * @param repo Repository where that reference will live
  71  * @param name The name of the reference
  72  * @param id The object id pointed to by the reference.
  73  * @param force Overwrite existing references
  74  * @return GIT_SUCCESS or an error code
  75  */
  76 GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force);
  77
  78 /**
  79  * Get the OID pointed to by a reference.
  80  *
  81  * Only available if the reference is direct (i.e. not symbolic)
  82  *
  83  * @param ref The reference
  84  * @return a pointer to the oid if available, NULL otherwise
  85  */
  86 GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);
  87
  88 /**
  89  * Get full name to the reference pointed by this reference
  90  *
  91  * Only available if the reference is symbolic
  92  *
  93  * @param ref The reference
  94  * @return a pointer to the name if available, NULL otherwise
  95  */
  96 GIT_EXTERN(const char *) git_reference_target(git_reference *ref);
  97
  98 /**
  99  * Get the type of a reference
 100  *
 101  * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)
 102  *
 103  * @param ref The reference
 104  * @return the type
 105  */
 106 GIT_EXTERN(git_rtype) git_reference_type(git_reference *ref);
 107
 108 /**
 109  * Get the full name of a reference
 110  *
 111  * @param ref The reference
 112  * @return the full name for the ref
 113  */
 114 GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
 115
 116 /**
 117  * Resolve a symbolic reference
 118  *
 119  * Thie method iteratively peels a symbolic reference
 120  * until it resolves to a direct reference to an OID.
 121  *
 122  * If a direct reference is passed as an argument,
 123  * that reference is returned immediately
 124  *
 125  * @param resolved_ref Pointer to the peeled reference
 126  * @param ref The reference
 127  * @return GIT_SUCCESS or an error code
 128  */
 129 GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref);
 130
 131 /**
 132  * Get the repository where a reference resides
 133  *
 134  * @param ref The reference
 135  * @return a pointer to the repo
 136  */
 137 GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);
 138
 139 /**
 140  * Set the symbolic target of a reference.
 141  *
 142  * The reference must be a symbolic reference, otherwise
 143  * this method will fail.
 144  *
 145  * The reference will be automatically updated in
 146  * memory and on disk.
 147  *
 148  * @param ref The reference
 149  * @param target The new target for the reference
 150  * @return GIT_SUCCESS or an error code
 151  */
 152 GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target);
 153
 154 /**
 155  * Set the OID target of a reference.
 156  *
 157  * The reference must be a direct reference, otherwise
 158  * this method will fail.
 159  *
 160  * The reference will be automatically updated in
 161  * memory and on disk.
 162  *
 163  * @param ref The reference
 164  * @param id The new target OID for the reference
 165  * @return GIT_SUCCESS or an error code
 166  */
 167 GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
 168
 169 /**
 170  * Rename an existing reference
 171  *
 172  * This method works for both direct and symbolic references.
 173  * The new name will be checked for validity and may be
 174  * modified into a normalized form.
 175  *
 176  * The refernece will be immediately renamed in-memory
 177  * and on disk.
 178  *
 179  */
 180 GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force);
 181
 182 /**
 183  * Delete an existing reference
 184  *
 185  * This method works for both direct and symbolic references.
 186  *
 187  * The reference will be immediately removed on disk and from
 188  * memory. The given reference pointer will no longer be valid.
 189  *
 190  */
 191 GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 192
 193 /**
 194  * Pack all the loose references in the repository
 195  *
 196  * This method will load into the cache all the loose
 197  * references on the repository and update the
 198  * `packed-refs` file with them.
 199  *
 200  * Once the `packed-refs` file has been written properly,
 201  * the loose references will be removed from disk.
 202  *
 203  * WARNING: calling this method may invalidate any existing
 204  * references previously loaded on the cache.
 205  *
 206  * @param repo Repository where the loose refs will be packed
 207  * @return GIT_SUCCESS or an error code
 208  */
 209 GIT_EXTERN(int) git_reference_packall(git_repository *repo);
 210
 211 /**
 212  * Fill a list with all the references that can be found
 213  * in a repository.
 214  *
 215  * The listed references may be filtered by type, or using
 216  * a bitwise OR of several types. Use the magic value
 217  * `GIT_REF_LISTALL` to obtain all references, including
 218  * packed ones.
 219  *
 220  * The string array will be filled with the names of all
 221  * references; these values are owned by the user and
 222  * should be free'd manually when no longer needed, using
 223  * `git_strarray_free`.
 224  *
 225  * @param array Pointer to a git_strarray structure where
 226  *              the reference names will be stored
 227  * @param repo Repository where to find the refs
 228  * @param list_flags Filtering flags for the reference
 229  *              listing.
 230  * @return GIT_SUCCESS or an error code
 231  */
 232 GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, unsigned int list_flags);
 233
 234
 235 /**
 236  * Perform an operation on each reference in the repository
 237  *
 238  * The processed references may be filtered by type, or using
 239  * a bitwise OR of several types. Use the magic value
 240  * `GIT_REF_LISTALL` to obtain all references, including
 241  * packed ones.
 242  *
 243  * The `callback` function will be called for each of the references
 244  * in the repository, and will receive the name of the reference and
 245  * the `payload` value passed to this method.
 246  *
 247  * @param repo Repository where to find the refs
 248  * @param list_flags Filtering flags for the reference
 249  *              listing.
 250  * @param callback Function which will be called for every listed ref
 251  * @param payload Additional data to pass to the callback
 252  * @return GIT_SUCCESS or an error code
 253  */
 254 GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);
 255
 256 /** @} */
 257 GIT_END_DECL
 258 #endif