git2/sys/merge.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_sys_git_merge_h__
0008 #define INCLUDE_sys_git_merge_h__
0009
0010 #include "git2/common.h"
0011 #include "git2/types.h"
0012 #include "git2/index.h"
0013 #include "git2/merge.h"
0014
0015 /**
0016  * @file git2/sys/merge.h
0017  * @brief Git merge driver backend and plugin routines
0018  * @defgroup git_merge Git merge driver APIs
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 typedef struct git_merge_driver git_merge_driver;
0025
0026 /**
0027  * Look up a merge driver by name
0028  *
0029  * @param name The name of the merge driver
0030  * @return Pointer to the merge driver object or NULL if not found
0031  */
0032 GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name);
0033
0034 #define GIT_MERGE_DRIVER_TEXT   "text"
0035 #define GIT_MERGE_DRIVER_BINARY "binary"
0036 #define GIT_MERGE_DRIVER_UNION  "union"
0037
0038 /**
0039  * A merge driver source represents the file to be merged
0040  */
0041 typedef struct git_merge_driver_source git_merge_driver_source;
0042
0043 /** Get the repository that the source data is coming from. */
0044 GIT_EXTERN(git_repository *) git_merge_driver_source_repo(
0045     const git_merge_driver_source *src);
0046
0047 /** Gets the ancestor of the file to merge. */
0048 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor(
0049     const git_merge_driver_source *src);
0050
0051 /** Gets the ours side of the file to merge. */
0052 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours(
0053     const git_merge_driver_source *src);
0054
0055 /** Gets the theirs side of the file to merge. */
0056 GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs(
0057     const git_merge_driver_source *src);
0058
0059 /** Gets the merge file options that the merge was invoked with */
0060 GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options(
0061     const git_merge_driver_source *src);
0062
0063
0064 /**
0065  * Initialize callback on merge driver
0066  *
0067  * Specified as `driver.initialize`, this is an optional callback invoked
0068  * before a merge driver is first used.  It will be called once at most
0069  * per library lifetime.
0070  *
0071  * If non-NULL, the merge driver's `initialize` callback will be invoked
0072  * right before the first use of the driver, so you can defer expensive
0073  * initialization operations (in case libgit2 is being used in a way that
0074  * doesn't need the merge driver).
0075  */
0076 typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self);
0077
0078 /**
0079  * Shutdown callback on merge driver
0080  *
0081  * Specified as `driver.shutdown`, this is an optional callback invoked
0082  * when the merge driver is unregistered or when libgit2 is shutting down.
0083  * It will be called once at most and should release resources as needed.
0084  * This may be called even if the `initialize` callback was not made.
0085  *
0086  * Typically this function will free the `git_merge_driver` object itself.
0087  */
0088 typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self);
0089
0090 /**
0091  * Callback to perform the merge.
0092  *
0093  * Specified as `driver.apply`, this is the callback that actually does the
0094  * merge.  If it can successfully perform a merge, it should populate
0095  * `path_out` with a pointer to the filename to accept, `mode_out` with
0096  * the resultant mode, and `merged_out` with the buffer of the merged file
0097  * and then return 0.  If the driver returns `GIT_PASSTHROUGH`, then the
0098  * default merge driver should instead be run.  It can also return
0099  * `GIT_EMERGECONFLICT` if the driver is not able to produce a merge result,
0100  * and the file will remain conflicted.  Any other errors will fail and
0101  * return to the caller.
0102  *
0103  * The `filter_name` contains the name of the filter that was invoked, as
0104  * specified by the file's attributes.
0105  *
0106  * The `src` contains the data about the file to be merged.
0107  */
0108 typedef int GIT_CALLBACK(git_merge_driver_apply_fn)(
0109     git_merge_driver *self,
0110     const char **path_out,
0111     uint32_t *mode_out,
0112     git_buf *merged_out,
0113     const char *filter_name,
0114     const git_merge_driver_source *src);
0115
0116 /**
0117  * Merge driver structure used to register custom merge drivers.
0118  *
0119  * To associate extra data with a driver, allocate extra data and put the
0120  * `git_merge_driver` struct at the start of your data buffer, then cast
0121  * the `self` pointer to your larger structure when your callback is invoked.
0122  */
0123 struct git_merge_driver {
0124     /** The `version` should be set to `GIT_MERGE_DRIVER_VERSION`. */
0125     unsigned int                 version;
0126
0127     /** Called when the merge driver is first used for any file. */
0128     git_merge_driver_init_fn     initialize;
0129
0130     /** Called when the merge driver is unregistered from the system. */
0131     git_merge_driver_shutdown_fn shutdown;
0132
0133     /**
0134      * Called to merge the contents of a conflict.  If this function
0135      * returns `GIT_PASSTHROUGH` then the default (`text`) merge driver
0136      * will instead be invoked.  If this function returns
0137      * `GIT_EMERGECONFLICT` then the file will remain conflicted.
0138      */
0139     git_merge_driver_apply_fn    apply;
0140 };
0141
0142 #define GIT_MERGE_DRIVER_VERSION 1
0143
0144 /**
0145  * Register a merge driver under a given name.
0146  *
0147  * As mentioned elsewhere, the initialize callback will not be invoked
0148  * immediately.  It is deferred until the driver is used in some way.
0149  *
0150  * Currently the merge driver registry is not thread safe, so any
0151  * registering or deregistering of merge drivers must be done outside of
0152  * any possible usage of the drivers (i.e. during application setup or
0153  * shutdown).
0154  *
0155  * @param name The name of this driver to match an attribute.  Attempting
0156  *          to register with an in-use name will return GIT_EEXISTS.
0157  * @param driver The merge driver definition.  This pointer will be stored
0158  *          as is by libgit2 so it must be a durable allocation (either
0159  *          static or on the heap).
0160  * @return 0 on successful registry, error code <0 on failure
0161  */
0162 GIT_EXTERN(int) git_merge_driver_register(
0163     const char *name, git_merge_driver *driver);
0164
0165 /**
0166  * Remove the merge driver with the given name.
0167  *
0168  * Attempting to remove the builtin libgit2 merge drivers is not permitted
0169  * and will return an error.
0170  *
0171  * Currently the merge driver registry is not thread safe, so any
0172  * registering or deregistering of drivers must be done outside of any
0173  * possible usage of the drivers (i.e. during application setup or shutdown).
0174  *
0175  * @param name The name under which the merge driver was registered
0176  * @return 0 on success, error code <0 on failure
0177  */
0178 GIT_EXTERN(int) git_merge_driver_unregister(const char *name);
0179
0180 /** @} */
0181 GIT_END_DECL
0182 #endif