Hash :
3f04219f
Author :
Date :
2015-12-23T10:23:08
merge driver: introduce custom merge drivers Consumers can now register custom merged drivers with `git_merge_driver_register`. This allows consumers to support the merge drivers, as configured in `.gitattributes`. Consumers will be asked to perform the file-level merge when a custom driver is configured.
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 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
/*
* 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_sys_git_merge_h__
#define INCLUDE_sys_git_merge_h__
/**
* @file git2/sys/merge.h
* @brief Git merge driver backend and plugin routines
* @defgroup git_backend Git custom backend APIs
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
typedef struct git_merge_driver git_merge_driver;
/**
* Look up a merge driver by name
*
* @param name The name of the merge driver
* @return Pointer to the merge driver object or NULL if not found
*/
GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name);
#define GIT_MERGE_DRIVER_TEXT "text"
#define GIT_MERGE_DRIVER_BINARY "binary"
#define GIT_MERGE_DRIVER_UNION "union"
/**
* A merge driver source represents the file to be merged
*/
typedef struct git_merge_driver_source git_merge_driver_source;
/** Get the repository that the source data is coming from. */
GIT_EXTERN(git_repository *) git_merge_driver_source_repo(
const git_merge_driver_source *src);
/** Gets the ancestor of the file to merge. */
GIT_EXTERN(git_index_entry *) git_merge_driver_source_ancestor(
const git_merge_driver_source *src);
/** Gets the ours side of the file to merge. */
GIT_EXTERN(git_index_entry *) git_merge_driver_source_ours(
const git_merge_driver_source *src);
/** Gets the theirs side of the file to merge. */
GIT_EXTERN(git_index_entry *) git_merge_driver_source_theirs(
const git_merge_driver_source *src);
/** Gets the merge file options that the merge was invoked with */
GIT_EXTERN(git_merge_file_options *) git_merge_driver_source_file_options(
const git_merge_driver_source *src);
/*
* struct git_merge_driver
*
* The merge driver lifecycle:
* - initialize - first use of merge driver
* - shutdown - merge driver removed/unregistered from system
* - check - considering using merge driver for file
* - apply - apply merge driver to the file
* - cleanup - done with file
*/
/**
* Initialize callback on merge driver
*
* Specified as `driver.initialize`, this is an optional callback invoked
* before a merge driver is first used. It will be called once at most.
*
* If non-NULL, the merge driver's `initialize` callback will be invoked
* right before the first use of the driver, so you can defer expensive
* initialization operations (in case libgit2 is being used in a way that
* doesn't need the merge driver).
*/
typedef int (*git_merge_driver_init_fn)(git_merge_driver *self);
/**
* Shutdown callback on merge driver
*
* Specified as `driver.shutdown`, this is an optional callback invoked
* when the merge driver is unregistered or when libgit2 is shutting down.
* It will be called once at most and should release resources as needed.
* This may be called even if the `initialize` callback was not made.
*
* Typically this function will free the `git_merge_driver` object itself.
*/
typedef void (*git_merge_driver_shutdown_fn)(git_merge_driver *self);
/**
* Callback to decide if a given conflict can be resolved with this merge
* driver.
*
* Specified as `driver.check`, this is an optional callback that checks
* if the given conflict can be resolved with this merge driver.
*
* It should return 0 if the merge driver should be applied (i.e. success),
* `GIT_PASSTHROUGH` if the driver is not available, which is the equivalent
* of an unregistered or nonexistent merge driver. In this case, the default
* (`text`) driver will be run. This is useful if you register a wildcard
* merge driver but are not interested in handling the requested file (and
* should just fallback). The driver can also return `GIT_EMERGECONFLICT`
* if the driver is not able to produce a merge result, and the file will
* remain conflicted. Any other errors will fail and return to the caller.
*
* The `name` will be set to the name of the driver as configured in the
* attributes.
*
* The `src` contains the data about the file to be merged.
*
* The `payload` will be a pointer to a reference payload for the driver.
* This will start as NULL, but `check` can assign to this pointer for
* later use by the `apply` callback. Note that the value should be heap
* allocated (not stack), so that it doesn't go away before the `apply`
* callback can use it. If a driver allocates and assigns a value to the
* `payload`, it will need a `cleanup` callback to free the payload.
*/
typedef int (*git_merge_driver_check_fn)(
git_merge_driver *self,
void **payload,
const char *name,
const git_merge_driver_source *src);
/**
* Callback to actually perform the merge.
*
* Specified as `driver.apply`, this is the callback that actually does the
* merge. If it can successfully perform a merge, it should populate
* `path_out` with a pointer to the filename to accept, `mode_out` with
* the resultant mode, and `merged_out` with the buffer of the merged file
* and then return 0. If the driver returns `GIT_PASSTHROUGH`, then the
* default merge driver should instead be run. It can also return
* `GIT_EMERGECONFLICT` if the driver is not able to produce a merge result,
* and the file will remain conflicted. Any other errors will fail and
* return to the caller.
*
* The `src` contains the data about the file to be merged.
*
* The `payload` value will refer to any payload that was set by the
* `check` callback. It may be read from or written to as needed.
*/
typedef int (*git_merge_driver_apply_fn)(
git_merge_driver *self,
void **payload,
const char **path_out,
uint32_t *mode_out,
git_buf *merged_out,
const git_merge_driver_source *src);
/**
* Callback to clean up after merge has been performed.
*
* Specified as `driver.cleanup`, this is an optional callback invoked
* after the driver has been run. If the `check` or `apply` callbacks
* allocated a `payload` to keep per-source merge driver state, use this
* callback to free that payload and release resources as required.
*/
typedef void (*git_merge_driver_cleanup_fn)(
git_merge_driver *self,
void *payload);
/**
* Merge driver structure used to register custom merge drivers.
*
* To associate extra data with a driver, allocate extra data and put the
* `git_merge_driver` struct at the start of your data buffer, then cast
* the `self` pointer to your larger structure when your callback is invoked.
*
* `version` should be set to GIT_MERGE_DRIVER_VERSION
*
* The `initialize`, `shutdown`, `check`, `apply`, and `cleanup`
* callbacks are all documented above with the respective function pointer
* typedefs.
*/
struct git_merge_driver {
unsigned int version;
git_merge_driver_init_fn initialize;
git_merge_driver_shutdown_fn shutdown;
git_merge_driver_check_fn check;
git_merge_driver_apply_fn apply;
git_merge_driver_cleanup_fn cleanup;
};
#define GIT_MERGE_DRIVER_VERSION 1
/**
* Register a merge driver under a given name.
*
* As mentioned elsewhere, the initialize callback will not be invoked
* immediately. It is deferred until the driver is used in some way.
*
* Currently the merge driver registry is not thread safe, so any
* registering or deregistering of merge drivers must be done outside of
* any possible usage of the drivers (i.e. during application setup or
* shutdown).
*
* @param name The name of this driver to match an attribute. Attempting
* to register with an in-use name will return GIT_EEXISTS.
* @param driver The merge driver definition. This pointer will be stored
* as is by libgit2 so it must be a durable allocation (either
* static or on the heap).
* @return 0 on successful registry, error code <0 on failure
*/
GIT_EXTERN(int) git_merge_driver_register(
const char *name, git_merge_driver *driver);
/**
* Remove the merge driver with the given name.
*
* Attempting to remove the builtin libgit2 merge drivers is not permitted
* and will return an error.
*
* Currently the merge driver registry is not thread safe, so any
* registering or deregistering of drivers must be done outside of any
* possible usage of the drivers (i.e. during application setup or shutdown).
*
* @param name The name under which the merge driver was registered
* @return 0 on success, error code <0 on failure
*/
GIT_EXTERN(int) git_merge_driver_unregister(const char *name);
/** @} */
GIT_END_DECL
#endif