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