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