include/git2/message.h

   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__ */