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