1 /*
2  * Copyright (C) the libgit2 contributors. All rights reserved.
3  *
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.
6  */
7 #ifndef INCLUDE_git_message_h__
8 #define INCLUDE_git_message_h__
9 
10 #include "common.h"
11 #include "buffer.h"
12 
13 /**
14  * @file git2/message.h
15  * @brief Git message management routines
16  * @ingroup Git
17  * @{
18  */
19 GIT_BEGIN_DECL
20 
21 /**
22  * Clean up excess whitespace and make sure there is a trailing newline in the message.
23  *
24  * Optionally, it can remove lines which start with the comment character.
25  *
26  * @param out The user-allocated git_buf which will be filled with the
27  *     cleaned up message.
28  *
29  * @param message The message to be prettified.
30  *
31  * @param strip_comments Non-zero to remove comment lines, 0 to leave them in.
32  *
33  * @param comment_char Comment character. Lines starting with this character
34  * are considered to be comments and removed if `strip_comments` is non-zero.
35  *
36  * @return 0 or an error code.
37  */
38 GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char);
39 
40 /**
41  * Represents a single git message trailer.
42  */
43 typedef struct {
44   const char *key;
45   const char *value;
46 } git_message_trailer;
47 
48 /**
49  * Represents an array of git message trailers.
50  *
51  * Struct members under the private comment are private, subject to change
52  * and should not be used by callers.
53  */
54 typedef struct {
55   git_message_trailer *trailers;
56   size_t count;
57 
58   /* private */
59   char *_trailer_block;
60 } git_message_trailer_array;
61 
62 /**
63  * Parse trailers out of a message, filling the array pointed to by +arr+.
64  *
65  * Trailers are key/value pairs in the last paragraph of a message, not
66  * including any patches or conflicts that may be present.
67  *
68  * @param arr A pre-allocated git_message_trailer_array struct to be filled in
69  *            with any trailers found during parsing.
70  * @param message The message to be parsed
71  * @return 0 on success, or non-zero on error.
72  */
73 GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char *message);
74 
75 /**
76  * Clean's up any allocated memory in the git_message_trailer_array filled by
77  * a call to git_message_trailers.
78  */
79 GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr);
80 
81 /** @} */
82 GIT_END_DECL
83 
84 #endif /* INCLUDE_git_message_h__ */
85