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_mailmap_h__ 8 #define INCLUDE_git_mailmap_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "buffer.h" 13 14 /** 15 * @file git2/mailmap.h 16 * @brief Mailmap parsing routines 17 * @defgroup git_mailmap Git mailmap routines 18 * @ingroup Git 19 * @{ 20 */ 21 GIT_BEGIN_DECL 22 23 /** 24 * Allocate a new mailmap object. 25 * 26 * This object is empty, so you'll have to add a mailmap file before you can do 27 * anything with it. The mailmap must be freed with 'git_mailmap_free'. 28 * 29 * @param out pointer to store the new mailmap 30 * @return 0 on success, or an error code 31 */ 32 GIT_EXTERN(int) git_mailmap_new(git_mailmap **out); 33 34 /** 35 * Free the mailmap and its associated memory. 36 * 37 * @param mm the mailmap to free 38 */ 39 GIT_EXTERN(void) git_mailmap_free(git_mailmap *mm); 40 41 /** 42 * Add a single entry to the given mailmap object. If the entry already exists, 43 * it will be replaced with the new entry. 44 * 45 * @param mm mailmap to add the entry to 46 * @param real_name the real name to use, or NULL 47 * @param real_email the real email to use, or NULL 48 * @param replace_name the name to replace, or NULL 49 * @param replace_email the email to replace 50 * @return 0 on success, or an error code 51 */ 52 GIT_EXTERN(int) git_mailmap_add_entry( 53 git_mailmap *mm, const char *real_name, const char *real_email, 54 const char *replace_name, const char *replace_email); 55 56 /** 57 * Create a new mailmap instance containing a single mailmap file 58 * 59 * @param out pointer to store the new mailmap 60 * @param buf buffer to parse the mailmap from 61 * @param len the length of the input buffer 62 * @return 0 on success, or an error code 63 */ 64 GIT_EXTERN(int) git_mailmap_from_buffer( 65 git_mailmap **out, const char *buf, size_t len); 66 67 /** 68 * Create a new mailmap instance from a repository, loading mailmap files based 69 * on the repository's configuration. 70 * 71 * Mailmaps are loaded in the following order: 72 * 1. '.mailmap' in the root of the repository's working directory, if present. 73 * 2. The blob object identified by the 'mailmap.blob' config entry, if set. 74 * [NOTE: 'mailmap.blob' defaults to 'HEAD:.mailmap' in bare repositories] 75 * 3. The path in the 'mailmap.file' config entry, if set. 76 * 77 * @param out pointer to store the new mailmap 78 * @param repo repository to load mailmap information from 79 * @return 0 on success, or an error code 80 */ 81 GIT_EXTERN(int) git_mailmap_from_repository( 82 git_mailmap **out, git_repository *repo); 83 84 /** 85 * Resolve a name and email to the corresponding real name and email. 86 * 87 * The lifetime of the strings are tied to `mm`, `name`, and `email` parameters. 88 * 89 * @param real_name pointer to store the real name 90 * @param real_email pointer to store the real email 91 * @param mm the mailmap to perform a lookup with (may be NULL) 92 * @param name the name to look up 93 * @param email the email to look up 94 * @return 0 on success, or an error code 95 */ 96 GIT_EXTERN(int) git_mailmap_resolve( 97 const char **real_name, const char **real_email, 98 const git_mailmap *mm, const char *name, const char *email); 99 100 /** 101 * Resolve a signature to use real names and emails with a mailmap. 102 * 103 * Call `git_signature_free()` to free the data. 104 * 105 * @param out new signature 106 * @param mm mailmap to resolve with 107 * @param sig signature to resolve 108 * @return 0 or an error code 109 */ 110 GIT_EXTERN(int) git_mailmap_resolve_signature( 111 git_signature **out, const git_mailmap *mm, const git_signature *sig); 112 113 /** @} */ 114 GIT_END_DECL 115 #endif 116