/*

[0] Fix | Delete

* Copyright (C) the libgit2 contributors. All rights reserved.

[1] Fix | Delete

*

[2] Fix | Delete

* This file is part of libgit2, distributed under the GNU GPL v2 with

[3] Fix | Delete

* a Linking Exception. For full terms see the included COPYING file.

[4] Fix | Delete

*/

[5] Fix | Delete

#ifndef INCLUDE_git_object_h__

[6] Fix | Delete

#define INCLUDE_git_object_h__

[7] Fix | Delete

[8] Fix | Delete

#include "common.h"

[9] Fix | Delete

#include "types.h"

[10] Fix | Delete

#include "oid.h"

[11] Fix | Delete

#include "buffer.h"

[12] Fix | Delete

[13] Fix | Delete

/**

[14] Fix | Delete

* @file git2/object.h

[15] Fix | Delete

* @brief Git revision object management routines

[16] Fix | Delete

* @defgroup git_object Git revision object management routines

[17] Fix | Delete

* @ingroup Git

[18] Fix | Delete

* @{

[19] Fix | Delete

*/

[20] Fix | Delete

GIT_BEGIN_DECL

[21] Fix | Delete

[22] Fix | Delete

#define GIT_OBJECT_SIZE_MAX UINT64_MAX

[23] Fix | Delete

[24] Fix | Delete

/**

[25] Fix | Delete

* Lookup a reference to one of the objects in a repository.

[26] Fix | Delete

*

[27] Fix | Delete

* The generated reference is owned by the repository and

[28] Fix | Delete

* should be closed with the `git_object_free` method

[29] Fix | Delete

* instead of free'd manually.

[30] Fix | Delete

*

[31] Fix | Delete

* The 'type' parameter must match the type of the object

[32] Fix | Delete

* in the odb; the method will fail otherwise.

[33] Fix | Delete

* The special value 'GIT_OBJECT_ANY' may be passed to let

[34] Fix | Delete

* the method guess the object's type.

[35] Fix | Delete

*

[36] Fix | Delete

* @param object pointer to the looked-up object

[37] Fix | Delete

* @param repo the repository to look up the object

[38] Fix | Delete

* @param id the unique identifier for the object

[39] Fix | Delete

* @param type the type of the object

[40] Fix | Delete

* @return 0 or an error code

[41] Fix | Delete

*/

[42] Fix | Delete

GIT_EXTERN(int) git_object_lookup(

[43] Fix | Delete

git_object **object,

[44] Fix | Delete

git_repository *repo,

[45] Fix | Delete

const git_oid *id,

[46] Fix | Delete

git_object_t type);

[47] Fix | Delete

[48] Fix | Delete

/**

[49] Fix | Delete

* Lookup a reference to one of the objects in a repository,

[50] Fix | Delete

* given a prefix of its identifier (short id).

[51] Fix | Delete

*

[52] Fix | Delete

* The object obtained will be so that its identifier

[53] Fix | Delete

* matches the first 'len' hexadecimal characters

[54] Fix | Delete

* (packets of 4 bits) of the given 'id'.

[55] Fix | Delete

* 'len' must be at least GIT_OID_MINPREFIXLEN, and

[56] Fix | Delete

* long enough to identify a unique object matching

[57] Fix | Delete

* the prefix; otherwise the method will fail.

[58] Fix | Delete

*

[59] Fix | Delete

* The generated reference is owned by the repository and

[60] Fix | Delete

* should be closed with the `git_object_free` method

[61] Fix | Delete

* instead of free'd manually.

[62] Fix | Delete

*

[63] Fix | Delete

* The 'type' parameter must match the type of the object

[64] Fix | Delete

* in the odb; the method will fail otherwise.

[65] Fix | Delete

* The special value 'GIT_OBJECT_ANY' may be passed to let

[66] Fix | Delete

* the method guess the object's type.

[67] Fix | Delete

*

[68] Fix | Delete

* @param object_out pointer where to store the looked-up object

[69] Fix | Delete

* @param repo the repository to look up the object

[70] Fix | Delete

* @param id a short identifier for the object

[71] Fix | Delete

* @param len the length of the short identifier

[72] Fix | Delete

* @param type the type of the object

[73] Fix | Delete

* @return 0 or an error code

[74] Fix | Delete

*/

