include/git2/refs.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   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 #include "strarray.h"
  14
  15 /**
  16  * @file git2/refs.h
  17  * @brief Git reference management routines
  18  * @defgroup git_reference Git reference management routines
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * Lookup a reference by name in a repository.
  26  *
  27  * The returned reference must be freed by the user.
  28  *
  29  * The name will be checked for validity.
  30  * See `git_reference_symbolic_create()` for rules about valid names.
  31  *
  32  * @param out pointer to the looked-up reference
  33  * @param repo the repository to look up the reference
  34  * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
  35  * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
  36  */
  37 GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name);
  38
  39 /**
  40  * Lookup a reference by name and resolve immediately to OID.
  41  *
  42  * This function provides a quick way to resolve a reference name straight
  43  * through to the object id that it refers to.  This avoids having to
  44  * allocate or free any `git_reference` objects for simple situations.
  45  *
  46  * The name will be checked for validity.
  47  * See `git_reference_symbolic_create()` for rules about valid names.
  48  *
  49  * @param out Pointer to oid to be filled in
  50  * @param repo The repository in which to look up the reference
  51  * @param name The long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
  52  * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
  53  */
  54 GIT_EXTERN(int) git_reference_name_to_id(
  55         git_oid *out, git_repository *repo, const char *name);
  56
  57 /**
  58  * Lookup a reference by DWIMing its short name
  59  *
  60  * Apply the git precedence rules to the given shorthand to determine
  61  * which reference the user is referring to.
  62  *
  63  * @param out pointer in which to store the reference
  64  * @param repo the repository in which to look
  65  * @param shorthand the short name for the reference
  66  * @return 0 or an error code
  67  */
  68 GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand);
  69
  70 /**
  71  * Conditionally create a new symbolic reference.
  72  *
  73  * A symbolic reference is a reference name that refers to another
  74  * reference name.  If the other name moves, the symbolic name will move,
  75  * too.  As a simple example, the "HEAD" reference might refer to
  76  * "refs/heads/master" while on the "master" branch of a repository.
  77  *
  78  * The symbolic reference will be created in the repository and written to
  79  * the disk.  The generated reference object must be freed by the user.
  80  *
  81  * Valid reference names must follow one of two patterns:
  82  *
  83  * 1. Top-level names must contain only capital letters and underscores,
  84  *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
  85  * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
  86  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
  87  *    sequences ".." and "@{" which have special meaning to revparse.
  88  *
  89  * This function will return an error if a reference already exists with the
  90  * given name unless `force` is true, in which case it will be overwritten.
  91  *
  92  * The message for the reflog will be ignored if the reference does
  93  * not belong in the standard set (HEAD, branches and remote-tracking
  94  * branches) and it does not have a reflog.
  95  *
  96  * It will return GIT_EMODIFIED if the reference's value at the time
  97  * of updating does not match the one passed through `current_value`
  98  * (i.e. if the ref has changed since the user read it).
  99  *
 100  * If `current_value` is all zeros, this function will return GIT_EMODIFIED
 101  * if the ref already exists.
 102  *
 103  * @param out Pointer to the newly created reference
 104  * @param repo Repository where that reference will live
 105  * @param name The name of the reference
 106  * @param target The target of the reference
 107  * @param force Overwrite existing references
 108  * @param current_value The expected value of the reference when updating
 109  * @param log_message The one line long message to be appended to the reflog
 110  * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code
 111  */
 112 GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message);
 113
 114 /**
 115  * Create a new symbolic reference.
 116  *
 117  * A symbolic reference is a reference name that refers to another
 118  * reference name.  If the other name moves, the symbolic name will move,
 119  * too.  As a simple example, the "HEAD" reference might refer to
 120  * "refs/heads/master" while on the "master" branch of a repository.
 121  *
 122  * The symbolic reference will be created in the repository and written to
 123  * the disk.  The generated reference object must be freed by the user.
 124  *
 125  * Valid reference names must follow one of two patterns:
 126  *
 127  * 1. Top-level names must contain only capital letters and underscores,
 128  *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
 129  * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
 130  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
 131  *    sequences ".." and "@{" which have special meaning to revparse.
 132  *
 133  * This function will return an error if a reference already exists with the
 134  * given name unless `force` is true, in which case it will be overwritten.
 135  *
 136  * The message for the reflog will be ignored if the reference does
 137  * not belong in the standard set (HEAD, branches and remote-tracking
 138  * branches) and it does not have a reflog.
 139  *
 140  * @param out Pointer to the newly created reference
 141  * @param repo Repository where that reference will live
 142  * @param name The name of the reference
 143  * @param target The target of the reference
 144  * @param force Overwrite existing references
 145  * @param log_message The one line long message to be appended to the reflog
 146  * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
 147  */
 148 GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message);
 149
 150 /**
 151  * Create a new direct reference.
 152  *
 153  * A direct reference (also called an object id reference) refers directly
 154  * to a specific object id (a.k.a. OID or SHA) in the repository.  The id
 155  * permanently refers to the object (although the reference itself can be
 156  * moved).  For example, in libgit2 the direct ref "refs/tags/v0.17.0"
 157  * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
 158  *
 159  * The direct reference will be created in the repository and written to
 160  * the disk.  The generated reference object must be freed by the user.
 161  *
 162  * Valid reference names must follow one of two patterns:
 163  *
 164  * 1. Top-level names must contain only capital letters and underscores,
 165  *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
 166  * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
 167  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
 168  *    sequences ".." and "@{" which have special meaning to revparse.
 169  *
 170  * This function will return an error if a reference already exists with the
 171  * given name unless `force` is true, in which case it will be overwritten.
 172  *
 173  * The message for the reflog will be ignored if the reference does
 174  * not belong in the standard set (HEAD, branches and remote-tracking
 175  * branches) and it does not have a reflog.
 176  *
 177  * @param out Pointer to the newly created reference
 178  * @param repo Repository where that reference will live
 179  * @param name The name of the reference
 180  * @param id The object id pointed to by the reference.
 181  * @param force Overwrite existing references
 182  * @param log_message The one line long message to be appended to the reflog
 183  * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
 184  */
 185 GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message);
 186
 187 /**
 188  * Conditionally create new direct reference
 189  *
 190  * A direct reference (also called an object id reference) refers directly
 191  * to a specific object id (a.k.a. OID or SHA) in the repository.  The id
 192  * permanently refers to the object (although the reference itself can be
 193  * moved).  For example, in libgit2 the direct ref "refs/tags/v0.17.0"
 194  * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
 195  *
 196  * The direct reference will be created in the repository and written to
 197  * the disk.  The generated reference object must be freed by the user.
 198  *
 199  * Valid reference names must follow one of two patterns:
 200  *
 201  * 1. Top-level names must contain only capital letters and underscores,
 202  *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
 203  * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
 204  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
 205  *    sequences ".." and "@{" which have special meaning to revparse.
 206  *
 207  * This function will return an error if a reference already exists with the
 208  * given name unless `force` is true, in which case it will be overwritten.
 209  *
 210  * The message for the reflog will be ignored if the reference does
 211  * not belong in the standard set (HEAD, branches and remote-tracking
 212  * branches) and it does not have a reflog.
 213  *
 214  * It will return GIT_EMODIFIED if the reference's value at the time
 215  * of updating does not match the one passed through `current_id`
 216  * (i.e. if the ref has changed since the user read it).
 217  *
 218  * @param out Pointer to the newly created reference
 219  * @param repo Repository where that reference will live
 220  * @param name The name of the reference
 221  * @param id The object id pointed to by the reference.
 222  * @param force Overwrite existing references
 223  * @param current_id The expected value of the reference at the time of update
 224  * @param log_message The one line long message to be appended to the reflog
 225  * @return 0 on success, GIT_EMODIFIED if the value of the reference
 226  * has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
 227  */
 228 GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message);
 229
 230 /**
 231  * Get the OID pointed to by a direct reference.
 232  *
 233  * Only available if the reference is direct (i.e. an object id reference,
 234  * not a symbolic one).
 235  *
 236  * To find the OID of a symbolic ref, call `git_reference_resolve()` and
 237  * then this function (or maybe use `git_reference_name_to_id()` to
 238  * directly resolve a reference name all the way through to an OID).
 239  *
 240  * @param ref The reference
 241  * @return a pointer to the oid if available, NULL otherwise
 242  */
 243 GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref);
 244
 245 /**
 246  * Return the peeled OID target of this reference.
 247  *
 248  * This peeled OID only applies to direct references that point to
 249  * a hard Tag object: it is the result of peeling such Tag.
 250  *
 251  * @param ref The reference
 252  * @return a pointer to the oid if available, NULL otherwise
 253  */
 254 GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref);
 255
 256 /**
 257  * Get full name to the reference pointed to by a symbolic reference.
 258  *
 259  * Only available if the reference is symbolic.
 260  *
 261  * @param ref The reference
 262  * @return a pointer to the name if available, NULL otherwise
 263  */
 264 GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref);
 265
 266 /**
 267  * Get the type of a reference.
 268  *
 269  * Either direct (GIT_REFERENCE_DIRECT) or symbolic (GIT_REFERENCE_SYMBOLIC)
 270  *
 271  * @param ref The reference
 272  * @return the type
 273  */
 274 GIT_EXTERN(git_reference_t) git_reference_type(const git_reference *ref);
 275
 276 /**
 277  * Get the full name of a reference.
 278  *
 279  * See `git_reference_symbolic_create()` for rules about valid names.
 280  *
 281  * @param ref The reference
 282  * @return the full name for the ref
 283  */
 284 GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
 285
 286 /**
 287  * Resolve a symbolic reference to a direct reference.
 288  *
 289  * This method iteratively peels a symbolic reference until it resolves to
 290  * a direct reference to an OID.
 291  *
 292  * The peeled reference is returned in the `resolved_ref` argument, and
 293  * must be freed manually once it's no longer needed.
 294  *
 295  * If a direct reference is passed as an argument, a copy of that
 296  * reference is returned. This copy must be manually freed too.
 297  *
 298  * @param out Pointer to the peeled reference
 299  * @param ref The reference
 300  * @return 0 or an error code
 301  */
 302 GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref);
 303
 304 /**
 305  * Get the repository where a reference resides.
 306  *
 307  * @param ref The reference
 308  * @return a pointer to the repo
 309  */
 310 GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref);
 311
 312 /**
 313  * Create a new reference with the same name as the given reference but a
 314  * different symbolic target. The reference must be a symbolic reference,
 315  * otherwise this will fail.
 316  *
 317  * The new reference will be written to disk, overwriting the given reference.
 318  *
 319  * The target name will be checked for validity.
 320  * See `git_reference_symbolic_create()` for rules about valid names.
 321  *
 322  * The message for the reflog will be ignored if the reference does
 323  * not belong in the standard set (HEAD, branches and remote-tracking
 324  * branches) and it does not have a reflog.
 325  *
 326  * @param out Pointer to the newly created reference
 327  * @param ref The reference
 328  * @param target The new target for the reference
 329  * @param log_message The one line long message to be appended to the reflog
 330  * @return 0 on success, GIT_EINVALIDSPEC or an error code
 331  */
 332 GIT_EXTERN(int) git_reference_symbolic_set_target(
 333         git_reference **out,
 334         git_reference *ref,
 335         const char *target,
 336         const char *log_message);
 337
 338 /**
 339  * Conditionally create a new reference with the same name as the given reference but a
 340  * different OID target. The reference must be a direct reference, otherwise
 341  * this will fail.
 342  *
 343  * The new reference will be written to disk, overwriting the given reference.
 344  *
 345  * @param out Pointer to the newly created reference
 346  * @param ref The reference
 347  * @param id The new target OID for the reference
 348  * @param log_message The one line long message to be appended to the reflog
 349  * @return 0 on success, GIT_EMODIFIED if the value of the reference
 350  * has changed since it was read, or an error code
 351  */
 352 GIT_EXTERN(int) git_reference_set_target(
 353         git_reference **out,
 354         git_reference *ref,
 355         const git_oid *id,
 356         const char *log_message);
 357
 358 /**
 359  * Rename an existing reference.
 360  *
 361  * This method works for both direct and symbolic references.
 362  *
 363  * The new name will be checked for validity.
 364  * See `git_reference_symbolic_create()` for rules about valid names.
 365  *
 366  * If the `force` flag is not enabled, and there's already
 367  * a reference with the given name, the renaming will fail.
 368  *
 369  * IMPORTANT:
 370  * The user needs to write a proper reflog entry if the
 371  * reflog is enabled for the repository. We only rename
 372  * the reflog if it exists.
 373  *
 374  * @param ref The reference to rename
 375  * @param new_name The new name for the reference
 376  * @param force Overwrite an existing reference
 377  * @param log_message The one line long message to be appended to the reflog
 378  * @return 0 on success, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
 379  *
 380  */
 381 GIT_EXTERN(int) git_reference_rename(
 382         git_reference **new_ref,
 383         git_reference *ref,
 384         const char *new_name,
 385         int force,
 386         const char *log_message);
 387
 388 /**
 389  * Delete an existing reference.
 390  *
 391  * This method works for both direct and symbolic references.  The reference
 392  * will be immediately removed on disk but the memory will not be freed.
 393  * Callers must call `git_reference_free`.
 394  *
 395  * This function will return an error if the reference has changed
 396  * from the time it was looked up.
 397  *
 398  * @param ref The reference to remove
 399  * @return 0, GIT_EMODIFIED or an error code
 400  */
 401 GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 402
 403 /**
 404  * Delete an existing reference by name
 405  *
 406  * This method removes the named reference from the repository without
 407  * looking at its old value.
 408  *
 409  * @param name The reference to remove
 410  * @return 0 or an error code
 411  */
 412 GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name);
 413
 414 /**
 415  * Fill a list with all the references that can be found in a repository.
 416  *
 417  * The string array will be filled with the names of all references; these
 418  * values are owned by the user and should be free'd manually when no
 419  * longer needed, using `git_strarray_free()`.
 420  *
 421  * @param array Pointer to a git_strarray structure where
 422  *              the reference names will be stored
 423  * @param repo Repository where to find the refs
 424  * @return 0 or an error code
 425  */
 426 GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo);
 427
 428 /**
 429  * Callback used to iterate over references
 430  *
 431  * @see git_reference_foreach
 432  *
 433  * @param reference The reference object
 434  * @param payload Payload passed to git_reference_foreach
 435  * @return non-zero to terminate the iteration
 436  */
 437 typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload);
 438
 439 /**
 440  * Callback used to iterate over reference names
 441  *
 442  * @see git_reference_foreach_name
 443  *
 444  * @param name The reference name
 445  * @param payload Payload passed to git_reference_foreach_name
 446  * @return non-zero to terminate the iteration
 447  */
 448 typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload);
 449
 450 /**
 451  * Perform a callback on each reference in the repository.
 452  *
 453  * The `callback` function will be called for each reference in the
 454  * repository, receiving the reference object and the `payload` value
 455  * passed to this method.  Returning a non-zero value from the callback
 456  * will terminate the iteration.
 457  *
 458  * Note that the callback function is responsible to call `git_reference_free`
 459  * on each reference passed to it.
 460  *
 461  * @param repo Repository where to find the refs
 462  * @param callback Function which will be called for every listed ref
 463  * @param payload Additional data to pass to the callback
 464  * @return 0 on success, non-zero callback return value, or error code
 465  */
 466 GIT_EXTERN(int) git_reference_foreach(
 467         git_repository *repo,
 468         git_reference_foreach_cb callback,
 469         void *payload);
 470
 471 /**
 472  * Perform a callback on the fully-qualified name of each reference.
 473  *
 474  * The `callback` function will be called for each reference in the
 475  * repository, receiving the name of the reference and the `payload` value
 476  * passed to this method.  Returning a non-zero value from the callback
 477  * will terminate the iteration.
 478  *
 479  * @param repo Repository where to find the refs
 480  * @param callback Function which will be called for every listed ref name
 481  * @param payload Additional data to pass to the callback
 482  * @return 0 on success, non-zero callback return value, or error code
 483  */
 484 GIT_EXTERN(int) git_reference_foreach_name(
 485         git_repository *repo,
 486         git_reference_foreach_name_cb callback,
 487         void *payload);
 488
 489 /**
 490  * Create a copy of an existing reference.
 491  *
 492  * Call `git_reference_free` to free the data.
 493  *
 494  * @param dest pointer where to store the copy
 495  * @param source object to copy
 496  * @return 0 or an error code
 497  */
 498 GIT_EXTERN(int) git_reference_dup(git_reference **dest, git_reference *source);
 499
 500 /**
 501  * Free the given reference.
 502  *
 503  * @param ref git_reference
 504  */
 505 GIT_EXTERN(void) git_reference_free(git_reference *ref);
 506
 507 /**
 508  * Compare two references.
 509  *
 510  * @param ref1 The first git_reference
 511  * @param ref2 The second git_reference
 512  * @return 0 if the same, else a stable but meaningless ordering.
 513  */
 514 GIT_EXTERN(int) git_reference_cmp(
 515         const git_reference *ref1,
 516         const git_reference *ref2);
 517
 518 /**
 519  * Create an iterator for the repo's references
 520  *
 521  * @param out pointer in which to store the iterator
 522  * @param repo the repository
 523  * @return 0 or an error code
 524  */
 525 GIT_EXTERN(int) git_reference_iterator_new(
 526         git_reference_iterator **out,
 527         git_repository *repo);
 528
 529 /**
 530  * Create an iterator for the repo's references that match the
 531  * specified glob
 532  *
 533  * @param out pointer in which to store the iterator
 534  * @param repo the repository
 535  * @param glob the glob to match against the reference names
 536  * @return 0 or an error code
 537  */
 538 GIT_EXTERN(int) git_reference_iterator_glob_new(
 539         git_reference_iterator **out,
 540         git_repository *repo,
 541         const char *glob);
 542
 543 /**
 544  * Get the next reference
 545  *
 546  * @param out pointer in which to store the reference
 547  * @param iter the iterator
 548  * @return 0, GIT_ITEROVER if there are no more; or an error code
 549  */
 550 GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter);
 551
 552 /**
 553  * Get the next reference's name
 554  *
 555  * This function is provided for convenience in case only the names
 556  * are interesting as it avoids the allocation of the `git_reference`
 557  * object which `git_reference_next()` needs.
 558  *
 559  * @param out pointer in which to store the string
 560  * @param iter the iterator
 561  * @return 0, GIT_ITEROVER if there are no more; or an error code
 562  */
 563 GIT_EXTERN(int) git_reference_next_name(const char **out, git_reference_iterator *iter);
 564
 565 /**
 566  * Free the iterator and its associated resources
 567  *
 568  * @param iter the iterator to free
 569  */
 570 GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter);
 571
 572 /**
 573  * Perform a callback on each reference in the repository whose name
 574  * matches the given pattern.
 575  *
 576  * This function acts like `git_reference_foreach()` with an additional
 577  * pattern match being applied to the reference name before issuing the
 578  * callback function.  See that function for more information.
 579  *
 580  * The pattern is matched using fnmatch or "glob" style where a '*' matches
 581  * any sequence of letters, a '?' matches any letter, and square brackets
 582  * can be used to define character ranges (such as "[0-9]" for digits).
 583  *
 584  * @param repo Repository where to find the refs
 585  * @param glob Pattern to match (fnmatch-style) against reference name.
 586  * @param callback Function which will be called for every listed ref
 587  * @param payload Additional data to pass to the callback
 588  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
 589  */
 590 GIT_EXTERN(int) git_reference_foreach_glob(
 591         git_repository *repo,
 592         const char *glob,
 593         git_reference_foreach_name_cb callback,
 594         void *payload);
 595
 596 /**
 597  * Check if a reflog exists for the specified reference.
 598  *
 599  * @param repo the repository
 600  * @param refname the reference's name
 601  * @return 0 when no reflog can be found, 1 when it exists;
 602  * otherwise an error code.
 603  */
 604 GIT_EXTERN(int) git_reference_has_log(git_repository *repo, const char *refname);
 605
 606 /**
 607  * Ensure there is a reflog for a particular reference.
 608  *
 609  * Make sure that successive updates to the reference will append to
 610  * its log.
 611  *
 612  * @param repo the repository
 613  * @param refname the reference's name
 614  * @return 0 or an error code.
 615  */
 616 GIT_EXTERN(int) git_reference_ensure_log(git_repository *repo, const char *refname);
 617
 618 /**
 619  * Check if a reference is a local branch.
 620  *
 621  * @param ref A git reference
 622  *
 623  * @return 1 when the reference lives in the refs/heads
 624  * namespace; 0 otherwise.
 625  */
 626 GIT_EXTERN(int) git_reference_is_branch(const git_reference *ref);
 627
 628 /**
 629  * Check if a reference is a remote tracking branch
 630  *
 631  * @param ref A git reference
 632  *
 633  * @return 1 when the reference lives in the refs/remotes
 634  * namespace; 0 otherwise.
 635  */
 636 GIT_EXTERN(int) git_reference_is_remote(const git_reference *ref);
 637
 638 /**
 639  * Check if a reference is a tag
 640  *
 641  * @param ref A git reference
 642  *
 643  * @return 1 when the reference lives in the refs/tags
 644  * namespace; 0 otherwise.
 645  */
 646 GIT_EXTERN(int) git_reference_is_tag(const git_reference *ref);
 647
 648 /**
 649  * Check if a reference is a note
 650  *
 651  * @param ref A git reference
 652  *
 653  * @return 1 when the reference lives in the refs/notes
 654  * namespace; 0 otherwise.
 655  */
 656 GIT_EXTERN(int) git_reference_is_note(const git_reference *ref);
 657
 658 /**
 659  * Normalization options for reference lookup
 660  */
 661 typedef enum {
 662         /**
 663          * No particular normalization.
 664          */
 665         GIT_REFERENCE_FORMAT_NORMAL = 0u,
 666
 667         /**
 668          * Control whether one-level refnames are accepted
 669          * (i.e., refnames that do not contain multiple /-separated
 670          * components). Those are expected to be written only using
 671          * uppercase letters and underscore (FETCH_HEAD, ...)
 672          */
 673         GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL = (1u << 0),
 674
 675         /**
 676          * Interpret the provided name as a reference pattern for a
 677          * refspec (as used with remote repositories). If this option
 678          * is enabled, the name is allowed to contain a single * (<star>)
 679          * in place of a one full pathname component
 680          * (e.g., foo/<star>/bar but not foo/bar<star>).
 681          */
 682         GIT_REFERENCE_FORMAT_REFSPEC_PATTERN = (1u << 1),
 683
 684         /**
 685          * Interpret the name as part of a refspec in shorthand form
 686          * so the `ONELEVEL` naming rules aren't enforced and 'master'
 687          * becomes a valid name.
 688          */
 689         GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND = (1u << 2)
 690 } git_reference_format_t;
 691
 692 /**
 693  * Normalize reference name and check validity.
 694  *
 695  * This will normalize the reference name by removing any leading slash
 696  * '/' characters and collapsing runs of adjacent slashes between name
 697  * components into a single slash.
 698  *
 699  * Once normalized, if the reference name is valid, it will be returned in
 700  * the user allocated buffer.
 701  *
 702  * See `git_reference_symbolic_create()` for rules about valid names.
 703  *
 704  * @param buffer_out User allocated buffer to store normalized name
 705  * @param buffer_size Size of buffer_out
 706  * @param name Reference name to be checked.
 707  * @param flags Flags to constrain name validation rules - see the
 708  *              GIT_REFERENCE_FORMAT constants above.
 709  * @return 0 on success, GIT_EBUFS if buffer is too small, GIT_EINVALIDSPEC
 710  * or an error code.
 711  */
 712 GIT_EXTERN(int) git_reference_normalize_name(
 713         char *buffer_out,
 714         size_t buffer_size,
 715         const char *name,
 716         unsigned int flags);
 717
 718 /**
 719  * Recursively peel reference until object of the specified type is found.
 720  *
 721  * The retrieved `peeled` object is owned by the repository
 722  * and should be closed with the `git_object_free` method.
 723  *
 724  * If you pass `GIT_OBJECT_ANY` as the target type, then the object
 725  * will be peeled until a non-tag object is met.
 726  *
 727  * @param out Pointer to the peeled git_object
 728  * @param ref The reference to be processed
 729  * @param type The type of the requested object (GIT_OBJECT_COMMIT,
 730  * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY).
 731  * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
 732  */
 733 GIT_EXTERN(int) git_reference_peel(
 734         git_object **out,
 735         const git_reference *ref,
 736         git_object_t type);
 737
 738 /**
 739  * Ensure the reference name is well-formed.
 740  *
 741  * Valid reference names must follow one of two patterns:
 742  *
 743  * 1. Top-level names must contain only capital letters and underscores,
 744  *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
 745  * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
 746  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
 747  *    sequences ".." and "@{" which have special meaning to revparse.
 748  *
 749  * @param valid output pointer to set with validity of given reference name
 750  * @param refname name to be checked.
 751  * @return 0 on success or an error code
 752  */
 753 GIT_EXTERN(int) git_reference_name_is_valid(int *valid, const char *refname);
 754
 755 /**
 756  * Get the reference's short name
 757  *
 758  * This will transform the reference name into a name "human-readable"
 759  * version. If no shortname is appropriate, it will return the full
 760  * name.
 761  *
 762  * The memory is owned by the reference and must not be freed.
 763  *
 764  * @param ref a reference
 765  * @return the human-readable version of the name
 766  */
 767 GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref);
 768
 769 /** @} */
 770 GIT_END_DECL
 771 #endif