| /* |
| * 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__ |
| |
| #include "git2/common.h" |
| #include "git2/types.h" |
| #include "git2/index.h" |
| #include "git2/merge.h" |
| |
| /** |
| * @file git2/sys/merge.h |
| * @brief Git merge driver backend and plugin routines |
| * @defgroup git_merge Git merge driver 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(const git_repository *) git_merge_driver_source_repo( |
| const git_merge_driver_source *src); |
| |
| /** Gets the ancestor of the file to merge. */ |
| GIT_EXTERN(const 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(const 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(const 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(const git_merge_file_options *) git_merge_driver_source_file_options( |
| const git_merge_driver_source *src); |
| |
| |
| /** |
| * 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 |
| * per library lifetime. |
| * |
| * 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_CALLBACK(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_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); |
| |
| /** |
| * Callback to 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 `filter_name` contains the name of the filter that was invoked, as |
| * specified by the file's attributes. |
| * |
| * The `src` contains the data about the file to be merged. |
| */ |
| typedef int GIT_CALLBACK(git_merge_driver_apply_fn)( |
| git_merge_driver *self, |
| const char **path_out, |
| uint32_t *mode_out, |
| git_buf *merged_out, |
| const char *filter_name, |
| const git_merge_driver_source *src); |
| |
| /** |
| * 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. |
| */ |
| struct git_merge_driver { |
| /** The `version` should be set to `GIT_MERGE_DRIVER_VERSION`. */ |
| unsigned int version; |
| |
| /** Called when the merge driver is first used for any file. */ |
| git_merge_driver_init_fn initialize; |
| |
| /** Called when the merge driver is unregistered from the system. */ |
| git_merge_driver_shutdown_fn shutdown; |
| |
| /** |
| * Called to merge the contents of a conflict. If this function |
| * returns `GIT_PASSTHROUGH` then the default (`text`) merge driver |
| * will instead be invoked. If this function returns |
| * `GIT_EMERGECONFLICT` then the file will remain conflicted. |
| */ |
| git_merge_driver_apply_fn apply; |
| }; |
| |
| #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 |