This repository was archived by the owner on Jun 3, 2024. It is now read-only.
forked from libgit2/libgit2
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathcommit.h
More file actions
325 lines (299 loc) · 9.63 KB
/
Copy pathcommit.h
File metadata and controls
325 lines (299 loc) · 9.63 KB
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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
/*
* 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_commit_h__
#define INCLUDE_git_commit_h__
#include "common.h"
#include "types.h"
#include "oid.h"
#include "object.h"
/**
* @file git2/commit.h
* @brief Git commit parsing, formatting routines
* @defgroup git_commit Git commit parsing, formatting routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Lookup a commit object from a repository.
*
* The returned object should be released with `git_commit_free` when no
* longer needed.
*
* @param commit pointer to the looked up commit
* @param repo the repo to use when locating the commit.
* @param id identity of the commit to locate. If the object is
* an annotated tag it will be peeled back to the commit.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_lookup(
git_commit **commit, git_repository *repo, const git_oid *id);
/**
* Lookup a commit object from a repository, given a prefix of its
* identifier (short id).
*
* The returned object should be released with `git_commit_free` when no
* longer needed.
*
* @see git_object_lookup_prefix
*
* @param commit pointer to the looked up commit
* @param repo the repo to use when locating the commit.
* @param id identity of the commit to locate. If the object is
* an annotated tag it will be peeled back to the commit.
* @param len the length of the short identifier
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_lookup_prefix(
git_commit **commit, git_repository *repo, const git_oid *id, size_t len);
/**
* Close an open commit
*
* This is a wrapper around git_object_free()
*
* IMPORTANT:
* It *is* necessary to call this method when you stop
* using a commit. Failure to do so will cause a memory leak.
*
* @param commit the commit to close
*/
GIT_EXTERN(void) git_commit_free(git_commit *commit);
/**
* Get the id of a commit.
*
* @param commit a previously loaded commit.
* @return object identity for the commit.
*/
GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit);
/**
* Get the repository that contains the commit.
*
* @param commit A previously loaded commit.
* @return Repository that contains this commit.
*/
GIT_EXTERN(git_repository *) git_commit_owner(const git_commit *commit);
/**
* Get the encoding for the message of a commit,
* as a string representing a standard encoding name.
*
* The encoding may be NULL if the `encoding` header
* in the commit is missing; in that case UTF-8 is assumed.
*
* @param commit a previously loaded commit.
* @return NULL, or the encoding
*/
GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit);
/**
* Get the full message of a commit.
*
* The returned message will be slightly prettified by removing any
* potential leading newlines.
*
* @param commit a previously loaded commit.
* @return the message of a commit
*/
GIT_EXTERN(const char *) git_commit_message(const git_commit *commit);
/**
* Get the full raw message of a commit.
*
* @param commit a previously loaded commit.
* @return the raw message of a commit
*/
GIT_EXTERN(const char *) git_commit_message_raw(const git_commit *commit);
/**
* Get the short "summary" of the git commit message.
*
* The returned message is the summary of the commit, comprising the
* first paragraph of the message with whitespace trimmed and squashed.
*
* @param commit a previously loaded commit.
* @return the summary of a commit or NULL on error
*/
GIT_EXTERN(const char *) git_commit_summary(git_commit *commit);
/**
* Get the commit time (i.e. committer time) of a commit.
*
* @param commit a previously loaded commit.
* @return the time of a commit
*/
GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit);
/**
* Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
*
* @param commit a previously loaded commit.
* @return positive or negative timezone offset, in minutes from UTC
*/
GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit);
/**
* Get the committer of a commit.
*
* @param commit a previously loaded commit.
* @return the committer of a commit
*/
GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit);
/**
* Get the author of a commit.
*
* @param commit a previously loaded commit.
* @return the author of a commit
*/
GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
/**
* Get the full raw text of the commit header.
*
* @param commit a previously loaded commit
* @return the header text of the commit
*/
GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit);
/**
* Get the tree pointed to by a commit.
*
* @param tree_out pointer where to store the tree object
* @param commit a previously loaded commit.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
/**
* Get the id of the tree pointed to by a commit. This differs from
* `git_commit_tree` in that no attempts are made to fetch an object
* from the ODB.
*
* @param commit a previously loaded commit.
* @return the id of tree pointed to by commit.
*/
GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
/**
* Get the number of parents of this commit
*
* @param commit a previously loaded commit.
* @return integer of count of parents
*/
GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
/**
* Get the specified parent of the commit.
*
* @param out Pointer where to store the parent commit
* @param commit a previously loaded commit.
* @param n the position of the parent (from 0 to `parentcount`)
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_parent(
git_commit **out,
const git_commit *commit,
unsigned int n);
/**
* Get the oid of a specified parent for a commit. This is different from
* `git_commit_parent`, which will attempt to load the parent commit from
* the ODB.
*
* @param commit a previously loaded commit.
* @param n the position of the parent (from 0 to `parentcount`)
* @return the id of the parent, NULL on error.
*/
GIT_EXTERN(const git_oid *) git_commit_parent_id(
const git_commit *commit,
unsigned int n);
/**
* Get the commit object that is the <n>th generation ancestor
* of the named commit object, following only the first parents.
* The returned commit has to be freed by the caller.
*
* Passing `0` as the generation number returns another instance of the
* base commit itself.
*
* @param ancestor Pointer where to store the ancestor commit
* @param commit a previously loaded commit.
* @param n the requested generation
* @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists
* or an error code
*/
GIT_EXTERN(int) git_commit_nth_gen_ancestor(
git_commit **ancestor,
const git_commit *commit,
unsigned int n);
/**
* Create new commit in the repository from a list of `git_object` pointers
*
* The message will not be cleaned up automatically. You can do that with
* the `git_message_prettify()` function.
*
* @param id Pointer in which to store the OID of the newly created commit
*
* @param repo Repository where to store the commit
*
* @param update_ref If not NULL, name of the reference that
* will be updated to point to this commit. If the reference
* is not direct, it will be resolved to a direct reference.
* Use "HEAD" to update the HEAD of the current branch and
* make it point to this commit. If the reference doesn't
* exist yet, it will be created.
*
* @param author Signature with author and author time of commit
*
* @param committer Signature with committer and * commit time of commit
*
* @param message_encoding The encoding for the message in the
* commit, represented with a standard encoding name.
* E.g. "UTF-8". If NULL, no encoding header is written and
* UTF-8 is assumed.
*
* @param message Full message for this commit
*
* @param tree An instance of a `git_tree` object that will
* be used as the tree for the commit. This tree object must
* also be owned by the given `repo`.
*
* @param parent_count Number of parents for this commit
*
* @param parents Array of `parent_count` pointers to `git_commit`
* objects that will be used as the parents for this commit. This
* array may be NULL if `parent_count` is 0 (root commit). All the
* given commits must be owned by the `repo`.
*
* @return 0 or an error code
* The created commit will be written to the Object Database and
* the given reference will be updated to point to it
*/
GIT_EXTERN(int) git_commit_create(
git_oid *id,
git_repository *repo,
const char *update_ref,
const git_signature *author,
const git_signature *committer,
const char *message_encoding,
const char *message,
const git_tree *tree,
int parent_count,
const git_commit *parents[]);
/**
* Create new commit in the repository using a variable argument list.
*
* The message will be cleaned up from excess whitespace and it will be made
* sure that the last line ends with a '\n'.
*
* The parents for the commit are specified as a variable list of pointers
* to `const git_commit *`. Note that this is a convenience method which may
* not be safe to export for certain languages or compilers
*
* All other parameters remain the same at `git_commit_create()`.
*
* @see git_commit_create
*/
GIT_EXTERN(int) git_commit_create_v(
git_oid *id,
git_repository *repo,
const char *update_ref,
const git_signature *author,
const git_signature *committer,
const char *message_encoding,
const char *message,
const git_tree *tree,
int parent_count,
...);
/** @} */
GIT_END_DECL
#endif