diff options
Diffstat (limited to 'include/git2/sys')
| -rw-r--r-- | include/git2/sys/alloc.h | 67 | ||||
| -rw-r--r-- | include/git2/sys/commit.h | 80 | ||||
| -rw-r--r-- | include/git2/sys/commit_graph.h | 184 | ||||
| -rw-r--r-- | include/git2/sys/config.h | 130 | ||||
| -rw-r--r-- | include/git2/sys/cred.h | 15 | ||||
| -rw-r--r-- | include/git2/sys/credential.h | 90 | ||||
| -rw-r--r-- | include/git2/sys/diff.h | 94 | ||||
| -rw-r--r-- | include/git2/sys/email.h | 45 | ||||
| -rw-r--r-- | include/git2/sys/filter.h | 353 | ||||
| -rw-r--r-- | include/git2/sys/hashsig.h | 106 | ||||
| -rw-r--r-- | include/git2/sys/index.h | 182 | ||||
| -rw-r--r-- | include/git2/sys/mempack.h | 87 | ||||
| -rw-r--r-- | include/git2/sys/merge.h | 182 | ||||
| -rw-r--r-- | include/git2/sys/midx.h | 78 | ||||
| -rw-r--r-- | include/git2/sys/odb_backend.h | 172 | ||||
| -rw-r--r-- | include/git2/sys/openssl.h | 38 | ||||
| -rw-r--r-- | include/git2/sys/path.h | 64 | ||||
| -rw-r--r-- | include/git2/sys/refdb_backend.h | 361 | ||||
| -rw-r--r-- | include/git2/sys/reflog.h | 21 | ||||
| -rw-r--r-- | include/git2/sys/refs.h | 49 | ||||
| -rw-r--r-- | include/git2/sys/remote.h | 46 | ||||
| -rw-r--r-- | include/git2/sys/repository.h | 180 | ||||
| -rw-r--r-- | include/git2/sys/stream.h | 152 | ||||
| -rw-r--r-- | include/git2/sys/transport.h | 465 |
24 files changed, 3241 insertions, 0 deletions
diff --git a/include/git2/sys/alloc.h b/include/git2/sys/alloc.h new file mode 100644 index 0000000..e7f85b8 --- /dev/null +++ b/include/git2/sys/alloc.h @@ -0,0 +1,67 @@ +/* + * 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_alloc_h__ +#define INCLUDE_sys_git_alloc_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * An instance for a custom memory allocator + * + * Setting the pointers of this structure allows the developer to implement + * custom memory allocators. The global memory allocator can be set by using + * "GIT_OPT_SET_ALLOCATOR" with the `git_libgit2_opts` function. Keep in mind + * that all fields need to be set to a proper function. + */ +typedef struct { + /** Allocate `n` bytes of memory */ + void * GIT_CALLBACK(gmalloc)(size_t n, const char *file, int line); + + /** + * This function shall deallocate the old object `ptr` and return a + * pointer to a new object that has the size specified by `size`. In + * case `ptr` is `NULL`, a new array shall be allocated. + */ + void * GIT_CALLBACK(grealloc)(void *ptr, size_t size, const char *file, int line); + + /** + * This function shall free the memory pointed to by `ptr`. In case + * `ptr` is `NULL`, this shall be a no-op. + */ + void GIT_CALLBACK(gfree)(void *ptr); +} git_allocator; + +/** + * Initialize the allocator structure to use the `stdalloc` pointer. + * + * Set up the structure so that all of its members are using the standard + * "stdalloc" allocator functions. The structure can then be used with + * `git_allocator_setup`. + * + * @param allocator The allocator that is to be initialized. + * @return An error code or 0. + */ +int git_stdalloc_init_allocator(git_allocator *allocator); + +/** + * Initialize the allocator structure to use the `crtdbg` pointer. + * + * Set up the structure so that all of its members are using the "crtdbg" + * allocator functions. Note that this allocator is only available on Windows + * platforms and only if libgit2 is being compiled with "-DMSVC_CRTDBG". + * + * @param allocator The allocator that is to be initialized. + * @return An error code or 0. + */ +int git_win32_crtdbg_init_allocator(git_allocator *allocator); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/commit.h b/include/git2/sys/commit.h new file mode 100644 index 0000000..ba67106 --- /dev/null +++ b/include/git2/sys/commit.h @@ -0,0 +1,80 @@ +/* + * 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_commit_h__ +#define INCLUDE_sys_git_commit_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/sys/commit.h + * @brief Low-level Git commit creation + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create new commit in the repository from a list of `git_oid` values. + * + * See documentation for `git_commit_create()` for information about the + * parameters, as the meaning is identical excepting that `tree` and + * `parents` now take `git_oid`. This is a dangerous API in that nor + * the `tree`, neither the `parents` list of `git_oid`s are checked for + * validity. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_create_from_ids( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_oid *tree, + size_t parent_count, + const git_oid *parents[]); + +/** + * Callback function to return parents for commit. + * + * This is invoked with the count of the number of parents processed so far + * along with the user supplied payload. This should return a git_oid of + * the next parent or NULL if all parents have been provided. + */ +typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, void *payload); + +/** + * Create a new commit in the repository with an callback to supply parents. + * + * See documentation for `git_commit_create()` for information about the + * parameters, as the meaning is identical excepting that `tree` takes a + * `git_oid` and doesn't check for validity, and `parent_cb` is invoked + * with `parent_payload` and should return `git_oid` values or NULL to + * indicate that all parents are accounted for. + * + * @see git_commit_create + */ +GIT_EXTERN(int) git_commit_create_from_callback( + git_oid *id, + git_repository *repo, + const char *update_ref, + const git_signature *author, + const git_signature *committer, + const char *message_encoding, + const char *message, + const git_oid *tree, + git_commit_parent_callback parent_cb, + void *parent_payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/commit_graph.h b/include/git2/sys/commit_graph.h new file mode 100644 index 0000000..06e045f --- /dev/null +++ b/include/git2/sys/commit_graph.h @@ -0,0 +1,184 @@ +/* + * 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_commit_graph_h__ +#define INCLUDE_sys_git_commit_graph_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/commit_graph.h + * @brief Git commit-graph + * @defgroup git_commit_graph Git commit-graph APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Opens a `git_commit_graph` from a path to an objects directory. + * + * This finds, opens, and validates the `commit-graph` file. + * + * @param cgraph_out the `git_commit_graph` struct to initialize. + * @param objects_dir the path to a git objects directory. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_commit_graph_open( + git_commit_graph **cgraph_out, + const char *objects_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Frees commit-graph data. This should only be called when memory allocated + * using `git_commit_graph_open` is not returned to libgit2 because it was not + * associated with the ODB through a successful call to + * `git_odb_set_commit_graph`. + * + * @param cgraph the commit-graph object to free. If NULL, no action is taken. + */ +GIT_EXTERN(void) git_commit_graph_free(git_commit_graph *cgraph); + +/** + * Create a new writer for `commit-graph` files. + * + * @param out Location to store the writer pointer. + * @param objects_info_dir The `objects/info` directory. + * The `commit-graph` file will be written in this directory. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_new( + git_commit_graph_writer **out, + const char *objects_info_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Free the commit-graph writer and its resources. + * + * @param w The writer to free. If NULL no action is taken. + */ +GIT_EXTERN(void) git_commit_graph_writer_free(git_commit_graph_writer *w); + +/** + * Add an `.idx` file (associated to a packfile) to the writer. + * + * @param w The writer. + * @param repo The repository that owns the `.idx` file. + * @param idx_path The path of an `.idx` file. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_add_index_file( + git_commit_graph_writer *w, + git_repository *repo, + const char *idx_path); + +/** + * Add a revwalk to the writer. This will add all the commits from the revwalk + * to the commit-graph. + * + * @param w The writer. + * @param walk The git_revwalk. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_add_revwalk( + git_commit_graph_writer *w, + git_revwalk *walk); + + +/** + * The strategy to use when adding a new set of commits to a pre-existing + * commit-graph chain. + */ +typedef enum { + /** + * Do not split commit-graph files. The other split strategy-related option + * fields are ignored. + */ + GIT_COMMIT_GRAPH_SPLIT_STRATEGY_SINGLE_FILE = 0 +} git_commit_graph_split_strategy_t; + +/** + * Options structure for + * `git_commit_graph_writer_commit`/`git_commit_graph_writer_dump`. + * + * Initialize with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. Alternatively, you + * can use `git_commit_graph_writer_options_init`. + */ +typedef struct { + unsigned int version; + + /** + * The strategy to use when adding new commits to a pre-existing commit-graph + * chain. + */ + git_commit_graph_split_strategy_t split_strategy; + + /** + * The number of commits in level N is less than X times the number of + * commits in level N + 1. Default is 2. + */ + float size_multiple; + + /** + * The number of commits in level N + 1 is more than C commits. + * Default is 64000. + */ + size_t max_commits; +} git_commit_graph_writer_options; + +#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1 +#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \ + GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \ + } + +/** + * Initialize git_commit_graph_writer_options structure + * + * Initializes a `git_commit_graph_writer_options` with default values. Equivalent to + * creating an instance with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. + * + * @param opts The `git_commit_graph_writer_options` struct to initialize. + * @param version The struct version; pass `GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_commit_graph_writer_options_init( + git_commit_graph_writer_options *opts, + unsigned int version); + +/** + * Write a `commit-graph` file to a file. + * + * @param w The writer + * @param opts Pointer to git_commit_graph_writer_options struct. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_commit( + git_commit_graph_writer *w, + git_commit_graph_writer_options *opts); + +/** + * Dump the contents of the `commit-graph` to an in-memory buffer. + * + * @param buffer Buffer where to store the contents of the `commit-graph`. + * @param w The writer. + * @param opts Pointer to git_commit_graph_writer_options struct. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_commit_graph_writer_dump( + git_buf *buffer, + git_commit_graph_writer *w, + git_commit_graph_writer_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/config.h b/include/git2/sys/config.h new file mode 100644 index 0000000..0a9005e --- /dev/null +++ b/include/git2/sys/config.h @@ -0,0 +1,130 @@ +/* + * 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_config_backend_h__ +#define INCLUDE_sys_git_config_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/config.h" + +/** + * @file git2/sys/config.h + * @brief Git config backend routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Every iterator must have this struct as its first element, so the + * API can talk to it. You'd define your iterator as + * + * struct my_iterator { + * git_config_iterator parent; + * ... + * } + * + * and assign `iter->parent.backend` to your `git_config_backend`. + */ +struct git_config_iterator { + git_config_backend *backend; + unsigned int flags; + + /** + * Return the current entry and advance the iterator. The + * memory belongs to the library. + */ + int GIT_CALLBACK(next)(git_config_entry **entry, git_config_iterator *iter); + + /** + * Free the iterator + */ + void GIT_CALLBACK(free)(git_config_iterator *iter); +}; + +/** + * Generic backend that implements the interface to + * access a configuration file + */ +struct git_config_backend { + unsigned int version; + /** True if this backend is for a snapshot */ + int readonly; + struct git_config *cfg; + + /* Open means open the file/database and parse if necessary */ + int GIT_CALLBACK(open)(struct git_config_backend *, git_config_level_t level, const git_repository *repo); + int GIT_CALLBACK(get)(struct git_config_backend *, const char *key, git_config_entry **entry); + int GIT_CALLBACK(set)(struct git_config_backend *, const char *key, const char *value); + int GIT_CALLBACK(set_multivar)(git_config_backend *cfg, const char *name, const char *regexp, const char *value); + int GIT_CALLBACK(del)(struct git_config_backend *, const char *key); + int GIT_CALLBACK(del_multivar)(struct git_config_backend *, const char *key, const char *regexp); + int GIT_CALLBACK(iterator)(git_config_iterator **, struct git_config_backend *); + /** Produce a read-only version of this backend */ + int GIT_CALLBACK(snapshot)(struct git_config_backend **, struct git_config_backend *); + /** + * Lock this backend. + * + * Prevent any writes to the data store backing this + * backend. Any updates must not be visible to any other + * readers. + */ + int GIT_CALLBACK(lock)(struct git_config_backend *); + /** + * Unlock the data store backing this backend. If success is + * true, the changes should be committed, otherwise rolled + * back. + */ + int GIT_CALLBACK(unlock)(struct git_config_backend *, int success); + void GIT_CALLBACK(free)(struct git_config_backend *); +}; +#define GIT_CONFIG_BACKEND_VERSION 1 +#define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION} + +/** + * Initializes a `git_config_backend` with default values. Equivalent to + * creating an instance with GIT_CONFIG_BACKEND_INIT. + * + * @param backend the `git_config_backend` struct to initialize. + * @param version Version of struct; pass `GIT_CONFIG_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_config_init_backend( + git_config_backend *backend, + unsigned int version); + +/** + * Add a generic config file instance to an existing config + * + * Note that the configuration object will free the file + * automatically. + * + * Further queries on this config object will access each + * of the config file instances in order (instances with + * a higher priority level will be accessed first). + * + * @param cfg the configuration to add the file to + * @param file the configuration file (backend) to add + * @param level the priority level of the backend + * @param repo optional repository to allow parsing of + * conditional includes + * @param force if a config file already exists for the given + * priority level, replace it + * @return 0 on success, GIT_EEXISTS when adding more than one file + * for a given priority level (and force_replace set to 0), or error code + */ +GIT_EXTERN(int) git_config_add_backend( + git_config *cfg, + git_config_backend *file, + git_config_level_t level, + const git_repository *repo, + int force); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/cred.h b/include/git2/sys/cred.h new file mode 100644 index 0000000..4d2a59a --- /dev/null +++ b/include/git2/sys/cred.h @@ -0,0 +1,15 @@ +/* + * 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_cred_h__ +#define INCLUDE_sys_git_cred_h__ + +/* These declarations have moved. */ +#ifndef GIT_DEPRECATE_HARD +# include "git2/sys/credential.h" +#endif + +#endif diff --git a/include/git2/sys/credential.h b/include/git2/sys/credential.h new file mode 100644 index 0000000..bb4c9f9 --- /dev/null +++ b/include/git2/sys/credential.h @@ -0,0 +1,90 @@ +/* + * 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_credential_h__ +#define INCLUDE_sys_git_credential_h__ + +#include "git2/common.h" +#include "git2/credential.h" + +/** + * @file git2/sys/cred.h + * @brief Git credentials low-level implementation + * @defgroup git_credential Git credentials low-level implementation + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * The base structure for all credential types + */ +struct git_credential { + git_credential_t credtype; /**< A type of credential */ + + /** The deallocator for this type of credentials */ + void GIT_CALLBACK(free)(git_credential *cred); +}; + +/** A plaintext username and password */ +struct git_credential_userpass_plaintext { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *password; /**< The password to use */ +}; + +/** Username-only credential information */ +struct git_credential_username { + git_credential parent; /**< The parent credential */ + char username[1]; /**< The username to authenticate as */ +}; + +/** + * A ssh key from disk + */ +struct git_credential_ssh_key { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The path to a public key */ + char *privatekey; /**< The path to a private key */ + char *passphrase; /**< Passphrase to decrypt the private key */ +}; + +/** + * Keyboard-interactive based ssh authentication + */ +struct git_credential_ssh_interactive { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + + /** + * Callback used for authentication. + */ + git_credential_ssh_interactive_cb prompt_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +/** + * A key with a custom signature function + */ +struct git_credential_ssh_custom { + git_credential parent; /**< The parent credential */ + char *username; /**< The username to authenticate as */ + char *publickey; /**< The public key data */ + size_t publickey_len; /**< Length of the public key */ + + /** + * Callback used to sign the data. + */ + git_credential_sign_cb sign_callback; + + void *payload; /**< Payload passed to prompt_callback */ +}; + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/diff.h b/include/git2/sys/diff.h new file mode 100644 index 0000000..aefd7b9 --- /dev/null +++ b/include/git2/sys/diff.h @@ -0,0 +1,94 @@ +/* + * 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_diff_h__ +#define INCLUDE_sys_git_diff_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/diff.h" +#include "git2/status.h" + +/** + * @file git2/sys/diff.h + * @brief Low-level Git diff utilities + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Diff print callback that writes to a git_buf. + * + * This function is provided not for you to call it directly, but instead + * so you can use it as a function pointer to the `git_diff_print` or + * `git_patch_print` APIs. When using those APIs, you specify a callback + * to actually handle the diff and/or patch data. + * + * Use this callback to easily write that data to a `git_buf` buffer. You + * must pass a `git_buf *` value as the payload to the `git_diff_print` + * and/or `git_patch_print` function. The data will be appended to the + * buffer (after any existing content). + */ +GIT_EXTERN(int) git_diff_print_callback__to_buf( + const git_diff_delta *delta, + const git_diff_hunk *hunk, + const git_diff_line *line, + void *payload); /**< payload must be a `git_buf *` */ + +/** + * Diff print callback that writes to stdio FILE handle. + * + * This function is provided not for you to call it directly, but instead + * so you can use it as a function pointer to the `git_diff_print` or + * `git_patch_print` APIs. When using those APIs, you specify a callback + * to actually handle the diff and/or patch data. + * + * Use this callback to easily write that data to a stdio FILE handle. You + * must pass a `FILE *` value (such as `stdout` or `stderr` or the return + * value from `fopen()`) as the payload to the `git_diff_print` + * and/or `git_patch_print` function. If you pass NULL, this will write + * data to `stdout`. + */ +GIT_EXTERN(int) git_diff_print_callback__to_file_handle( + const git_diff_delta *delta, + const git_diff_hunk *hunk, + const git_diff_line *line, + void *payload); /**< payload must be a `FILE *` */ + + +/** + * Performance data from diffing + */ +typedef struct { + unsigned int version; + size_t stat_calls; /**< Number of stat() calls performed */ + size_t oid_calculations; /**< Number of ID calculations */ +} git_diff_perfdata; + +#define GIT_DIFF_PERFDATA_VERSION 1 +#define GIT_DIFF_PERFDATA_INIT {GIT_DIFF_PERFDATA_VERSION,0,0} + +/** + * Get performance data for a diff object. + * + * @param out Structure to be filled with diff performance data + * @param diff Diff to read performance data from + * @return 0 for success, <0 for error + */ +GIT_EXTERN(int) git_diff_get_perfdata( + git_diff_perfdata *out, const git_diff *diff); + +/** + * Get performance data for diffs from a git_status_list + */ +GIT_EXTERN(int) git_status_list_get_perfdata( + git_diff_perfdata *out, const git_status_list *status); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/email.h b/include/git2/sys/email.h new file mode 100644 index 0000000..6f4a286 --- /dev/null +++ b/include/git2/sys/email.h @@ -0,0 +1,45 @@ +/* + * 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_email_h__ +#define INCLUDE_sys_git_email_h__ + +/** + * @file git2/sys/email.h + * @brief Advanced git email creation routines + * @defgroup git_email Advanced git email creation routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a diff for a commit in mbox format for sending via email. + * + * @param out buffer to store the e-mail patch in + * @param diff the changes to include in the email + * @param patch_idx the patch index + * @param patch_count the total number of patches that will be included + * @param commit_id the commit id for this change + * @param summary the commit message for this change + * @param body optional text to include above the diffstat + * @param author the person who authored this commit + * @param opts email creation options + */ +GIT_EXTERN(int) git_email_create_from_diff( + git_buf *out, + git_diff *diff, + size_t patch_idx, + size_t patch_count, + const git_oid *commit_id, + const char *summary, + const char *body, + const git_signature *author, + const git_email_create_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h new file mode 100644 index 0000000..b375941 --- /dev/null +++ b/include/git2/sys/filter.h @@ -0,0 +1,353 @@ +/* + * 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_filter_h__ +#define INCLUDE_sys_git_filter_h__ + +#include "git2/filter.h" + +/** + * @file git2/sys/filter.h + * @brief Git filter backend and plugin routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Look up a filter by name + * + * @param name The name of the filter + * @return Pointer to the filter object or NULL if not found + */ +GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); + +#define GIT_FILTER_CRLF "crlf" +#define GIT_FILTER_IDENT "ident" + +/** + * This is priority that the internal CRLF filter will be registered with + */ +#define GIT_FILTER_CRLF_PRIORITY 0 + +/** + * This is priority that the internal ident filter will be registered with + */ +#define GIT_FILTER_IDENT_PRIORITY 100 + +/** + * This is priority to use with a custom filter to imitate a core Git + * filter driver, so that it will be run last on checkout and first on + * checkin. You do not have to use this, but it helps compatibility. + */ +#define GIT_FILTER_DRIVER_PRIORITY 200 + +/** + * Create a new empty filter list + * + * Normally you won't use this because `git_filter_list_load` will create + * the filter list for you, but you can use this in combination with the + * `git_filter_lookup` and `git_filter_list_push` functions to assemble + * your own chains of filters. + */ +GIT_EXTERN(int) git_filter_list_new( + git_filter_list **out, + git_repository *repo, + git_filter_mode_t mode, + uint32_t options); + +/** + * Add a filter to a filter list with the given payload. + * + * Normally you won't have to do this because the filter list is created + * by calling the "check" function on registered filters when the filter + * attributes are set, but this does allow more direct manipulation of + * filter lists when desired. + * + * Note that normally the "check" function can set up a payload for the + * filter. Using this function, you can either pass in a payload if you + * know the expected payload format, or you can pass NULL. Some filters + * may fail with a NULL payload. Good luck! + */ +GIT_EXTERN(int) git_filter_list_push( + git_filter_list *fl, git_filter *filter, void *payload); + +/** + * Look up how many filters are in the list + * + * We will attempt to apply all of these filters to any data passed in, + * but note that the filter apply action still has the option of skipping + * data that is passed in (for example, the CRLF filter will skip data + * that appears to be binary). + * + * @param fl A filter list + * @return The number of filters in the list + */ +GIT_EXTERN(size_t) git_filter_list_length(const git_filter_list *fl); + +/** + * A filter source represents a file/blob to be processed + */ +typedef struct git_filter_source git_filter_source; + +/** + * Get the repository that the source data is coming from. + */ +GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src); + +/** + * Get the path that the source data is coming from. + */ +GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src); + +/** + * Get the file mode of the source file + * If the mode is unknown, this will return 0 + */ +GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); + +/** + * Get the OID of the source + * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then + * this will return NULL. + */ +GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src); + +/** + * Get the git_filter_mode_t to be used + */ +GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src); + +/** + * Get the combination git_filter_flag_t options to be applied + */ +GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src); + +/** + * Initialize callback on filter + * + * Specified as `filter.initialize`, this is an optional callback invoked + * before a filter is first used. It will be called once at most. + * + * If non-NULL, the filter's `initialize` callback will be invoked right + * before the first use of the filter, so you can defer expensive + * initialization operations (in case libgit2 is being used in a way that + * doesn't need the filter). + */ +typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self); + +/** + * Shutdown callback on filter + * + * Specified as `filter.shutdown`, this is an optional callback invoked + * when the filter 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_filter` object itself. + */ +typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); + +/** + * Callback to decide if a given source needs this filter + * + * Specified as `filter.check`, this is an optional callback that checks + * if filtering is needed for a given source. + * + * It should return 0 if the filter should be applied (i.e. success), + * GIT_PASSTHROUGH if the filter should not be applied, or an error code + * to fail out of the filter processing pipeline and return to the caller. + * + * The `attr_values` will be set to the values of any attributes given in + * the filter definition. See `git_filter` below for more detail. + * + * The `payload` will be a pointer to a reference payload for the filter. + * This will start as NULL, but `check` can assign to this pointer for + * later use by the `stream` callback. Note that the value should be heap + * allocated (not stack), so that it doesn't go away before the `stream` + * callback can use it. If a filter allocates and assigns a value to the + * `payload`, it will need a `cleanup` callback to free the payload. + */ +typedef int GIT_CALLBACK(git_filter_check_fn)( + git_filter *self, + void **payload, /* NULL on entry, may be set */ + const git_filter_source *src, + const char **attr_values); + +#ifndef GIT_DEPRECATE_HARD +/** + * Callback to actually perform the data filtering + * + * Specified as `filter.apply`, this is the callback that actually filters + * data. If it successfully writes the output, it should return 0. Like + * `check`, it can return GIT_PASSTHROUGH to indicate that the filter + * doesn't want to run. Other error codes will stop filter processing and + * return to the caller. + * + * 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. + * + * @deprecated use git_filter_stream_fn + */ +typedef int GIT_CALLBACK(git_filter_apply_fn)( + git_filter *self, + void **payload, /* may be read and/or set */ + git_buf *to, + const git_buf *from, + const git_filter_source *src); +#endif + +/** + * Callback to perform the data filtering. + * + * Specified as `filter.stream`, this is a callback that filters data + * in a streaming manner. This function will provide a + * `git_writestream` that will the original data will be written to; + * with that data, the `git_writestream` will then perform the filter + * translation and stream the filtered data out to the `next` location. + */ +typedef int GIT_CALLBACK(git_filter_stream_fn)( + git_writestream **out, + git_filter *self, + void **payload, + const git_filter_source *src, + git_writestream *next); + +/** + * Callback to clean up after filtering has been applied + * + * Specified as `filter.cleanup`, this is an optional callback invoked + * after the filter has been applied. If the `check`, `apply`, or + * `stream` callbacks allocated a `payload` to keep per-source filter + * state, use this callback to free that payload and release resources + * as required. + */ +typedef void GIT_CALLBACK(git_filter_cleanup_fn)( + git_filter *self, + void *payload); + +/** + * Filter structure used to register custom filters. + * + * To associate extra data with a filter, allocate extra data and put the + * `git_filter` struct at the start of your data buffer, then cast the + * `self` pointer to your larger structure when your callback is invoked. + */ +struct git_filter { + /** The `version` field should be set to `GIT_FILTER_VERSION`. */ + unsigned int version; + + /** + * A whitespace-separated list of attribute names to check for this + * filter (e.g. "eol crlf text"). If the attribute name is bare, it + * will be simply loaded and passed to the `check` callback. If it + * has a value (i.e. "name=value"), the attribute must match that + * value for the filter to be applied. The value may be a wildcard + * (eg, "name=*"), in which case the filter will be invoked for any + * value for the given attribute name. See the attribute parameter + * of the `check` callback for the attribute value that was specified. + */ + const char *attributes; + + /** Called when the filter is first used for any file. */ + git_filter_init_fn initialize; + + /** Called when the filter is removed or unregistered from the system. */ + git_filter_shutdown_fn shutdown; + + /** + * Called to determine whether the filter should be invoked for a + * given file. If this function returns `GIT_PASSTHROUGH` then the + * `stream` or `apply` functions will not be invoked and the + * contents will be passed through unmodified. + */ + git_filter_check_fn check; + +#ifdef GIT_DEPRECATE_HARD + void *reserved; +#else + /** + * Provided for backward compatibility; this will apply the + * filter to the given contents in a `git_buf`. Callers should + * provide a `stream` function instead. + */ + git_filter_apply_fn apply; +#endif + + /** + * Called to apply the filter, this function will provide a + * `git_writestream` that will the original data will be + * written to; with that data, the `git_writestream` will then + * perform the filter translation and stream the filtered data + * out to the `next` location. + */ + git_filter_stream_fn stream; + + /** Called when the system is done filtering for a file. */ + git_filter_cleanup_fn cleanup; +}; + +#define GIT_FILTER_VERSION 1 +#define GIT_FILTER_INIT {GIT_FILTER_VERSION} + +/** + * Initializes a `git_filter` with default values. Equivalent to + * creating an instance with GIT_FILTER_INIT. + * + * @param filter the `git_filter` struct to initialize. + * @param version Version the struct; pass `GIT_FILTER_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version); + +/** + * Register a filter under a given name with a given priority. + * + * As mentioned elsewhere, the initialize callback will not be invoked + * immediately. It is deferred until the filter is used in some way. + * + * A filter's attribute checks and `check` and `stream` (or `apply`) + * callbacks will be issued in order of `priority` on smudge (to + * workdir), and in reverse order of `priority` on clean (to odb). + * + * Two filters are preregistered with libgit2: + * - GIT_FILTER_CRLF with priority 0 + * - GIT_FILTER_IDENT with priority 100 + * + * Currently the filter registry is not thread safe, so any registering or + * deregistering of filters must be done outside of any possible usage of + * the filters (i.e. during application setup or shutdown). + * + * @param name A name by which the filter can be referenced. Attempting + * to register with an in-use name will return GIT_EEXISTS. + * @param filter The filter definition. This pointer will be stored as is + * by libgit2 so it must be a durable allocation (either static + * or on the heap). + * @param priority The priority for filter application + * @return 0 on successful registry, error code <0 on failure + */ +GIT_EXTERN(int) git_filter_register( + const char *name, git_filter *filter, int priority); + +/** + * Remove the filter with the given name + * + * Attempting to remove the builtin libgit2 filters is not permitted and + * will return an error. + * + * Currently the filter registry is not thread safe, so any registering or + * deregistering of filters must be done outside of any possible usage of + * the filters (i.e. during application setup or shutdown). + * + * @param name The name under which the filter was registered + * @return 0 on success, error code <0 on failure + */ +GIT_EXTERN(int) git_filter_unregister(const char *name); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/hashsig.h b/include/git2/sys/hashsig.h new file mode 100644 index 0000000..09c19ae --- /dev/null +++ b/include/git2/sys/hashsig.h @@ -0,0 +1,106 @@ +/* + * 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_hashsig_h__ +#define INCLUDE_sys_hashsig_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * Similarity signature of arbitrary text content based on line hashes + */ +typedef struct git_hashsig git_hashsig; + +/** + * Options for hashsig computation + * + * The options GIT_HASHSIG_NORMAL, GIT_HASHSIG_IGNORE_WHITESPACE, + * GIT_HASHSIG_SMART_WHITESPACE are exclusive and should not be combined. + */ +typedef enum { + /** + * Use all data + */ + GIT_HASHSIG_NORMAL = 0, + + /** + * Ignore whitespace + */ + GIT_HASHSIG_IGNORE_WHITESPACE = (1 << 0), + + /** + * Ignore \r and all space after \n + */ + GIT_HASHSIG_SMART_WHITESPACE = (1 << 1), + + /** + * Allow hashing of small files + */ + GIT_HASHSIG_ALLOW_SMALL_FILES = (1 << 2) +} git_hashsig_option_t; + +/** + * Compute a similarity signature for a text buffer + * + * If you have passed the option GIT_HASHSIG_IGNORE_WHITESPACE, then the + * whitespace will be removed from the buffer while it is being processed, + * modifying the buffer in place. Sorry about that! + * + * @param out The computed similarity signature. + * @param buf The input buffer. + * @param buflen The input buffer size. + * @param opts The signature computation options (see above). + * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to + * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or + * error code. + */ +GIT_EXTERN(int) git_hashsig_create( + git_hashsig **out, + const char *buf, + size_t buflen, + git_hashsig_option_t opts); + +/** + * Compute a similarity signature for a text file + * + * This walks through the file, only loading a maximum of 4K of file data at + * a time. Otherwise, it acts just like `git_hashsig_create`. + * + * @param out The computed similarity signature. + * @param path The path to the input file. + * @param opts The signature computation options (see above). + * @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to + * compute a valid signature (unless GIT_HASHSIG_ALLOW_SMALL_FILES is set), or + * error code. + */ +GIT_EXTERN(int) git_hashsig_create_fromfile( + git_hashsig **out, + const char *path, + git_hashsig_option_t opts); + +/** + * Release memory for a content similarity signature + * + * @param sig The similarity signature to free. + */ +GIT_EXTERN(void) git_hashsig_free(git_hashsig *sig); + +/** + * Measure similarity score between two similarity signatures + * + * @param a The first similarity signature to compare. + * @param b The second similarity signature to compare. + * @return [0 to 100] on success as the similarity score, or error code. + */ +GIT_EXTERN(int) git_hashsig_compare( + const git_hashsig *a, + const git_hashsig *b); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/index.h b/include/git2/sys/index.h new file mode 100644 index 0000000..1f6d93f --- /dev/null +++ b/include/git2/sys/index.h @@ -0,0 +1,182 @@ +/* + * 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_index_h__ +#define INCLUDE_sys_git_index_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/index.h + * @brief Low-level Git index manipulation routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** Representation of a rename conflict entry in the index. */ +typedef struct git_index_name_entry { + char *ancestor; + char *ours; + char *theirs; +} git_index_name_entry; + +/** Representation of a resolve undo entry in the index. */ +typedef struct git_index_reuc_entry { + uint32_t mode[3]; + git_oid oid[3]; + char *path; +} git_index_reuc_entry; + +/** @name Conflict Name entry functions + * + * These functions work on rename conflict entries. + */ +/**@{*/ + +/** + * Get the count of filename conflict entries currently in the index. + * + * @param index an existing index object + * @return integer of count of current filename conflict entries + */ +GIT_EXTERN(size_t) git_index_name_entrycount(git_index *index); + +/** + * Get a filename conflict entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param n the position of the entry + * @return a pointer to the filename conflict entry; NULL if out of bounds + */ +GIT_EXTERN(const git_index_name_entry *) git_index_name_get_byindex( + git_index *index, size_t n); + +/** + * Record the filenames involved in a rename conflict. + * + * @param index an existing index object + * @param ancestor the path of the file as it existed in the ancestor + * @param ours the path of the file as it existed in our tree + * @param theirs the path of the file as it existed in their tree + */ +GIT_EXTERN(int) git_index_name_add(git_index *index, + const char *ancestor, const char *ours, const char *theirs); + +/** + * Remove all filename conflict entries. + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_name_clear(git_index *index); + +/**@}*/ + +/** @name Resolve Undo (REUC) index entry manipulation. + * + * These functions work on the Resolve Undo index extension and contains + * data about the original files that led to a merge conflict. + */ +/**@{*/ + +/** + * Get the count of resolve undo entries currently in the index. + * + * @param index an existing index object + * @return integer of count of current resolve undo entries + */ +GIT_EXTERN(size_t) git_index_reuc_entrycount(git_index *index); + +/** + * Finds the resolve undo entry that points to the given path in the Git + * index. + * + * @param at_pos the address to which the position of the reuc entry is written (optional) + * @param index an existing index object + * @param path path to search + * @return 0 if found, < 0 otherwise (GIT_ENOTFOUND) + */ +GIT_EXTERN(int) git_index_reuc_find(size_t *at_pos, git_index *index, const char *path); + +/** + * Get a resolve undo entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param path path to search + * @return the resolve undo entry; NULL if not found + */ +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path); + +/** + * Get a resolve undo entry from the index. + * + * The returned entry is read-only and should not be modified + * or freed by the caller. + * + * @param index an existing index object + * @param n the position of the entry + * @return a pointer to the resolve undo entry; NULL if out of bounds + */ +GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n); + +/** + * Adds a resolve undo entry for a file based on the given parameters. + * + * The resolve undo entry contains the OIDs of files that were involved + * in a merge conflict after the conflict has been resolved. This allows + * conflicts to be re-resolved later. + * + * If there exists a resolve undo entry for the given path in the index, + * it will be removed. + * + * This method will fail in bare index instances. + * + * @param index an existing index object + * @param path filename to add + * @param ancestor_mode mode of the ancestor file + * @param ancestor_id oid of the ancestor file + * @param our_mode mode of our file + * @param our_id oid of our file + * @param their_mode mode of their file + * @param their_id oid of their file + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path, + int ancestor_mode, const git_oid *ancestor_id, + int our_mode, const git_oid *our_id, + int their_mode, const git_oid *their_id); + +/** + * Remove an resolve undo entry from the index + * + * @param index an existing index object + * @param n position of the resolve undo entry to remove + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n); + +/** + * Remove all resolve undo entries from the index + * + * @param index an existing index object + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_reuc_clear(git_index *index); + +/**@}*/ + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/mempack.h b/include/git2/sys/mempack.h new file mode 100644 index 0000000..17da590 --- /dev/null +++ b/include/git2/sys/mempack.h @@ -0,0 +1,87 @@ +/* + * 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_odb_mempack_h__ +#define INCLUDE_sys_git_odb_mempack_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/odb.h" +#include "git2/buffer.h" + +/** + * @file git2/sys/mempack.h + * @brief Custom ODB backend that permits packing objects in-memory + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Instantiate a new mempack backend. + * + * The backend must be added to an existing ODB with the highest + * priority. + * + * git_mempack_new(&mempacker); + * git_repository_odb(&odb, repository); + * git_odb_add_backend(odb, mempacker, 999); + * + * Once the backend has been loaded, all writes to the ODB will + * instead be queued in memory, and can be finalized with + * `git_mempack_dump`. + * + * Subsequent reads will also be served from the in-memory store + * to ensure consistency, until the memory store is dumped. + * + * @param out Pointer where to store the ODB backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_new(git_odb_backend **out); + +/** + * Dump all the queued in-memory writes to a packfile. + * + * The contents of the packfile will be stored in the given buffer. + * It is the caller's responsibility to ensure that the generated + * packfile is available to the repository (e.g. by writing it + * to disk, or doing something crazy like distributing it across + * several copies of the repository over a network). + * + * Once the generated packfile is available to the repository, + * call `git_mempack_reset` to cleanup the memory store. + * + * Calling `git_mempack_reset` before the packfile has been + * written to disk will result in an inconsistent repository + * (the objects in the memory store won't be accessible). + * + * @param pack Buffer where to store the raw packfile + * @param repo The active repository where the backend is loaded + * @param backend The mempack backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend); + +/** + * Reset the memory packer by clearing all the queued objects. + * + * This assumes that `git_mempack_dump` has been called before to + * store all the queued objects into a single packfile. + * + * Alternatively, call `reset` without a previous dump to "undo" + * all the recently written objects, giving transaction-like + * semantics to the Git repository. + * + * @param backend The mempack backend + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/merge.h b/include/git2/sys/merge.h new file mode 100644 index 0000000..ef4bc5a --- /dev/null +++ b/include/git2/sys/merge.h @@ -0,0 +1,182 @@ +/* + * 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(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 diff --git a/include/git2/sys/midx.h b/include/git2/sys/midx.h new file mode 100644 index 0000000..3a87484 --- /dev/null +++ b/include/git2/sys/midx.h @@ -0,0 +1,78 @@ +/* + * 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_midx_h__ +#define INCLUDE_sys_git_midx_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/midx.h + * @brief Git multi-pack-index routines + * @defgroup git_midx Git multi-pack-index routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new writer for `multi-pack-index` files. + * + * @param out location to store the writer pointer. + * @param pack_dir the directory where the `.pack` and `.idx` files are. The + * `multi-pack-index` file will be written in this directory, too. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_new( + git_midx_writer **out, + const char *pack_dir +#ifdef GIT_EXPERIMENTAL_SHA256 + , git_oid_t oid_type +#endif + ); + +/** + * Free the multi-pack-index writer and its resources. + * + * @param w the writer to free. If NULL no action is taken. + */ +GIT_EXTERN(void) git_midx_writer_free(git_midx_writer *w); + +/** + * Add an `.idx` file to the writer. + * + * @param w the writer + * @param idx_path the path of an `.idx` file. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_add( + git_midx_writer *w, + const char *idx_path); + +/** + * Write a `multi-pack-index` file to a file. + * + * @param w the writer + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_commit( + git_midx_writer *w); + +/** + * Dump the contents of the `multi-pack-index` to an in-memory buffer. + * + * @param midx Buffer where to store the contents of the `multi-pack-index`. + * @param w the writer + * @return 0 or an error code + */ +GIT_EXTERN(int) git_midx_writer_dump( + git_buf *midx, + git_midx_writer *w); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/odb_backend.h b/include/git2/sys/odb_backend.h new file mode 100644 index 0000000..c42abd3 --- /dev/null +++ b/include/git2/sys/odb_backend.h @@ -0,0 +1,172 @@ +/* + * 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_odb_backend_h__ +#define INCLUDE_sys_git_odb_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" +#include "git2/odb.h" + +/** + * @file git2/sys/backend.h + * @brief Git custom backend implementors functions + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * An instance for a custom backend + */ +struct git_odb_backend { + unsigned int version; + git_odb *odb; + + /* read and read_prefix each return to libgit2 a buffer which + * will be freed later. The buffer should be allocated using + * the function git_odb_backend_data_alloc to ensure that libgit2 + * can safely free it later. */ + int GIT_CALLBACK(read)( + void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *); + + /* To find a unique object given a prefix of its oid. The oid given + * must be so that the remaining (GIT_OID_SHA1_HEXSIZE - len)*4 bits are 0s. + */ + int GIT_CALLBACK(read_prefix)( + git_oid *, void **, size_t *, git_object_t *, + git_odb_backend *, const git_oid *, size_t); + + int GIT_CALLBACK(read_header)( + size_t *, git_object_t *, git_odb_backend *, const git_oid *); + + /** + * Write an object into the backend. The id of the object has + * already been calculated and is passed in. + */ + int GIT_CALLBACK(write)( + git_odb_backend *, const git_oid *, const void *, size_t, git_object_t); + + int GIT_CALLBACK(writestream)( + git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t); + + int GIT_CALLBACK(readstream)( + git_odb_stream **, size_t *, git_object_t *, + git_odb_backend *, const git_oid *); + + int GIT_CALLBACK(exists)( + git_odb_backend *, const git_oid *); + + int GIT_CALLBACK(exists_prefix)( + git_oid *, git_odb_backend *, const git_oid *, size_t); + + /** + * If the backend implements a refreshing mechanism, it should be exposed + * through this endpoint. Each call to `git_odb_refresh()` will invoke it. + * + * The odb layer will automatically call this when needed on failed + * lookups (ie. `exists()`, `read()`, `read_header()`). + */ + int GIT_CALLBACK(refresh)(git_odb_backend *); + + int GIT_CALLBACK(foreach)( + git_odb_backend *, git_odb_foreach_cb cb, void *payload); + + int GIT_CALLBACK(writepack)( + git_odb_writepack **, git_odb_backend *, git_odb *odb, + git_indexer_progress_cb progress_cb, void *progress_payload); + + /** + * If the backend supports pack files, this will create a + * `multi-pack-index` file which will contain an index of all objects + * across all the `.pack` files. + */ + int GIT_CALLBACK(writemidx)(git_odb_backend *); + + /** + * "Freshens" an already existing object, updating its last-used + * time. This occurs when `git_odb_write` was called, but the + * object already existed (and will not be re-written). The + * underlying implementation may want to update last-used timestamps. + * + * If callers implement this, they should return `0` if the object + * exists and was freshened, and non-zero otherwise. + */ + int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *); + + /** + * Frees any resources held by the odb (including the `git_odb_backend` + * itself). An odb backend implementation must provide this function. + */ + void GIT_CALLBACK(free)(git_odb_backend *); +}; + +#define GIT_ODB_BACKEND_VERSION 1 +#define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION} + +/** + * Initializes a `git_odb_backend` with default values. Equivalent to + * creating an instance with GIT_ODB_BACKEND_INIT. + * + * @param backend the `git_odb_backend` struct to initialize. + * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_odb_init_backend( + git_odb_backend *backend, + unsigned int version); + +/** + * Allocate data for an ODB object. Custom ODB backends may use this + * to provide data back to the ODB from their read function. This + * memory should not be freed once it is returned to libgit2. If a + * custom ODB uses this function but encounters an error and does not + * return this data to libgit2, then they should use the corresponding + * git_odb_backend_data_free function. + * + * @param backend the ODB backend that is allocating this memory + * @param len the number of bytes to allocate + * @return the allocated buffer on success or NULL if out of memory + */ +GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len); + +/** + * Frees custom allocated ODB data. This should only be called when + * memory allocated using git_odb_backend_data_alloc is not returned + * to libgit2 because the backend encountered an error in the read + * function after allocation and did not return this data to libgit2. + * + * @param backend the ODB backend that is freeing this memory + * @param data the buffer to free + */ +GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data); + + +/* + * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`. + */ +#ifndef GIT_DEPRECATE_HARD + +/** + * Allocate memory for an ODB object from a custom backend. This is + * an alias of `git_odb_backend_data_alloc` and is preserved for + * backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated git_odb_backend_data_alloc + * @see git_odb_backend_data_alloc + */ +GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); + +#endif + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/openssl.h b/include/git2/sys/openssl.h new file mode 100644 index 0000000..b41c55c --- /dev/null +++ b/include/git2/sys/openssl.h @@ -0,0 +1,38 @@ +/* + * 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_git_openssl_h__ +#define INCLUDE_git_openssl_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * Initialize the OpenSSL locks + * + * OpenSSL requires the application to determine how it performs + * locking. + * + * This is a last-resort convenience function which libgit2 provides for + * allocating and initializing the locks as well as setting the + * locking function to use the system's native locking functions. + * + * The locking function will be cleared and the memory will be freed + * when you call git_threads_sutdown(). + * + * If your programming language has an OpenSSL package/bindings, it + * likely sets up locking. You should very strongly prefer that over + * this function. + * + * @return 0 on success, -1 if there are errors or if libgit2 was not + * built with OpenSSL and threading support. + */ +GIT_EXTERN(int) git_openssl_set_locking(void); + +GIT_END_DECL +#endif + diff --git a/include/git2/sys/path.h b/include/git2/sys/path.h new file mode 100644 index 0000000..2a0c7e0 --- /dev/null +++ b/include/git2/sys/path.h @@ -0,0 +1,64 @@ +/* + * 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_path_h__ +#define INCLUDE_sys_git_path_h__ + +#include "git2/common.h" + +GIT_BEGIN_DECL + +/** + * The kinds of git-specific files we know about. + * + * The order needs to stay the same to not break the `gitfiles` + * array in path.c + */ +typedef enum { + /** Check for the .gitignore file */ + GIT_PATH_GITFILE_GITIGNORE, + /** Check for the .gitmodules file */ + GIT_PATH_GITFILE_GITMODULES, + /** Check for the .gitattributes file */ + GIT_PATH_GITFILE_GITATTRIBUTES +} git_path_gitfile; + +/** + * The kinds of checks to perform according to which filesystem we are trying to + * protect. + */ +typedef enum { + /** Do both NTFS- and HFS-specific checks */ + GIT_PATH_FS_GENERIC, + /** Do NTFS-specific checks only */ + GIT_PATH_FS_NTFS, + /** Do HFS-specific checks only */ + GIT_PATH_FS_HFS +} git_path_fs; + +/** + * Check whether a path component corresponds to a .git$SUFFIX + * file. + * + * As some filesystems do special things to filenames when + * writing files to disk, you cannot always do a plain string + * comparison to verify whether a file name matches an expected + * path or not. This function can do the comparison for you, + * depending on the filesystem you're on. + * + * @param path the path component to check + * @param pathlen the length of `path` that is to be checked + * @param gitfile which file to check against + * @param fs which filesystem-specific checks to use + * @return 0 in case the file does not match, a positive value if + * it does; -1 in case of an error + */ +GIT_EXTERN(int) git_path_is_gitfile(const char *path, size_t pathlen, git_path_gitfile gitfile, git_path_fs fs); + +GIT_END_DECL + +#endif /* INCLUDE_sys_git_path */ diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h new file mode 100644 index 0000000..c31e26d --- /dev/null +++ b/include/git2/sys/refdb_backend.h @@ -0,0 +1,361 @@ +/* + * 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_refdb_backend_h__ +#define INCLUDE_sys_git_refdb_backend_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/refdb_backend.h + * @brief Git custom refs backend functions + * @defgroup git_refdb_backend Git custom refs backend API + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + + +/** + * Every backend's iterator must have a pointer to itself as the first + * element, so the API can talk to it. You'd define your iterator as + * + * struct my_iterator { + * git_reference_iterator parent; + * ... + * } + * + * and assign `iter->parent.backend` to your `git_refdb_backend`. + */ +struct git_reference_iterator { + git_refdb *db; + + /** + * Return the current reference and advance the iterator. + */ + int GIT_CALLBACK(next)( + git_reference **ref, + git_reference_iterator *iter); + + /** + * Return the name of the current reference and advance the iterator + */ + int GIT_CALLBACK(next_name)( + const char **ref_name, + git_reference_iterator *iter); + + /** + * Free the iterator + */ + void GIT_CALLBACK(free)( + git_reference_iterator *iter); +}; + +/** An instance for a custom backend */ +struct git_refdb_backend { + unsigned int version; /**< The backend API version */ + + /** + * Queries the refdb backend for the existence of a reference. + * + * A refdb implementation must provide this function. + * + * @arg exists The implementation shall set this to `0` if a ref does + * not exist, otherwise to `1`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, a negative error value code. + */ + int GIT_CALLBACK(exists)( + int *exists, + git_refdb_backend *backend, + const char *ref_name); + + /** + * Queries the refdb backend for a given reference. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference, if it could be found, otherwise to `NULL`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, `GIT_ENOTFOUND` if the reference does + * exist, otherwise a negative error code. + */ + int GIT_CALLBACK(lookup)( + git_reference **out, + git_refdb_backend *backend, + const char *ref_name); + + /** + * Allocate an iterator object for the backend. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference iterator. A custom structure may be used with an + * embedded `git_reference_iterator` structure. Both `next` + * and `next_name` functions of `git_reference_iterator` need + * to be populated. + * @arg glob A pattern to filter references by. If given, the iterator + * shall only return references that match the glob when + * passed to `wildmatch`. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(iterator)( + git_reference_iterator **iter, + struct git_refdb_backend *backend, + const char *glob); + + /** + * Writes the given reference to the refdb. + * + * A refdb implementation must provide this function. + * + * @arg ref The reference to persist. May either be a symbolic or + * direct reference. + * @arg force Whether to write the reference if a reference with the + * same name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @arg old If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. If both `old` + * and `old_target` are `NULL`, then the reference should not + * exist at the point of writing. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. If both `old` and + * `old_target` are `NULL`, then the reference should + * not exist at the point of writing. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(write)(git_refdb_backend *backend, + const git_reference *ref, int force, + const git_signature *who, const char *message, + const git_oid *old, const char *old_target); + + /** + * Rename a reference in the refdb. + * + * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the newly created + * reference or `NULL` on error. + * @arg old_name The current name of the reference that is to be renamed. + * @arg new_name The new name that the old reference shall be renamed to. + * @arg force Whether to write the reference if a reference with the + * target name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(rename)( + git_reference **out, git_refdb_backend *backend, + const char *old_name, const char *new_name, int force, + const git_signature *who, const char *message); + + /** + * Deletes the given reference from the refdb. + * + * If it exists, its reflog should be deleted as well. + * + * A refdb implementation must provide this function. + * + * @arg ref_name The name of the reference name that shall be deleted. + * @arg old_id If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. + * @return `0` on success, otherwise a negative error code. + */ + int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target); + + /** + * Suggests that the given refdb compress or optimize its references. + * + * This mechanism is implementation specific. For on-disk reference + * databases, this may pack all loose references. + * + * A refdb implementation may provide this function; if it is not + * provided, nothing will be done. + * + * @return `0` on success a negative error code otherwise + */ + int GIT_CALLBACK(compress)(git_refdb_backend *backend); + + /** + * Query whether a particular reference has a log (may be empty) + * + * Shall return 1 if it has a reflog, 0 it it doesn't and negative in + * case an error occurred. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, `1` if the reflog for the given reference + * exists, a negative error code otherwise + */ + int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname); + + /** + * Make sure a particular reference will have a reflog which + * will be appended to on writes. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname); + + /** + * Frees any resources held by the refdb (including the `git_refdb_backend` + * itself). + * + * A refdb backend implementation must provide this function. + */ + void GIT_CALLBACK(free)(git_refdb_backend *backend); + + /** + * Read the reflog for the given reference name. + * + * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name); + + /** + * Write a reflog to disk. + * + * A refdb implementation must provide this function. + * + * @arg reflog The complete reference log for a given reference. Note + * that this may contain entries that have already been + * written to disk. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog); + + /** + * Rename a reflog. + * + * A refdb implementation must provide this function. + * + * @arg old_name The name of old reference whose reflog shall be renamed from. + * @arg new_name The name of new reference whose reflog shall be renamed to. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name); + + /** + * Remove a reflog. + * + * A refdb implementation must provide this function. + * + * @arg name The name of the reference whose reflog shall be deleted. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name); + + /** + * Lock a reference. + * + * A refdb implementation may provide this function; if it is not + * provided, the transaction API will fail to work. + * + * @arg payload_out Opaque parameter that will be passed verbosely to + * `unlock`. + * @arg refname Reference that shall be locked. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname); + + /** + * Unlock a reference. + * + * Only one of target or symbolic_target will be set. + * `success` will be true if the reference should be update, false if + * the lock must be discarded. + * + * A refdb implementation must provide this function if a `lock` + * implementation is provided. + * + * @arg payload The payload returned by `lock`. + * @arg success `1` if a reference should be updated, `2` if + * a reference should be deleted, `0` if the lock must be + * discarded. + * @arg update_reflog `1` in case the reflog should be updated, `0` + * otherwise. + * @arg ref The reference which should be unlocked. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry in case `update_reflog` is set. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry in + * case `update_reflog` is set. + * @return `0` on success, a negative error code otherwise + */ + int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog, + const git_reference *ref, const git_signature *sig, const char *message); +}; + +#define GIT_REFDB_BACKEND_VERSION 1 +#define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION} + +/** + * Initializes a `git_refdb_backend` with default values. Equivalent to + * creating an instance with GIT_REFDB_BACKEND_INIT. + * + * @param backend the `git_refdb_backend` struct to initialize + * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_refdb_init_backend( + git_refdb_backend *backend, + unsigned int version); + +/** + * Constructors for default filesystem-based refdb backend + * + * Under normal usage, this is called for you when the repository is + * opened / created, but you can use this to explicitly construct a + * filesystem refdb backend for a repository. + * + * @param backend_out Output pointer to the git_refdb_backend object + * @param repo Git repository to access + * @return 0 on success, <0 error code on failure + */ +GIT_EXTERN(int) git_refdb_backend_fs( + git_refdb_backend **backend_out, + git_repository *repo); + +/** + * Sets the custom backend to an existing reference DB + * + * The `git_refdb` will take ownership of the `git_refdb_backend` so you + * should NOT free it after calling this function. + * + * @param refdb database to add the backend to + * @param backend pointer to a git_refdb_backend instance + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_refdb_set_backend( + git_refdb *refdb, + git_refdb_backend *backend); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/reflog.h b/include/git2/sys/reflog.h new file mode 100644 index 0000000..c9d0041 --- /dev/null +++ b/include/git2/sys/reflog.h @@ -0,0 +1,21 @@ +/* + * 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_reflog_h__ +#define INCLUDE_sys_git_reflog_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +GIT_BEGIN_DECL + +GIT_EXTERN(git_reflog_entry *) git_reflog_entry__alloc(void); +GIT_EXTERN(void) git_reflog_entry__free(git_reflog_entry *entry); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/refs.h b/include/git2/sys/refs.h new file mode 100644 index 0000000..d2ce2e0 --- /dev/null +++ b/include/git2/sys/refs.h @@ -0,0 +1,49 @@ +/* + * 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_refdb_h__ +#define INCLUDE_sys_git_refdb_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/oid.h" + +/** + * @file git2/sys/refs.h + * @brief Low-level Git ref creation + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new direct reference from an OID. + * + * @param name the reference name + * @param oid the object id for a direct reference + * @param peel the first non-tag object's OID, or NULL + * @return the created git_reference or NULL on error + */ +GIT_EXTERN(git_reference *) git_reference__alloc( + const char *name, + const git_oid *oid, + const git_oid *peel); + +/** + * Create a new symbolic reference. + * + * @param name the reference name + * @param target the target for a symbolic reference + * @return the created git_reference or NULL on error + */ +GIT_EXTERN(git_reference *) git_reference__alloc_symbolic( + const char *name, + const char *target); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/remote.h b/include/git2/sys/remote.h new file mode 100644 index 0000000..0eae923 --- /dev/null +++ b/include/git2/sys/remote.h @@ -0,0 +1,46 @@ +/* + * 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_remote_h +#define INCLUDE_sys_git_remote_h + +#include "git2/remote.h" + +/** + * @file git2/sys/remote.h + * @brief Low-level remote functionality for custom transports + * @defgroup git_remote Low-level remote functionality + * @ingroup Git + * @{ +*/ + +GIT_BEGIN_DECL + +typedef enum { + /** Remote supports fetching an advertised object by ID. */ + GIT_REMOTE_CAPABILITY_TIP_OID = (1 << 0), + + /** Remote supports fetching an individual reachable object. */ + GIT_REMOTE_CAPABILITY_REACHABLE_OID = (1 << 1), +} git_remote_capability_t; + +/** + * Disposes libgit2-initialized fields from a git_remote_connect_options. + * This should only be used for git_remote_connect_options returned by + * git_transport_remote_connect_options. + * + * Note that this does not free the `git_remote_connect_options` itself, just + * the memory pointed to by it. + * + * @param opts The `git_remote_connect_options` struct to dispose. + */ +GIT_EXTERN(void) git_remote_connect_options_dispose( + git_remote_connect_options *opts); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/repository.h b/include/git2/sys/repository.h new file mode 100644 index 0000000..892be66 --- /dev/null +++ b/include/git2/sys/repository.h @@ -0,0 +1,180 @@ +/* + * 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_repository_h__ +#define INCLUDE_sys_git_repository_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/repository.h + * @brief Git repository custom implementation routines + * @defgroup git_backend Git custom backend APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Create a new repository with neither backends nor config object + * + * Note that this is only useful if you wish to associate the repository + * with a non-filesystem-backed object database and config store. + * + * Caveats: since this repository has no physical location, some systems + * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR, + * or $GIT_INFO_DIR are impacted. + * + * @param out The blank repository + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_new(git_repository **out); + +/** + * Reset all the internal state in a repository. + * + * This will free all the mapped memory and internal objects + * of the repository and leave it in a "blank" state. + * + * There's no need to call this function directly unless you're + * trying to aggressively cleanup the repo before its + * deallocation. `git_repository_free` already performs this operation + * before deallocating the repo. + * + * @param repo The repository to clean up + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository__cleanup(git_repository *repo); + +/** + * Update the filesystem config settings for an open repository + * + * When a repository is initialized, config values are set based on the + * properties of the filesystem that the repository is on, such as + * "core.ignorecase", "core.filemode", "core.symlinks", etc. If the + * repository is moved to a new filesystem, these properties may no + * longer be correct and API calls may not behave as expected. This + * call reruns the phase of repository initialization that sets those + * properties to compensate for the current filesystem of the repo. + * + * @param repo A repository object + * @param recurse_submodules Should submodules be updated recursively + * @return 0 on success, < 0 on error + */ +GIT_EXTERN(int) git_repository_reinit_filesystem( + git_repository *repo, + int recurse_submodules); + +/** + * Set the configuration file for this repository + * + * This configuration file will be used for all configuration + * queries involving this repository. + * + * The repository will keep a reference to the config file; + * the user must still free the config after setting it + * to the repository, or it will leak. + * + * @param repo A repository object + * @param config A Config object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_config(git_repository *repo, git_config *config); + +/** + * Set the Object Database for this repository + * + * The ODB will be used for all object-related operations + * involving this repository. + * + * The repository will keep a reference to the ODB; the user + * must still free the ODB object after setting it to the + * repository, or it will leak. + * + * @param repo A repository object + * @param odb An ODB object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_odb(git_repository *repo, git_odb *odb); + +/** + * Set the Reference Database Backend for this repository + * + * The refdb will be used for all reference related operations + * involving this repository. + * + * The repository will keep a reference to the refdb; the user + * must still free the refdb object after setting it to the + * repository, or it will leak. + * + * @param repo A repository object + * @param refdb An refdb object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_refdb(git_repository *repo, git_refdb *refdb); + +/** + * Set the index file for this repository + * + * This index will be used for all index-related operations + * involving this repository. + * + * The repository will keep a reference to the index file; + * the user must still free the index after setting it + * to the repository, or it will leak. + * + * @param repo A repository object + * @param index An index object + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_set_index(git_repository *repo, git_index *index); + +/** + * Set a repository to be bare. + * + * Clear the working directory and set core.bare to true. You may also + * want to call `git_repository_set_index(repo, NULL)` since a bare repo + * typically does not have an index, but this function will not do that + * for you. + * + * @param repo Repo to make bare + * @return 0 on success, <0 on failure + */ +GIT_EXTERN(int) git_repository_set_bare(git_repository *repo); + +/** + * Load and cache all submodules. + * + * Because the `.gitmodules` file is unstructured, loading submodules is an + * O(N) operation. Any operation (such as `git_rebase_init`) that requires + * accessing all submodules is O(N^2) in the number of submodules, if it + * has to look each one up individually. This function loads all submodules + * and caches them so that subsequent calls to `git_submodule_lookup` are O(1). + * + * @param repo the repository whose submodules will be cached. + */ +GIT_EXTERN(int) git_repository_submodule_cache_all( + git_repository *repo); + +/** + * Clear the submodule cache. + * + * Clear the submodule cache populated by `git_repository_submodule_cache_all`. + * If there is no cache, do nothing. + * + * The cache incorporates data from the repository's configuration, as well + * as the state of the working tree, the index, and HEAD. So any time any + * of these has changed, the cache might become invalid. + * + * @param repo the repository whose submodule cache will be cleared + */ +GIT_EXTERN(int) git_repository_submodule_cache_clear( + git_repository *repo); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/sys/stream.h b/include/git2/sys/stream.h new file mode 100644 index 0000000..3d28d09 --- /dev/null +++ b/include/git2/sys/stream.h @@ -0,0 +1,152 @@ +/* + * 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_stream_h__ +#define INCLUDE_sys_git_stream_h__ + +#include "git2/common.h" +#include "git2/types.h" +#include "git2/proxy.h" + +GIT_BEGIN_DECL + +#define GIT_STREAM_VERSION 1 + +/** + * Every stream must have this struct as its first element, so the + * API can talk to it. You'd define your stream as + * + * struct my_stream { + * git_stream parent; + * ... + * } + * + * and fill the functions + */ +typedef struct git_stream { + int version; + + int encrypted : 1, + proxy_support : 1; + + /** + * Timeout for read and write operations; can be set to `0` to + * block indefinitely. + */ + int timeout; + + /** + * Timeout to connect to the remote server; can be set to `0` + * to use the system defaults. This can be shorter than the + * system default - often 75 seconds - but cannot be longer. + */ + int connect_timeout; + + int GIT_CALLBACK(connect)(struct git_stream *); + int GIT_CALLBACK(certificate)(git_cert **, struct git_stream *); + int GIT_CALLBACK(set_proxy)(struct git_stream *, const git_proxy_options *proxy_opts); + ssize_t GIT_CALLBACK(read)(struct git_stream *, void *, size_t); + ssize_t GIT_CALLBACK(write)(struct git_stream *, const char *, size_t, int); + int GIT_CALLBACK(close)(struct git_stream *); + void GIT_CALLBACK(free)(struct git_stream *); +} git_stream; + +typedef struct { + /** The `version` field should be set to `GIT_STREAM_VERSION`. */ + int version; + + /** + * Called to create a new connection to a given host. + * + * @param out The created stream + * @param host The hostname to connect to; may be a hostname or + * IP address + * @param port The port to connect to; may be a port number or + * service name + * @return 0 or an error code + */ + int GIT_CALLBACK(init)(git_stream **out, const char *host, const char *port); + + /** + * Called to create a new connection on top of the given stream. If + * this is a TLS stream, then this function may be used to proxy a + * TLS stream over an HTTP CONNECT session. If this is unset, then + * HTTP CONNECT proxies will not be supported. + * + * @param out The created stream + * @param in An existing stream to add TLS to + * @param host The hostname that the stream is connected to, + * for certificate validation + * @return 0 or an error code + */ + int GIT_CALLBACK(wrap)(git_stream **out, git_stream *in, const char *host); +} git_stream_registration; + +/** + * The type of stream to register. + */ +typedef enum { + /** A standard (non-TLS) socket. */ + GIT_STREAM_STANDARD = 1, + + /** A TLS-encrypted socket. */ + GIT_STREAM_TLS = 2 +} git_stream_t; + +/** + * Register stream constructors for the library to use + * + * If a registration structure is already set, it will be overwritten. + * Pass `NULL` in order to deregister the current constructor and return + * to the system defaults. + * + * The type parameter may be a bitwise AND of types. + * + * @param type the type or types of stream to register + * @param registration the registration data + * @return 0 or an error code + */ +GIT_EXTERN(int) git_stream_register( + git_stream_t type, git_stream_registration *registration); + +#ifndef GIT_DEPRECATE_HARD + +/** @name Deprecated TLS Stream Registration Functions + * + * These functions are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * @deprecated Provide a git_stream_registration to git_stream_register + * @see git_stream_registration + */ +typedef int GIT_CALLBACK(git_stream_cb)(git_stream **out, const char *host, const char *port); + +/** + * Register a TLS stream constructor for the library to use. This stream + * will not support HTTP CONNECT proxies. This internally calls + * `git_stream_register` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Provide a git_stream_registration to git_stream_register + * @see git_stream_register + */ +GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor); + +/**@}*/ + +#endif + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h new file mode 100644 index 0000000..370ca45 --- /dev/null +++ b/include/git2/sys/transport.h @@ -0,0 +1,465 @@ +/* + * 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_transport_h +#define INCLUDE_sys_git_transport_h + +#include "git2/net.h" +#include "git2/oidarray.h" +#include "git2/proxy.h" +#include "git2/remote.h" +#include "git2/strarray.h" +#include "git2/transport.h" +#include "git2/types.h" + +/** + * @file git2/sys/transport.h + * @brief Git custom transport registration interfaces and functions + * @defgroup git_transport Git custom transport registration + * @ingroup Git + * @{ + */ + +GIT_BEGIN_DECL + +typedef struct { + const git_remote_head * const *refs; + size_t refs_len; + git_oid *shallow_roots; + size_t shallow_roots_len; + int depth; +} git_fetch_negotiation; + +struct git_transport { + unsigned int version; /**< The struct version */ + + /** + * Connect the transport to the remote repository, using the given + * direction. + */ + int GIT_CALLBACK(connect)( + git_transport *transport, + const char *url, + int direction, + const git_remote_connect_options *connect_opts); + + /** + * Resets the connect options for the given transport. This + * is useful for updating settings or callbacks for an already + * connected transport. + */ + int GIT_CALLBACK(set_connect_opts)( + git_transport *transport, + const git_remote_connect_options *connect_opts); + + /** + * Gets the capabilities for this remote repository. + * + * This function may be called after a successful call to + * `connect()`. + */ + int GIT_CALLBACK(capabilities)( + unsigned int *capabilities, + git_transport *transport); + +#ifdef GIT_EXPERIMENTAL_SHA256 + /** + * Gets the object type for the remote repository. + * + * This function may be called after a successful call to + * `connect()`. + */ + int GIT_CALLBACK(oid_type)( + git_oid_t *object_type, + git_transport *transport); +#endif + + /** + * Get the list of available references in the remote repository. + * + * This function may be called after a successful call to + * `connect()`. The array returned is owned by the transport and + * must be kept valid until the next call to one of its functions. + */ + int GIT_CALLBACK(ls)( + const git_remote_head ***out, + size_t *size, + git_transport *transport); + + /** Executes the push whose context is in the git_push object. */ + int GIT_CALLBACK(push)( + git_transport *transport, + git_push *push); + + /** + * Negotiate a fetch with the remote repository. + * + * This function may be called after a successful call to `connect()`, + * when the direction is GIT_DIRECTION_FETCH. The function performs a + * negotiation to calculate the `wants` list for the fetch. + */ + int GIT_CALLBACK(negotiate_fetch)( + git_transport *transport, + git_repository *repo, + const git_fetch_negotiation *fetch_data); + + /** + * Return the shallow roots of the remote. + * + * This function may be called after a successful call to + * `negotiate_fetch`. + */ + int GIT_CALLBACK(shallow_roots)( + git_oidarray *out, + git_transport *transport); + + /** + * Start downloading the packfile from the remote repository. + * + * This function may be called after a successful call to + * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH. + */ + int GIT_CALLBACK(download_pack)( + git_transport *transport, + git_repository *repo, + git_indexer_progress *stats); + + /** Checks to see if the transport is connected */ + int GIT_CALLBACK(is_connected)(git_transport *transport); + + /** Cancels any outstanding transport operation */ + void GIT_CALLBACK(cancel)(git_transport *transport); + + /** + * Close the connection to the remote repository. + * + * This function is the reverse of connect() -- it terminates the + * connection to the remote end. + */ + int GIT_CALLBACK(close)(git_transport *transport); + + /** Frees/destructs the git_transport object. */ + void GIT_CALLBACK(free)(git_transport *transport); +}; + +#define GIT_TRANSPORT_VERSION 1 +#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} + +/** + * Initializes a `git_transport` with default values. Equivalent to + * creating an instance with GIT_TRANSPORT_INIT. + * + * @param opts the `git_transport` struct to initialize + * @param version Version of struct; pass `GIT_TRANSPORT_VERSION` + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_transport_init( + git_transport *opts, + unsigned int version); + +/** + * Function to use to create a transport from a URL. The transport database + * is scanned to find a transport that implements the scheme of the URI (i.e. + * git:// or http://) and a transport object is returned to the caller. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param url The URL to connect to + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url); + +/** + * Create an ssh transport with custom git command paths + * + * This is a factory function suitable for setting as the transport + * callback in a remote (or for a clone in the options). + * + * The payload argument must be a strarray pointer with the paths for + * the `git-upload-pack` and `git-receive-pack` at index 0 and 1. + * + * @param out the resulting transport + * @param owner the owning remote + * @param payload a strarray with the paths + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload); + +/** + * Add a custom transport definition, to be used in addition to the built-in + * set of transports that come with libgit2. + * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * + * @param prefix The scheme (ending in "://") to match, i.e. "git://" + * @param cb The callback used to create an instance of the transport + * @param param A fixed parameter to pass to cb at creation time + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_register( + const char *prefix, + git_transport_cb cb, + void *param); + +/** + * Unregister a custom transport definition which was previously registered + * with git_transport_register. + * + * The caller is responsible for synchronizing calls to git_transport_register + * and git_transport_unregister with other calls to the library that + * instantiate transports. + * + * @param prefix From the previous call to git_transport_register + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_unregister( + const char *prefix); + +/* Transports which come with libgit2 (match git_transport_cb). The expected + * value for "param" is listed in-line below. */ + +/** + * Create an instance of the dummy transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_dummy( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the local transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload You must pass NULL for this parameter. + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_local( + git_transport **out, + git_remote *owner, + /* NULL */ void *payload); + +/** + * Create an instance of the smart transport. + * + * @param out The newly created transport (out) + * @param owner The git_remote which will own this transport + * @param payload A pointer to a git_smart_subtransport_definition + * @return 0 or an error code + */ +GIT_EXTERN(int) git_transport_smart( + git_transport **out, + git_remote *owner, + /* (git_smart_subtransport_definition *) */ void *payload); + +/** + * Call the certificate check for this transport. + * + * @param transport a smart transport + * @param cert the certificate to pass to the caller + * @param valid whether we believe the certificate is valid + * @param hostname the hostname we connected to + * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH + * to indicate that there is no callback registered (or the callback + * refused to validate the certificate and callers should behave as + * if no callback was set), or < 0 for an error + */ +GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname); + +/** + * Call the credentials callback for this transport + * + * @param out the pointer where the creds are to be stored + * @param transport a smart transport + * @param user the user we saw on the url (if any) + * @param methods available methods for authentication + * @return the return value of the callback: 0 for no error, GIT_PASSTHROUGH + * to indicate that there is no callback registered (or the callback + * refused to provide credentials and callers should behave as if no + * callback was set), or < 0 for an error + */ +GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transport *transport, const char *user, int methods); + +/** + * Get a copy of the remote connect options + * + * All data is copied and must be freed by the caller by calling + * `git_remote_connect_options_dispose`. + * + * @param out options struct to fill + * @param transport the transport to extract the data from. + */ +GIT_EXTERN(int) git_transport_remote_connect_options( + git_remote_connect_options *out, + git_transport *transport); + +/* + *** End of base transport interface *** + *** Begin interface for subtransports for the smart transport *** + */ + +/** Actions that the smart transport can ask a subtransport to perform */ +typedef enum { + GIT_SERVICE_UPLOADPACK_LS = 1, + GIT_SERVICE_UPLOADPACK = 2, + GIT_SERVICE_RECEIVEPACK_LS = 3, + GIT_SERVICE_RECEIVEPACK = 4 +} git_smart_service_t; + +typedef struct git_smart_subtransport git_smart_subtransport; +typedef struct git_smart_subtransport_stream git_smart_subtransport_stream; + +/** + * A stream used by the smart transport to read and write data + * from a subtransport. + * + * This provides a customization point in case you need to + * support some other communication method. + */ +struct git_smart_subtransport_stream { + git_smart_subtransport *subtransport; /**< The owning subtransport */ + + /** + * Read available data from the stream. + * + * The implementation may read less than requested. + */ + int GIT_CALLBACK(read)( + git_smart_subtransport_stream *stream, + char *buffer, + size_t buf_size, + size_t *bytes_read); + + /** + * Write data to the stream + * + * The implementation must write all data or return an error. + */ + int GIT_CALLBACK(write)( + git_smart_subtransport_stream *stream, + const char *buffer, + size_t len); + + /** Free the stream */ + void GIT_CALLBACK(free)( + git_smart_subtransport_stream *stream); +}; + +/** + * An implementation of a subtransport which carries data for the + * smart transport + */ +struct git_smart_subtransport { + /** + * Setup a subtransport stream for the requested action. + */ + int GIT_CALLBACK(action)( + git_smart_subtransport_stream **out, + git_smart_subtransport *transport, + const char *url, + git_smart_service_t action); + + /** + * Close the subtransport. + * + * Subtransports are guaranteed a call to close() between + * calls to action(), except for the following two "natural" progressions + * of actions against a constant URL: + * + * - UPLOADPACK_LS -> UPLOADPACK + * - RECEIVEPACK_LS -> RECEIVEPACK + */ + int GIT_CALLBACK(close)(git_smart_subtransport *transport); + + /** Free the subtransport */ + void GIT_CALLBACK(free)(git_smart_subtransport *transport); +}; + +/** A function which creates a new subtransport for the smart transport */ +typedef int GIT_CALLBACK(git_smart_subtransport_cb)( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Definition for a "subtransport" + * + * The smart transport knows how to speak the git protocol, but it has no + * knowledge of how to establish a connection between it and another endpoint, + * or how to move data back and forth. For this, a subtransport interface is + * declared, and the smart transport delegates this work to the subtransports. + * + * Three subtransports are provided by libgit2: ssh, git, http(s). + * + * Subtransports can either be RPC = 0 (persistent connection) or RPC = 1 + * (request/response). The smart transport handles the differences in its own + * logic. The git subtransport is RPC = 0, while http is RPC = 1. + */ +typedef struct git_smart_subtransport_definition { + /** The function to use to create the git_smart_subtransport */ + git_smart_subtransport_cb callback; + + /** + * True if the protocol is stateless; false otherwise. For example, + * http:// is stateless, but git:// is not. + */ + unsigned rpc; + + /** User-specified parameter passed to the callback */ + void *param; +} git_smart_subtransport_definition; + +/* Smart transport subtransports that come with libgit2 */ + +/** + * Create an instance of the http subtransport. + * + * This subtransport also supports https. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_http( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Create an instance of the git subtransport. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_git( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** + * Create an instance of the ssh subtransport. + * + * @param out The newly created subtransport + * @param owner The smart transport to own this subtransport + * @return 0 or an error code + */ +GIT_EXTERN(int) git_smart_subtransport_ssh( + git_smart_subtransport **out, + git_transport *owner, + void *param); + +/** @} */ +GIT_END_DECL +#endif |