include/git2/object.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_object_h__
   8 #define INCLUDE_git_object_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/object.h
  16  * @brief Git revision object management routines
  17  * @defgroup git_object Git revision object management routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Lookup a reference to one of the objects in a repository.
  25  *
  26  * The generated reference is owned by the repository and
  27  * should be closed with the `git_object_free` method
  28  * instead of free'd manually.
  29  *
  30  * The 'type' parameter must match the type of the object
  31  * in the odb; the method will fail otherwise.
  32  * The special value 'GIT_OBJ_ANY' may be passed to let
  33  * the method guess the object's type.
  34  *
  35  * @param object pointer to the looked-up object
  36  * @param repo the repository to look up the object
  37  * @param id the unique identifier for the object
  38  * @param type the type of the object
  39  * @return 0 or an error code
  40  */
  41 GIT_EXTERN(int) git_object_lookup(
  42                 git_object **object,
  43                 git_repository *repo,
  44                 const git_oid *id,
  45                 git_otype type);
  46
  47 /**
  48  * Lookup a reference to one of the objects in a repository,
  49  * given a prefix of its identifier (short id).
  50  *
  51  * The object obtained will be so that its identifier
  52  * matches the first 'len' hexadecimal characters
  53  * (packets of 4 bits) of the given 'id'.
  54  * 'len' must be at least GIT_OID_MINPREFIXLEN, and
  55  * long enough to identify a unique object matching
  56  * the prefix; otherwise the method will fail.
  57  *
  58  * The generated reference is owned by the repository and
  59  * should be closed with the `git_object_free` method
  60  * instead of free'd manually.
  61  *
  62  * The 'type' parameter must match the type of the object
  63  * in the odb; the method will fail otherwise.
  64  * The special value 'GIT_OBJ_ANY' may be passed to let
  65  * the method guess the object's type.
  66  *
  67  * @param object_out pointer where to store the looked-up object
  68  * @param repo the repository to look up the object
  69  * @param id a short identifier for the object
  70  * @param len the length of the short identifier
  71  * @param type the type of the object
  72  * @return 0 or an error code
  73  */
  74 GIT_EXTERN(int) git_object_lookup_prefix(
  75                 git_object **object_out,
  76                 git_repository *repo,
  77                 const git_oid *id,
  78                 size_t len,
  79                 git_otype type);
  80
  81
  82 /**
  83  * Lookup an object that represents a tree entry.
  84  *
  85  * @param out buffer that receives a pointer to the object (which must be freed
  86  *            by the caller)
  87  * @param treeish root object that can be peeled to a tree
  88  * @param path relative path from the root object to the desired object
  89  * @param type type of object desired
  90  * @return 0 on success, or an error code
  91  */
  92 GIT_EXTERN(int) git_object_lookup_bypath(
  93                 git_object **out,
  94                 const git_object *treeish,
  95                 const char *path,
  96                 git_otype type);
  97
  98 /**
  99  * Get the id (SHA1) of a repository object
 100  *
 101  * @param obj the repository object
 102  * @return the SHA1 id
 103  */
 104 GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);
 105
 106 /**
 107  * Get the object type of an object
 108  *
 109  * @param obj the repository object
 110  * @return the object's type
 111  */
 112 GIT_EXTERN(git_otype) git_object_type(const git_object *obj);
 113
 114 /**
 115  * Get the repository that owns this object
 116  *
 117  * Freeing or calling `git_repository_close` on the
 118  * returned pointer will invalidate the actual object.
 119  *
 120  * Any other operation may be run on the repository without
 121  * affecting the object.
 122  *
 123  * @param obj the object
 124  * @return the repository who owns this object
 125  */
 126 GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
 127
 128 /**
 129  * Close an open object
 130  *
 131  * This method instructs the library to close an existing
 132  * object; note that git_objects are owned and cached by the repository
 133  * so the object may or may not be freed after this library call,
 134  * depending on how aggressive is the caching mechanism used
 135  * by the repository.
 136  *
 137  * IMPORTANT:
 138  * It *is* necessary to call this method when you stop using
 139  * an object. Failure to do so will cause a memory leak.
 140  *
 141  * @param object the object to close
 142  */
 143 GIT_EXTERN(void) git_object_free(git_object *object);
 144
 145 /**
 146  * Convert an object type to it's string representation.
 147  *
 148  * The result is a pointer to a string in static memory and
 149  * should not be free()'ed.
 150  *
 151  * @param type object type to convert.
 152  * @return the corresponding string representation.
 153  */
 154 GIT_EXTERN(const char *) git_object_type2string(git_otype type);
 155
 156 /**
 157  * Convert a string object type representation to it's git_otype.
 158  *
 159  * @param str the string to convert.
 160  * @return the corresponding git_otype.
 161  */
 162 GIT_EXTERN(git_otype) git_object_string2type(const char *str);
 163
 164 /**
 165  * Determine if the given git_otype is a valid loose object type.
 166  *
 167  * @param type object type to test.
 168  * @return true if the type represents a valid loose object type,
 169  * false otherwise.
 170  */
 171 GIT_EXTERN(int) git_object_typeisloose(git_otype type);
 172
 173 /**
 174  * Get the size in bytes for the structure which
 175  * acts as an in-memory representation of any given
 176  * object type.
 177  *
 178  * For all the core types, this would the equivalent
 179  * of calling `sizeof(git_commit)` if the core types
 180  * were not opaque on the external API.
 181  *
 182  * @param type object type to get its size
 183  * @return size in bytes of the object
 184  */
 185 GIT_EXTERN(size_t) git_object__size(git_otype type);
 186
 187 /**
 188  * Recursively peel an object until an object of the specified type is met.
 189  *
 190  * The retrieved `peeled` object is owned by the repository and should be
 191  * closed with the `git_object_free` method.
 192  *
 193  * If you pass `GIT_OBJ_ANY` as the target type, then the object will be
 194  * peeled until the type changes (e.g. a tag will be chased until the
 195  * referenced object is no longer a tag).
 196  *
 197  * @param peeled Pointer to the peeled git_object
 198  * @param object The object to be processed
 199  * @param target_type The type of the requested object (GIT_OBJ_COMMIT,
 200  * GIT_OBJ_TAG, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_ANY).
 201  * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
 202  */
 203 GIT_EXTERN(int) git_object_peel(
 204         git_object **peeled,
 205         const git_object *object,
 206         git_otype target_type);
 207
 208 /**
 209  * Create an in-memory copy of a Git object. The copy must be
 210  * explicitly free'd or it will leak.
 211  *
 212  * @param dest Pointer to store the copy of the object
 213  * @param source Original object to copy
 214  */
 215 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
 216
 217 /** @} */
 218 GIT_END_DECL
 219
 220 #endif