include/git2/refs.h

   1 /*
   2  * This file is free software; you can redistribute it and/or modify
   3  * it under the terms of the GNU General Public License, version 2,
   4  * as published by the Free Software Foundation.
   5  *
   6  * In addition to the permissions in the GNU General Public License,
   7  * the authors give you unlimited permission to link the compiled
   8  * version of this file into combinations with other programs,
   9  * and to distribute those combinations without any restriction
  10  * coming from the use of this file.  (The General Public License
  11  * restrictions do apply in other respects; for example, they cover
  12  * modification of the file, and distribution when not linked into
  13  * a combined executable.)
  14  *
  15  * This file is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; see the file COPYING.  If not, write to
  22  * the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301, USA.
  24  */
  25 #ifndef INCLUDE_git_refs_h__
  26 #define INCLUDE_git_refs_h__
  27
  28 #include "common.h"
  29 #include "types.h"
  30 #include "oid.h"
  31
  32 /**
  33  * @file git2/refs.h
  34  * @brief Git reference management routines
  35  * @defgroup git_reference Git reference management routines
  36  * @ingroup Git
  37  * @{
  38  */
  39 GIT_BEGIN_DECL
  40
  41 /**
  42  * Lookup a reference by its name in a repository.
  43  *
  44  * The generated reference is owned by the repository and
  45  * should not be freed by the user.
  46  *
  47  * @param reference_out pointer to the looked-up reference
  48  * @param repo the repository to look up the reference
  49  * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...)
  50  * @return 0 on success; error code otherwise
  51  */
  52 GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);
  53
  54 /**
  55  * Create a new symbolic reference.
  56  *
  57  * The reference will be created in the repository and written
  58  * to the disk.
  59  *
  60  * This reference is owned by the repository and shall not
  61  * be free'd by the user.
  62  *
  63  * @param ref_out Pointer to the newly created reference
  64  * @param repo Repository where that reference will live
  65  * @param name The name of the reference
  66  * @param target The target of the reference
  67  * @return 0 on success; error code otherwise
  68  */
  69 GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target);
  70
  71 /**
  72  * Create a new symbolic reference, overwriting an existing one with
  73  * the same name, if it exists.
  74  *
  75  * If the new reference isn't a symbolic one, any pointers to the old
  76  * reference become invalid.
  77  *
  78  * The reference will be created in the repository and written
  79  * to the disk.
  80  *
  81  * This reference is owned by the repository and shall not
  82  * be free'd by the user.
  83  *
  84  * @param ref_out Pointer to the newly created reference
  85  * @param repo Repository where that reference will live
  86  * @param name The name of the reference
  87  * @param target The target of the reference
  88  * @return 0 on success; error code otherwise
  89  */
  90 GIT_EXTERN(int) git_reference_create_symbolic_f(git_reference **ref_out, git_repository *repo, const char *name, const char *target);
  91
  92 /**
  93  * Create a new object id reference.
  94  *
  95  * The reference will be created in the repository and written
  96  * to the disk.
  97  *
  98  * This reference is owned by the repository and shall not
  99  * be free'd by the user.
 100  *
 101  * @param ref_out Pointer to the newly created reference
 102  * @param repo Repository where that reference will live
 103  * @param name The name of the reference
 104  * @param id The object id pointed to by the reference.
 105  * @return 0 on success; error code otherwise
 106  */
 107 GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id);
 108
 109 /**
 110  * Create a new object id reference, overwriting an existing one with
 111  * the same name, if it exists.
 112  *
 113  * If the new reference isn't an object id one, any pointers to the
 114  * old reference become invalid.
 115  *
 116  * The reference will be created in the repository and written
 117  * to the disk.
 118  *
 119  * This reference is owned by the repository and shall not
 120  * be free'd by the user.
 121  *
 122  * @param ref_out Pointer to the newly created reference
 123  * @param repo Repository where that reference will live
 124  * @param name The name of the reference
 125  * @param id The object id pointed to by the reference.
 126  * @return 0 on success; error code otherwise
 127  */
 128 GIT_EXTERN(int) git_reference_create_oid_f(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id);
 129
 130 /**
 131  * Get the OID pointed to by a reference.
 132  *
 133  * Only available if the reference is direct (i.e. not symbolic)
 134  *
 135  * @param ref The reference
 136  * @return a pointer to the oid if available, NULL otherwise
 137  */
 138 GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);
 139
 140 /**
 141  * Get full name to the reference pointed by this reference
 142  *
 143  * Only available if the reference is symbolic
 144  *
 145  * @param ref The reference
 146  * @return a pointer to the name if available, NULL otherwise
 147  */
 148 GIT_EXTERN(const char *) git_reference_target(git_reference *ref);
 149
 150 /**
 151  * Get the type of a reference
 152  *
 153  * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)
 154  *
 155  * @param ref The reference
 156  * @return the type
 157  */
 158 GIT_EXTERN(git_rtype) git_reference_type(git_reference *ref);
 159
 160 /**
 161  * Get the full name of a reference
 162  *
 163  * @param ref The reference
 164  * @return the full name for the ref
 165  */
 166 GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
 167
 168 /**
 169  * Resolve a symbolic reference
 170  *
 171  * Thie method iteratively peels a symbolic reference
 172  * until it resolves to a direct reference to an OID.
 173  *
 174  * If a direct reference is passed as an argument,
 175  * that reference is returned immediately
 176  *
 177  * @param resolved_ref Pointer to the peeled reference
 178  * @param ref The reference
 179  * @return 0 on success; error code otherwise
 180  */
 181 GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref);
 182
 183 /**
 184  * Get the repository where a reference resides
 185  *
 186  * @param ref The reference
 187  * @return a pointer to the repo
 188  */
 189 GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);
 190
 191 /**
 192  * Set the symbolic target of a reference.
 193  *
 194  * The reference must be a symbolic reference, otherwise
 195  * this method will fail.
 196  *
 197  * The reference will be automatically updated in
 198  * memory and on disk.
 199  *
 200  * @param ref The reference
 201  * @param target The new target for the reference
 202  * @return 0 on success; error code otherwise
 203  */
 204 GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target);
 205
 206 /**
 207  * Set the OID target of a reference.
 208  *
 209  * The reference must be a direct reference, otherwise
 210  * this method will fail.
 211  *
 212  * The reference will be automatically updated in
 213  * memory and on disk.
 214  *
 215  * @param ref The reference
 216  * @param target The new target OID for the reference
 217  * @return 0 on success; error code otherwise
 218  */
 219 GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
 220
 221 /**
 222  * Rename an existing reference
 223  *
 224  * This method works for both direct and symbolic references.
 225  * The new name will be checked for validity and may be
 226  * modified into a normalized form.
 227  *
 228  * The refernece will be immediately renamed in-memory
 229  * and on disk.
 230  *
 231  */
 232 GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name);
 233
 234 /**
 235  * Rename an existing reference, overwriting an existing one with the
 236  * same name, if it exists.
 237  *
 238  * This method works for both direct and symbolic references.
 239  * The new name will be checked for validity and may be
 240  * modified into a normalized form.
 241  *
 242  * The refernece will be immediately renamed in-memory
 243  * and on disk.
 244  *
 245  */
 246 GIT_EXTERN(int) git_reference_rename_f(git_reference *ref, const char *new_name);
 247
 248 /**
 249  * Delete an existing reference
 250  *
 251  * This method works for both direct and symbolic references.
 252  *
 253  * The reference will be immediately removed on disk and from
 254  * memory. The given reference pointer will no longer be valid.
 255  *
 256  */
 257 GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 258
 259 /**
 260  * Pack all the loose references in the repository
 261  *
 262  * This method will load into the cache all the loose
 263  * references on the repository and update the
 264  * `packed-refs` file with them.
 265  *
 266  * Once the `packed-refs` file has been written properly,
 267  * the loose references will be removed from disk.
 268  *
 269  * WARNING: calling this method may invalidate any existing
 270  * references previously loaded on the cache.
 271  *
 272  * @param repo Repository where the loose refs will be packed
 273  * @return 0 on success; error code otherwise
 274  */
 275 GIT_EXTERN(int) git_reference_packall(git_repository *repo);
 276
 277 /**
 278  * Fill a list with all the references that can be found
 279  * in a repository.
 280  *
 281  * The listed references may be filtered by type, or using
 282  * a bitwise OR of several types. Use the magic value
 283  * `GIT_REF_LISTALL` to obtain all references, including
 284  * packed ones.
 285  *
 286  * The string array will be filled with the names of all
 287  * references; these values are owned by the user and
 288  * should be free'd manually when no longer needed, using
 289  * `git_strarray_free`.
 290  *
 291  * @param array Pointer to a git_strarray structure where
 292  *              the reference names will be stored
 293  * @param repo Repository where to find the refs
 294  * @param list_flags Filtering flags for the reference
 295  *              listing.
 296  * @return 0 on success; error code otherwise
 297  */
 298 GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, unsigned int list_flags);
 299
 300
 301 /**
 302  * Perform an operation on each reference in the repository
 303  *
 304  * The processed references may be filtered by type, or using
 305  * a bitwise OR of several types. Use the magic value
 306  * `GIT_REF_LISTALL` to obtain all references, including
 307  * packed ones.
 308  *
 309  * The `callback` function will be called for each of the references
 310  * in the repository, and will receive the name of the reference and
 311  * the `payload` value passed to this method.
 312  *
 313  * @param repo Repository where to find the refs
 314  * @param list_flags Filtering flags for the reference
 315  *              listing.
 316  * @param callback Function which will be called for every listed ref
 317  * @param payload Additional data to pass to the callback
 318  * @return 0 on success; error code otherwise
 319  */
 320 GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);
 321
 322 /** @} */
 323 GIT_END_DECL
 324 #endif