[75] Fix | Delete

GIT_EXTERN(int) git_object_lookup_prefix(

[76] Fix | Delete

git_object **object_out,

[77] Fix | Delete

git_repository *repo,

[78] Fix | Delete

const git_oid *id,

[79] Fix | Delete

size_t len,

[80] Fix | Delete

git_object_t type);

[81] Fix | Delete

[82] Fix | Delete

[83] Fix | Delete

/**

[84] Fix | Delete

* Lookup an object that represents a tree entry.

[85] Fix | Delete

*

[86] Fix | Delete

* @param out buffer that receives a pointer to the object (which must be freed

[87] Fix | Delete

* by the caller)

[88] Fix | Delete

* @param treeish root object that can be peeled to a tree

[89] Fix | Delete

* @param path relative path from the root object to the desired object

[90] Fix | Delete

* @param type type of object desired

[91] Fix | Delete

* @return 0 on success, or an error code

[92] Fix | Delete

*/

[93] Fix | Delete

GIT_EXTERN(int) git_object_lookup_bypath(

[94] Fix | Delete

git_object **out,

[95] Fix | Delete

const git_object *treeish,

[96] Fix | Delete

const char *path,

[97] Fix | Delete

git_object_t type);

[98] Fix | Delete

[99] Fix | Delete

/**

[100] Fix | Delete

* Get the id (SHA1) of a repository object

[101] Fix | Delete

*

[102] Fix | Delete

* @param obj the repository object

[103] Fix | Delete

* @return the SHA1 id

[104] Fix | Delete

*/

[105] Fix | Delete

GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);

[106] Fix | Delete

[107] Fix | Delete

/**

[108] Fix | Delete

* Get a short abbreviated OID string for the object

[109] Fix | Delete

*

[110] Fix | Delete

* This starts at the "core.abbrev" length (default 7 characters) and

[111] Fix | Delete

* iteratively extends to a longer string if that length is ambiguous.

[112] Fix | Delete

* The result will be unambiguous (at least until new objects are added to

[113] Fix | Delete

* the repository).

[114] Fix | Delete

*

[115] Fix | Delete

* @param out Buffer to write string into

[116] Fix | Delete

* @param obj The object to get an ID for

[117] Fix | Delete

* @return 0 on success, <0 for error

[118] Fix | Delete

*/

[119] Fix | Delete

GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);

[120] Fix | Delete

[121] Fix | Delete

/**

[122] Fix | Delete

* Get the object type of an object

[123] Fix | Delete

*

[124] Fix | Delete

* @param obj the repository object

[125] Fix | Delete

* @return the object's type

[126] Fix | Delete

*/

[127] Fix | Delete

GIT_EXTERN(git_object_t) git_object_type(const git_object *obj);

[128] Fix | Delete

[129] Fix | Delete

/**

[130] Fix | Delete

* Get the repository that owns this object

[131] Fix | Delete

*

[132] Fix | Delete

* Freeing or calling `git_repository_close` on the

[133] Fix | Delete

* returned pointer will invalidate the actual object.

[134] Fix | Delete

*

[135] Fix | Delete

* Any other operation may be run on the repository without

[136] Fix | Delete

* affecting the object.

[137] Fix | Delete

*

[138] Fix | Delete

* @param obj the object

[139] Fix | Delete

* @return the repository who owns this object

[140] Fix | Delete

*/

[141] Fix | Delete

GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);

[142] Fix | Delete

[143] Fix | Delete

/**

[144] Fix | Delete

* Close an open object

[145] Fix | Delete

*

[146] Fix | Delete

* This method instructs the library to close an existing

[147] Fix | Delete

* object; note that git_objects are owned and cached by the repository

[148] Fix | Delete

* so the object may or may not be freed after this library call,

[149] Fix | Delete

* depending on how aggressive is the caching mechanism used

[150] Fix | Delete

* by the repository.

[151] Fix | Delete

*

[152] Fix | Delete

* IMPORTANT:

[153] Fix | Delete

* It *is* necessary to call this method when you stop using

[154] Fix | Delete

* an object. Failure to do so will cause a memory leak.

[155] Fix | Delete

*

[156] Fix | Delete

* @param object the object to close

[157] Fix | Delete

*/

