Hash :
d91d2968
Author :
Date :
2018-06-14T16:49:48
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
/*
* 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_mailmap_h__
#define INCLUDE_git_mailmap_h__
#include "common.h"
#include "types.h"
#include "buffer.h"
/**
* @file git2/mailmap.h
* @brief Mailmap parsing routines
* @defgroup git_mailmap Git mailmap routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Allocate a new mailmap object.
*
* This object is empty, so you'll have to add a mailmap file before you can do
* anything with it. The mailmap must be freed with 'git_mailmap_free'.
*
* @param out pointer to store the new mailmap
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_new(git_mailmap **out);
/**
* Free the mailmap and its associated memory.
*
* @param mm the mailmap to free
*/
GIT_EXTERN(void) git_mailmap_free(git_mailmap *mm);
/**
* Add a single entry to the given mailmap object. If the entry already exists,
* it will be replaced with the new entry.
*
* @param mm mailmap to add the entry to
* @param real_name the real name to use, or NULL
* @param real_email the real email to use, or NULL
* @param replace_name the name to replace, or NULL
* @param replace_email the email to replace
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_add_entry(
git_mailmap *mm, const char *real_name, const char *real_email,
const char *replace_name, const char *replace_email);
/**
* Parse mailmap entries from a buffer.
*
* @param mm mailmap to add the entries to
* @param buf the buffer to read the mailmap file from
* @param len the length of the input buffer [optional: 0 defaults to 'strlen']
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_add_buffer(
git_mailmap *mm, const char *buf, size_t len);
/**
* Create a new mailmap instance containing a single mailmap file
*
* This method is a simple utility wrapper for the following sequence
* of calls:
* - git_mailmap_new
* - git_mailmap_add_buffer
*
* @param out pointer to store the new mailmap
* @param buf buffer to parse the mailmap from
* @param len the length of the input buffer [optional: 0 defaults to 'strlen']
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_from_buffer(
git_mailmap **out, const char *buf, size_t len);
/**
* Create a new mailmap instance from a repository, loading mailmap files based
* on the repository's configuration.
*
* Mailmaps are loaded in the following order:
* 1. '.mailmap' in the root of the repository's working directory, if present.
* 2. The blob object identified by the 'mailmap.blob' config entry, if set.
* [NOTE: 'mailmap.blob' defaults to 'HEAD:.mailmap' in bare repositories]
* 3. The path in the 'mailmap.file' config entry, if set.
*
* @param out pointer to store the new mailmap
* @param repo repository to load mailmap information from
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_from_repository(
git_mailmap **out, git_repository *repo);
/**
* Resolve a name and email to the corresponding real name and email.
*
* The lifetime of the strings are tied to `mm`, `name`, and `email` parameters.
*
* @param real_name pointer to store the real name
* @param real_email pointer to store the real email
* @param mm the mailmap to perform a lookup with (may be NULL)
* @param name the name to look up
* @param email the email to look up
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_resolve(
const char **real_name, const char **real_email,
const git_mailmap *mm, const char *name, const char *email);
/**
* Resolve a signature to use real names and emails with a mailmap.
*
* Call `git_signature_free()` to free the data.
*
* @param out new signature
* @param mm mailmap to resolve with
* @param sig signature to resolve
* @return 0 or an error code
*/
GIT_EXTERN(int) git_mailmap_resolve_signature(
git_signature **out, const git_mailmap *mm, const git_signature *sig);
/** @} */
GIT_END_DECL
#endif