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