FilesExpand file tree

master

/

object.h

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

242 lines (223 loc) · 7.19 KB

master

/

object.h

Copy path

Top

File metadata and controls

• Code
• Blame

242 lines (223 loc) · 7.19 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

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

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

/*

* 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"

#include "buffer.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 0 or an error code

*/

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);

/**

* Lookup an object that represents a tree entry.

*

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

* by the caller)

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

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

* @param type type of object desired

* @return 0 on success, or an error code

*/

GIT_EXTERN(int) git_object_lookup_bypath(

git_object **out,

const git_object *treeish,

const char *path,

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 a short abbreviated OID string for the object

*

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

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

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

* the repository).

*

* @param out Buffer to write string into

* @param obj The object to get an ID for

* @return 0 on success, <0 for error

*/

GIT_EXTERN(int) git_object_short_id(git_buf *out, 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 its 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.

*

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

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

* tree).

*

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

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

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

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

*

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

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

* returned.

*

* You must free the returned object.

*

* @param peeled Pointer to the peeled git_object

* @param object The object to be processed

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

* @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, 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