]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
d12299fe VM |
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" | |
13f7ecd7 | 13 | #include "buffer.h" |
d12299fe VM |
14 | |
15 | /** | |
f5918330 | 16 | * @file git2/object.h |
d12299fe VM |
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 | ||
22a2d3d5 UG |
24 | #define GIT_OBJECT_SIZE_MAX UINT64_MAX |
25 | ||
5de079b8 | 26 | /** |
d73c94b2 | 27 | * Lookup a reference to one of the objects in a repository. |
5de079b8 VM |
28 | * |
29 | * The generated reference is owned by the repository and | |
45e79e37 | 30 | * should be closed with the `git_object_free` method |
72a3fe42 | 31 | * instead of free'd manually. |
5de079b8 VM |
32 | * |
33 | * The 'type' parameter must match the type of the object | |
34 | * in the odb; the method will fail otherwise. | |
ac3d33df | 35 | * The special value 'GIT_OBJECT_ANY' may be passed to let |
5de079b8 VM |
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 | |
49781a03 | 42 | * @return 0 or an error code |
5de079b8 | 43 | */ |
d0323a5f VM |
44 | GIT_EXTERN(int) git_object_lookup( |
45 | git_object **object, | |
46 | git_repository *repo, | |
47 | const git_oid *id, | |
ac3d33df | 48 | git_object_t type); |
5de079b8 | 49 | |
dd453c4d | 50 | /** |
d73c94b2 | 51 | * Lookup a reference to one of the objects in a repository, |
dd453c4d MP |
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'. | |
ac2b94ad MP |
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. | |
dd453c4d MP |
60 | * |
61 | * The generated reference is owned by the repository and | |
45e79e37 | 62 | * should be closed with the `git_object_free` method |
dd453c4d MP |
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. | |
ac3d33df | 67 | * The special value 'GIT_OBJECT_ANY' may be passed to let |
dd453c4d MP |
68 | * the method guess the object's type. |
69 | * | |
d144c569 | 70 | * @param object_out pointer where to store the looked-up object |
dd453c4d MP |
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 | |
e172cf08 | 75 | * @return 0 or an error code |
dd453c4d | 76 | */ |
d0323a5f VM |
77 | GIT_EXTERN(int) git_object_lookup_prefix( |
78 | git_object **object_out, | |
79 | git_repository *repo, | |
80 | const git_oid *id, | |
b8457baa | 81 | size_t len, |
ac3d33df | 82 | git_object_t type); |
dd453c4d | 83 | |
ceab4e26 BS |
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, | |
ac3d33df | 99 | git_object_t type); |
ceab4e26 | 100 | |
d12299fe VM |
101 | /** |
102 | * Get the id (SHA1) of a repository object | |
103 | * | |
d12299fe VM |
104 | * @param obj the repository object |
105 | * @return the SHA1 id | |
106 | */ | |
17cdf252 | 107 | GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); |
d12299fe | 108 | |
13f7ecd7 RB |
109 | /** |
110 | * Get a short abbreviated OID string for the object | |
111 | * | |
d2c16e9a RB |
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 | * | |
13f7ecd7 RB |
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 | ||
d12299fe VM |
123 | /** |
124 | * Get the object type of an object | |
125 | * | |
126 | * @param obj the repository object | |
127 | * @return the object's type | |
128 | */ | |
ac3d33df | 129 | GIT_EXTERN(git_object_t) git_object_type(const git_object *obj); |
d12299fe VM |
130 | |
131 | /** | |
132 | * Get the repository that owns this object | |
133 | * | |
ef5ffed3 VM |
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 | * | |
d12299fe VM |
140 | * @param obj the object |
141 | * @return the repository who owns this object | |
142 | */ | |
17cdf252 | 143 | GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj); |
d12299fe VM |
144 | |
145 | /** | |
48c27f86 | 146 | * Close an open object |
d12299fe | 147 | * |
48c27f86 | 148 | * This method instructs the library to close an existing |
6b2a1941 VM |
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, | |
d73c94b2 | 151 | * depending on how aggressive is the caching mechanism used |
6b2a1941 | 152 | * by the repository. |
d12299fe | 153 | * |
48c27f86 | 154 | * IMPORTANT: |
72a3fe42 VM |
155 | * It *is* necessary to call this method when you stop using |
156 | * an object. Failure to do so will cause a memory leak. | |
48c27f86 VM |
157 | * |
158 | * @param object the object to close | |
d12299fe | 159 | */ |
45e79e37 | 160 | GIT_EXTERN(void) git_object_free(git_object *object); |
d12299fe VM |
161 | |
162 | /** | |
4ae4a9bb | 163 | * Convert an object type to its string representation. |
d12299fe VM |
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 | */ | |
ac3d33df | 171 | GIT_EXTERN(const char *) git_object_type2string(git_object_t type); |
d12299fe VM |
172 | |
173 | /** | |
ac3d33df | 174 | * Convert a string object type representation to it's git_object_t. |
d12299fe VM |
175 | * |
176 | * @param str the string to convert. | |
ac3d33df | 177 | * @return the corresponding git_object_t. |
d12299fe | 178 | */ |
ac3d33df | 179 | GIT_EXTERN(git_object_t) git_object_string2type(const char *str); |
d12299fe VM |
180 | |
181 | /** | |
ac3d33df | 182 | * Determine if the given git_object_t is a valid loose object type. |
d12299fe VM |
183 | * |
184 | * @param type object type to test. | |
185 | * @return true if the type represents a valid loose object type, | |
186 | * false otherwise. | |
187 | */ | |
ac3d33df | 188 | GIT_EXTERN(int) git_object_typeisloose(git_object_t type); |
d12299fe | 189 | |
db9be945 | 190 | /** |
d8057a5b | 191 | * Recursively peel an object until an object of the specified type is met. |
db9be945 | 192 | * |
753e17b0 CMN |
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). | |
d8057a5b | 196 | * |
ac3d33df | 197 | * If you pass `GIT_OBJECT_ANY` as the target type, then the object will |
753e17b0 CMN |
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. | |
db9be945 | 207 | * |
208 | * @param peeled Pointer to the peeled git_object | |
209 | * @param object The object to be processed | |
ac3d33df | 210 | * @param target_type The type of the requested object (a GIT_OBJECT_ value) |
753e17b0 | 211 | * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code |
db9be945 | 212 | */ |
213 | GIT_EXTERN(int) git_object_peel( | |
d9023dbe RB |
214 | git_object **peeled, |
215 | const git_object *object, | |
ac3d33df | 216 | git_object_t target_type); |
db9be945 | 217 | |
575a54db VM |
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 | |
e579e0f7 | 224 | * @return 0 or an error code |
575a54db VM |
225 | */ |
226 | GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source); | |
227 | ||
e579e0f7 MB |
228 | /** |
229 | * Analyzes a buffer of raw object content and determines its validity. | |
230 | * Tree, commit, and tag objects will be parsed and ensured that they | |
231 | * are valid, parseable content. (Blobs are always valid by definition.) | |
232 | * An error message will be set with an informative message if the object | |
233 | * is not valid. | |
234 | * | |
235 | * @warning This function is experimental and its signature may change in | |
236 | * the future. | |
237 | * | |
238 | * @param valid Output pointer to set with validity of the object content | |
239 | * @param buf The contents to validate | |
240 | * @param len The length of the buffer | |
241 | * @param type The type of the object in the buffer | |
242 | * @return 0 on success or an error code | |
243 | */ | |
244 | GIT_EXTERN(int) git_object_rawcontent_is_valid( | |
245 | int *valid, | |
246 | const char *buf, | |
247 | size_t len, | |
248 | git_object_t type); | |
249 | ||
d12299fe VM |
250 | /** @} */ |
251 | GIT_END_DECL | |
252 | ||
253 | #endif |