libgit2.mailmap source code

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