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_sys_git_merge_h__ 8 #define INCLUDE_sys_git_merge_h__ 9 10 #include "git2/common.h" 11 #include "git2/types.h" 12 #include "git2/index.h" 13 #include "git2/merge.h" 14 15 /** 16 * @file git2/sys/merge.h 17 * @brief Git merge driver backend and plugin routines 18 * @defgroup git_merge Git merge driver APIs 19 * @ingroup Git 20 * @{ 21 */ 22 GIT_BEGIN_DECL 23 24 typedef struct git_merge_driver git_merge_driver; 25 26 /** 27 * Look up a merge driver by name 28 * 29 * @param name The name of the merge driver 30 * @return Pointer to the merge driver object or NULL if not found 31 */ 32 GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name); 33 34 #define GIT_MERGE_DRIVER_TEXT "text" 35 #define GIT_MERGE_DRIVER_BINARY "binary" 36 #define GIT_MERGE_DRIVER_UNION "union" 37 38 /** 39 * A merge driver source represents the file to be merged 40 */ 41 typedef struct git_merge_driver_source git_merge_driver_source; 42 43 /** Get the repository that the source data is coming from. */ 44 GIT_EXTERN(git_repository *) git_merge_driver_source_repo( 45 const git_merge_driver_source *src); 46 47 /** Gets the ancestor of the file to merge. */ 48 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor( 49 const git_merge_driver_source *src); 50 51 /** Gets the ours side of the file to merge. */ 52 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours( 53 const git_merge_driver_source *src); 54 55 /** Gets the theirs side of the file to merge. */ 56 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs( 57 const git_merge_driver_source *src); 58 59 /** Gets the merge file options that the merge was invoked with */ 60 GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options( 61 const git_merge_driver_source *src); 62 63 64 /** 65 * Initialize callback on merge driver 66 * 67 * Specified as `driver.initialize`, this is an optional callback invoked 68 * before a merge driver is first used. It will be called once at most 69 * per library lifetime. 70 * 71 * If non-NULL, the merge driver's `initialize` callback will be invoked 72 * right before the first use of the driver, so you can defer expensive 73 * initialization operations (in case libgit2 is being used in a way that 74 * doesn't need the merge driver). 75 */ 76 typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self); 77 78 /** 79 * Shutdown callback on merge driver 80 * 81 * Specified as `driver.shutdown`, this is an optional callback invoked 82 * when the merge driver is unregistered or when libgit2 is shutting down. 83 * It will be called once at most and should release resources as needed. 84 * This may be called even if the `initialize` callback was not made. 85 * 86 * Typically this function will free the `git_merge_driver` object itself. 87 */ 88 typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); 89 90 /** 91 * Callback to perform the merge. 92 * 93 * Specified as `driver.apply`, this is the callback that actually does the 94 * merge. If it can successfully perform a merge, it should populate 95 * `path_out` with a pointer to the filename to accept, `mode_out` with 96 * the resultant mode, and `merged_out` with the buffer of the merged file 97 * and then return 0. If the driver returns `GIT_PASSTHROUGH`, then the 98 * default merge driver should instead be run. It can also return 99 * `GIT_EMERGECONFLICT` if the driver is not able to produce a merge result, 100 * and the file will remain conflicted. Any other errors will fail and 101 * return to the caller. 102 * 103 * The `filter_name` contains the name of the filter that was invoked, as 104 * specified by the file's attributes. 105 * 106 * The `src` contains the data about the file to be merged. 107 */ 108 typedef int GIT_CALLBACK(git_merge_driver_apply_fn)( 109 git_merge_driver *self, 110 const char **path_out, 111 uint32_t *mode_out, 112 git_buf *merged_out, 113 const char *filter_name, 114 const git_merge_driver_source *src); 115 116 /** 117 * Merge driver structure used to register custom merge drivers. 118 * 119 * To associate extra data with a driver, allocate extra data and put the 120 * `git_merge_driver` struct at the start of your data buffer, then cast 121 * the `self` pointer to your larger structure when your callback is invoked. 122 */ 123 struct git_merge_driver { 124 /** The `version` should be set to `GIT_MERGE_DRIVER_VERSION`. */ 125 unsigned int version; 126 127 /** Called when the merge driver is first used for any file. */ 128 git_merge_driver_init_fn initialize; 129 130 /** Called when the merge driver is unregistered from the system. */ 131 git_merge_driver_shutdown_fn shutdown; 132 133 /** 134 * Called to merge the contents of a conflict. If this function 135 * returns `GIT_PASSTHROUGH` then the default (`text`) merge driver 136 * will instead be invoked. If this function returns 137 * `GIT_EMERGECONFLICT` then the file will remain conflicted. 138 */ 139 git_merge_driver_apply_fn apply; 140 }; 141 142 #define GIT_MERGE_DRIVER_VERSION 1 143 144 /** 145 * Register a merge driver under a given name. 146 * 147 * As mentioned elsewhere, the initialize callback will not be invoked 148 * immediately. It is deferred until the driver is used in some way. 149 * 150 * Currently the merge driver registry is not thread safe, so any 151 * registering or deregistering of merge drivers must be done outside of 152 * any possible usage of the drivers (i.e. during application setup or 153 * shutdown). 154 * 155 * @param name The name of this driver to match an attribute. Attempting 156 * to register with an in-use name will return GIT_EEXISTS. 157 * @param driver The merge driver definition. This pointer will be stored 158 * as is by libgit2 so it must be a durable allocation (either 159 * static or on the heap). 160 * @return 0 on successful registry, error code <0 on failure 161 */ 162 GIT_EXTERN(int) git_merge_driver_register( 163 const char *name, git_merge_driver *driver); 164 165 /** 166 * Remove the merge driver with the given name. 167 * 168 * Attempting to remove the builtin libgit2 merge drivers is not permitted 169 * and will return an error. 170 * 171 * Currently the merge driver registry is not thread safe, so any 172 * registering or deregistering of drivers must be done outside of any 173 * possible usage of the drivers (i.e. during application setup or shutdown). 174 * 175 * @param name The name under which the merge driver was registered 176 * @return 0 on success, error code <0 on failure 177 */ 178 GIT_EXTERN(int) git_merge_driver_unregister(const char *name); 179 180 /** @} */ 181 GIT_END_DECL 182 #endif 183
