include/git2/message.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_message_h__
0008 #define INCLUDE_git_message_h__
0009
0010 #include "common.h"
0011 #include "buffer.h"
0012
0013 /**
0014  * @file git2/message.h
0015  * @brief Git message management routines
0016  * @ingroup Git
0017  * @{
0018  */
0019 GIT_BEGIN_DECL
0020
0021 /**
0022  * Clean up excess whitespace and make sure there is a trailing newline in the message.
0023  *
0024  * Optionally, it can remove lines which start with the comment character.
0025  *
0026  * @param out The user-allocated git_buf which will be filled with the
0027  *     cleaned up message.
0028  *
0029  * @param message The message to be prettified.
0030  *
0031  * @param strip_comments Non-zero to remove comment lines, 0 to leave them in.
0032  *
0033  * @param comment_char Comment character. Lines starting with this character
0034  * are considered to be comments and removed if `strip_comments` is non-zero.
0035  *
0036  * @return 0 or an error code.
0037  */
0038 GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char);
0039
0040 /**
0041  * Represents a single git message trailer.
0042  */
0043 typedef struct {
0044   const char *key;
0045   const char *value;
0046 } git_message_trailer;
0047
0048 /**
0049  * Represents an array of git message trailers.
0050  *
0051  * Struct members under the private comment are private, subject to change
0052  * and should not be used by callers.
0053  */
0054 typedef struct {
0055   git_message_trailer *trailers;
0056   size_t count;
0057
0058   /* private */
0059   char *_trailer_block;
0060 } git_message_trailer_array;
0061
0062 /**
0063  * Parse trailers out of a message, filling the array pointed to by +arr+.
0064  *
0065  * Trailers are key/value pairs in the last paragraph of a message, not
0066  * including any patches or conflicts that may be present.
0067  *
0068  * @param arr A pre-allocated git_message_trailer_array struct to be filled in
0069  *            with any trailers found during parsing.
0070  * @param message The message to be parsed
0071  * @return 0 on success, or non-zero on error.
0072  */
0073 GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char *message);
0074
0075 /**
0076  * Clean's up any allocated memory in the git_message_trailer_array filled by
0077  * a call to git_message_trailers.
0078  *
0079  * @param arr The trailer to free.
0080  */
0081 GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr);
0082
0083 /** @} */
0084 GIT_END_DECL
0085
0086 #endif /* INCLUDE_git_message_h__ */