[158] Fix | Delete

GIT_EXTERN(void) git_object_free(git_object *object);

[159] Fix | Delete

[160] Fix | Delete

/**

[161] Fix | Delete

* Convert an object type to its string representation.

[162] Fix | Delete

*

[163] Fix | Delete

* The result is a pointer to a string in static memory and

[164] Fix | Delete

* should not be free()'ed.

[165] Fix | Delete

*

[166] Fix | Delete

* @param type object type to convert.

[167] Fix | Delete

* @return the corresponding string representation.

[168] Fix | Delete

*/

[169] Fix | Delete

GIT_EXTERN(const char *) git_object_type2string(git_object_t type);

[170] Fix | Delete

[171] Fix | Delete

/**

[172] Fix | Delete

* Convert a string object type representation to it's git_object_t.

[173] Fix | Delete

*

[174] Fix | Delete

* @param str the string to convert.

[175] Fix | Delete

* @return the corresponding git_object_t.

[176] Fix | Delete

*/

[177] Fix | Delete

GIT_EXTERN(git_object_t) git_object_string2type(const char *str);

[178] Fix | Delete

[179] Fix | Delete

/**

[180] Fix | Delete

* Determine if the given git_object_t is a valid loose object type.

[181] Fix | Delete

*

[182] Fix | Delete

* @param type object type to test.

[183] Fix | Delete

* @return true if the type represents a valid loose object type,

[184] Fix | Delete

* false otherwise.

[185] Fix | Delete

*/

[186] Fix | Delete

GIT_EXTERN(int) git_object_typeisloose(git_object_t type);

[187] Fix | Delete

[188] Fix | Delete

/**

[189] Fix | Delete

* Recursively peel an object until an object of the specified type is met.

[190] Fix | Delete

*

[191] Fix | Delete

* If the query cannot be satisfied due to the object model,

[192] Fix | Delete

* GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a

[193] Fix | Delete

* tree).

[194] Fix | Delete

*

[195] Fix | Delete

* If you pass `GIT_OBJECT_ANY` as the target type, then the object will

[196] Fix | Delete

* be peeled until the type changes. A tag will be peeled until the

[197] Fix | Delete

* referenced object is no longer a tag, and a commit will be peeled

[198] Fix | Delete

* to a tree. Any other object type will return GIT_EINVALIDSPEC.

[199] Fix | Delete

*

[200] Fix | Delete

* If peeling a tag we discover an object which cannot be peeled to

[201] Fix | Delete

* the target type due to the object model, GIT_EPEEL will be

[202] Fix | Delete

* returned.

[203] Fix | Delete

*

[204] Fix | Delete

* You must free the returned object.

[205] Fix | Delete

*

[206] Fix | Delete

* @param peeled Pointer to the peeled git_object

[207] Fix | Delete

* @param object The object to be processed

[208] Fix | Delete

* @param target_type The type of the requested object (a GIT_OBJECT_ value)

[209] Fix | Delete

* @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code

[210] Fix | Delete

*/

[211] Fix | Delete

GIT_EXTERN(int) git_object_peel(

[212] Fix | Delete

git_object **peeled,

[213] Fix | Delete

const git_object *object,

[214] Fix | Delete

git_object_t target_type);

[215] Fix | Delete

[216] Fix | Delete

/**

[217] Fix | Delete

* Create an in-memory copy of a Git object. The copy must be

[218] Fix | Delete

* explicitly free'd or it will leak.

[219] Fix | Delete

*

[220] Fix | Delete

* @param dest Pointer to store the copy of the object

[221] Fix | Delete

* @param source Original object to copy

[222] Fix | Delete

*/

[223] Fix | Delete

GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);

[224] Fix | Delete

[225] Fix | Delete

/** @} */

[226] Fix | Delete

GIT_END_DECL

[227] Fix | Delete

[228] Fix | Delete

#endif

[229] Fix | Delete

[230] Fix | Delete