]>
git.proxmox.com Git - libgit2.git/blob - include/git2/object.h
2 * Copyright (C) 2009-2012 the libgit2 contributors
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.
7 #ifndef INCLUDE_git_object_h__
8 #define INCLUDE_git_object_h__
16 * @brief Git revision object management routines
17 * @defgroup git_object Git revision object management routines
24 * Lookup a reference to one of the objects in a repostory.
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.
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.
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 a reference to the object
41 GIT_EXTERN(int) git_object_lookup(
48 * Lookup a reference to one of the objects in a repostory,
49 * given a prefix of its identifier (short id).
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.
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.
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.
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 GIT_SUCCESS or an error code
74 GIT_EXTERN(int) git_object_lookup_prefix(
75 git_object
**object_out
,
82 * Get the id (SHA1) of a repository object
84 * @param obj the repository object
87 GIT_EXTERN(const git_oid
*) git_object_id(const git_object
*obj
);
90 * Get the object type of an object
92 * @param obj the repository object
93 * @return the object's type
95 GIT_EXTERN(git_otype
) git_object_type(const git_object
*obj
);
98 * Get the repository that owns this object
100 * Freeing or calling `git_repository_close` on the
101 * returned pointer will invalidate the actual object.
103 * Any other operation may be run on the repository without
104 * affecting the object.
106 * @param obj the object
107 * @return the repository who owns this object
109 GIT_EXTERN(git_repository
*) git_object_owner(const git_object
*obj
);
112 * Close an open object
114 * This method instructs the library to close an existing
115 * object; note that git_objects are owned and cached by the repository
116 * so the object may or may not be freed after this library call,
117 * depending on how agressive is the caching mechanism used
121 * It *is* necessary to call this method when you stop using
122 * an object. Failure to do so will cause a memory leak.
124 * @param object the object to close
126 GIT_EXTERN(void) git_object_free(git_object
*object
);
129 * Convert an object type to it's string representation.
131 * The result is a pointer to a string in static memory and
132 * should not be free()'ed.
134 * @param type object type to convert.
135 * @return the corresponding string representation.
137 GIT_EXTERN(const char *) git_object_type2string(git_otype type
);
140 * Convert a string object type representation to it's git_otype.
142 * @param str the string to convert.
143 * @return the corresponding git_otype.
145 GIT_EXTERN(git_otype
) git_object_string2type(const char *str
);
148 * Determine if the given git_otype is a valid loose object type.
150 * @param type object type to test.
151 * @return true if the type represents a valid loose object type,
154 GIT_EXTERN(int) git_object_typeisloose(git_otype type
);
157 * Get the size in bytes for the structure which
158 * acts as an in-memory representation of any given
161 * For all the core types, this would the equivalent
162 * of calling `sizeof(git_commit)` if the core types
163 * were not opaque on the external API.
165 * @param type object type to get its size
166 * @return size in bytes of the object
168 GIT_EXTERN(size_t) git_object__size(git_otype type
);