diff options
Diffstat (limited to 'include/git2')
41 files changed, 1247 insertions, 728 deletions
diff --git a/include/git2/attr.h b/include/git2/attr.h index 3adbb2c24..0238f3dd7 100644 --- a/include/git2/attr.h +++ b/include/git2/attr.h @@ -76,25 +76,28 @@ GIT_BEGIN_DECL */ #define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_T) +/** + * Possible states for an attribute + */ typedef enum { - GIT_ATTR_UNSPECIFIED_T = 0, - GIT_ATTR_TRUE_T, - GIT_ATTR_FALSE_T, - GIT_ATTR_VALUE_T, + GIT_ATTR_UNSPECIFIED_T = 0, /**< The attribute has been left unspecified */ + GIT_ATTR_TRUE_T, /**< The attribute has been set */ + GIT_ATTR_FALSE_T, /**< The attribute has been unset */ + GIT_ATTR_VALUE_T, /**< This attribute has a value */ } git_attr_t; -/* - * Return the value type for a given attribute. +/** + * Return the value type for a given attribute. * - * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute - * was not set at all), or `VALUE`, if the attribute was set to - * an actual string. + * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute + * was not set at all), or `VALUE`, if the attribute was set to an + * actual string. * - * If the attribute has a `VALUE` string, it can be accessed normally - * as a NULL-terminated C string. + * If the attribute has a `VALUE` string, it can be accessed normally + * as a NULL-terminated C string. * - * @param attr The attribute - * @return the value type for the attribute + * @param attr The attribute + * @return the value type for the attribute */ GIT_EXTERN(git_attr_t) git_attr_value(const char *attr); diff --git a/include/git2/blame.h b/include/git2/blame.h index b7fa9aeda..7f0de1731 100644 --- a/include/git2/blame.h +++ b/include/git2/blame.h @@ -83,17 +83,16 @@ typedef struct git_blame_options { #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION} /** -* Initializes a `git_blame_options` with default values. Equivalent to -* creating an instance with GIT_BLAME_OPTIONS_INIT. -* -* @param opts the `git_blame_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_BLAME_OPTIONS_VERSION` here. -* @return Zero on success; -1 on failure. -*/ + * Initializes a `git_blame_options` with default values. Equivalent to + * creating an instance with GIT_BLAME_OPTIONS_INIT. + * + * @param opts The `git_blame_options` struct to initialize + * @param version Version of struct; pass `GIT_BLAME_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ GIT_EXTERN(int) git_blame_init_options( - git_blame_options* opts, - int version); + git_blame_options *opts, + unsigned int version); /** * Structure that represents a blame hunk. diff --git a/include/git2/blob.h b/include/git2/blob.h index 1b6583309..c24ff7e7f 100644 --- a/include/git2/blob.h +++ b/include/git2/blob.h @@ -210,7 +210,7 @@ GIT_EXTERN(int) git_blob_create_frombuffer( * * The heuristic used to guess if a file is binary is taken from core git: * Searching for NUL bytes and looking for a reasonable ratio of printable - * to non-printable characters among the first 4000 bytes. + * to non-printable characters among the first 8000 bytes. * * @param blob The blob which content should be analyzed * @return 1 if the content of the blob is detected diff --git a/include/git2/buffer.h b/include/git2/buffer.h index 36a61e6c9..1c216bf3a 100644 --- a/include/git2/buffer.h +++ b/include/git2/buffer.h @@ -105,6 +105,22 @@ GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size); GIT_EXTERN(int) git_buf_set( git_buf *buffer, const void *data, size_t datalen); +/** +* Check quickly if buffer looks like it contains binary data +* +* @param buf Buffer to check +* @return 1 if buffer looks like non-text data +*/ +GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf); + +/** +* Check quickly if buffer contains a NUL byte +* +* @param buf Buffer to check +* @return 1 if buffer contains a NUL byte +*/ +GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf); + GIT_END_DECL /** @} */ diff --git a/include/git2/checkout.h b/include/git2/checkout.h index 69addb7d9..fe4966aa2 100644 --- a/include/git2/checkout.h +++ b/include/git2/checkout.h @@ -43,17 +43,17 @@ GIT_BEGIN_DECL * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE` * both of which only make modifications that will not lose changes. * - * | target == baseline | target != baseline | - * ---------------------|-----------------------|----------------------| - * workdir == baseline | no action | create, update, or | - * | | delete file | - * ---------------------|-----------------------|----------------------| - * workdir exists and | no action | conflict (notify | - * is != baseline | notify dirty MODIFIED | and cancel checkout) | - * ---------------------|-----------------------|----------------------| - * workdir missing, | create if SAFE_CREATE | create file | - * baseline present | notify dirty DELETED | | - * ---------------------|-----------------------|----------------------| + * | target == baseline | target != baseline | + * ---------------------|-----------------------|----------------------| + * workdir == baseline | no action | create, update, or | + * | | delete file | + * ---------------------|-----------------------|----------------------| + * workdir exists and | no action | conflict (notify | + * is != baseline | notify dirty MODIFIED | and cancel checkout) | + * ---------------------|-----------------------|----------------------| + * workdir missing, | create if SAFE_CREATE | create file | + * baseline present | notify dirty DELETED | | + * ---------------------|-----------------------|----------------------| * * The only difference between SAFE and SAFE_CREATE is that SAFE_CREATE * will cause a file to be checked out if it is missing from the working @@ -106,7 +106,7 @@ GIT_BEGIN_DECL * target contains that file. */ typedef enum { - GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */ + GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */ /** Allow safe updates that cannot overwrite uncommitted data */ GIT_CHECKOUT_SAFE = (1u << 0), @@ -233,18 +233,18 @@ typedef void (*git_checkout_progress_cb)( typedef struct git_checkout_options { unsigned int version; - unsigned int checkout_strategy; /** default will be a dry run */ + unsigned int checkout_strategy; /**< default will be a dry run */ - int disable_filters; /** don't apply filters like CRLF conversion */ - unsigned int dir_mode; /** default is 0755 */ - unsigned int file_mode; /** default is 0644 or 0755 as dictated by blob */ - int file_open_flags; /** default is O_CREAT | O_TRUNC | O_WRONLY */ + int disable_filters; /**< don't apply filters like CRLF conversion */ + unsigned int dir_mode; /**< default is 0755 */ + unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */ + int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */ - unsigned int notify_flags; /** see `git_checkout_notify_t` above */ + unsigned int notify_flags; /**< see `git_checkout_notify_t` above */ git_checkout_notify_cb notify_cb; void *notify_payload; - /* Optional callback to notify the consumer of checkout progress. */ + /** Optional callback to notify the consumer of checkout progress. */ git_checkout_progress_cb progress_cb; void *progress_payload; @@ -254,13 +254,13 @@ typedef struct git_checkout_options { */ git_strarray paths; - git_tree *baseline; /** expected content of workdir, defaults to HEAD */ + git_tree *baseline; /**< expected content of workdir, defaults to HEAD */ - const char *target_directory; /** alternative checkout path to workdir */ + const char *target_directory; /**< alternative checkout path to workdir */ - const char *ancestor_label; /** the name of the common ancestor side of conflicts */ - const char *our_label; /** the name of the "our" side of conflicts */ - const char *their_label; /** the name of the "their" side of conflicts */ + const char *ancestor_label; /**< the name of the common ancestor side of conflicts */ + const char *our_label; /**< the name of the "our" side of conflicts */ + const char *their_label; /**< the name of the "their" side of conflicts */ } git_checkout_options; #define GIT_CHECKOUT_OPTIONS_VERSION 1 @@ -270,14 +270,13 @@ typedef struct git_checkout_options { * Initializes a `git_checkout_options` with default values. Equivalent to * creating an instance with GIT_CHECKOUT_OPTIONS_INIT. * -* @param opts the `git_checkout_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_CHECKOUT_OPTIONS_VERSION` here. +* @param opts the `git_checkout_options` struct to initialize. +* @param version Version of struct; pass `GIT_CHECKOUT_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ -GIT_EXTERN(int) git_checkout_init_opts( - git_checkout_options* opts, - int version); +GIT_EXTERN(int) git_checkout_init_options( + git_checkout_options *opts, + unsigned int version); /** * Updates files in the index and the working tree to match the content of diff --git a/include/git2/cherrypick.h b/include/git2/cherrypick.h index 7c48e6659..dea67c1ff 100644 --- a/include/git2/cherrypick.h +++ b/include/git2/cherrypick.h @@ -28,23 +28,22 @@ typedef struct { git_merge_options merge_opts; git_checkout_options checkout_opts; -} git_cherry_pick_options; +} git_cherrypick_options; -#define GIT_CHERRY_PICK_OPTIONS_VERSION 1 -#define GIT_CHERRY_PICK_OPTIONS_INIT {GIT_CHERRY_PICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} +#define GIT_CHERRYPICK_OPTIONS_VERSION 1 +#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} /** - * Initializes a `git_cherry_pick_options` with default values. Equivalent to - * creating an instance with GIT_CHERRY_PICK_OPTIONS_INIT. + * Initializes a `git_cherrypick_options` with default values. Equivalent to + * creating an instance with GIT_CHERRYPICK_OPTIONS_INIT. * - * @param opts the `git_cherry_pick_options` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_CHERRY_PICK_OPTIONS_VERSION` here. + * @param opts the `git_cherrypick_options` struct to initialize + * @param version Version of struct; pass `GIT_CHERRYPICK_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ -GIT_EXTERN(int) git_cherry_pick_init_opts( - git_cherry_pick_options* opts, - int version); +GIT_EXTERN(int) git_cherrypick_init_options( + git_cherrypick_options *opts, + unsigned int version); /** * Cherry-picks the given commit against the given "our" commit, producing an @@ -54,16 +53,16 @@ GIT_EXTERN(int) git_cherry_pick_init_opts( * * @param out pointer to store the index result in * @param repo the repository that contains the given commits - * @param cherry_pick_commit the commit to cherry-pick + * @param cherrypick_commit the commit to cherry-pick * @param our_commit the commit to revert against (eg, HEAD) * @param mainline the parent of the revert commit, if it is a merge - * @param merge_tree_opts the merge tree options (or null for defaults) + * @param merge_options the merge options (or null for defaults) * @return zero on success, -1 on failure. */ -GIT_EXTERN(int) git_cherry_pick_commit( +GIT_EXTERN(int) git_cherrypick_commit( git_index **out, git_repository *repo, - git_commit *cherry_pick_commit, + git_commit *cherrypick_commit, git_commit *our_commit, unsigned int mainline, const git_merge_options *merge_options); @@ -73,13 +72,13 @@ GIT_EXTERN(int) git_cherry_pick_commit( * * @param repo the repository to cherry-pick * @param commit the commit to cherry-pick - * @param cherry_pick_options the cherry-pick options (or null for defaults) + * @param cherrypick_options the cherry-pick options (or null for defaults) * @return zero on success, -1 on failure. */ -GIT_EXTERN(int) git_cherry_pick( +GIT_EXTERN(int) git_cherrypick( git_repository *repo, git_commit *commit, - const git_cherry_pick_options *cherry_pick_options); + const git_cherrypick_options *cherrypick_options); /** @} */ GIT_END_DECL diff --git a/include/git2/clone.h b/include/git2/clone.h index 20be1a105..fa2e25b60 100644 --- a/include/git2/clone.h +++ b/include/git2/clone.h @@ -12,6 +12,7 @@ #include "indexer.h" #include "checkout.h" #include "remote.h" +#include "transport.h" /** @@ -24,66 +25,175 @@ GIT_BEGIN_DECL /** - * Clone options structure + * Options for bypassing the git-aware transport on clone. Bypassing + * it means that instead of a fetch, libgit2 will copy the object + * database directory instead of figuring out what it needs, which is + * faster. If possible, it will hardlink the files to save space. + */ +typedef enum { + /** + * Auto-detect (default), libgit2 will bypass the git-aware + * transport for local paths, but use a normal fetch for + * `file://` urls. + */ + GIT_CLONE_LOCAL_AUTO, + /** + * Bypass the git-aware transport even for a `file://` url. + */ + GIT_CLONE_LOCAL, + /** + * Do no bypass the git-aware transport + */ + GIT_CLONE_NO_LOCAL, + /** + * Bypass the git-aware transport, but do not try to use + * hardlinks. + */ + GIT_CLONE_LOCAL_NO_LINKS, +} git_clone_local_t; + +/** + * The signature of a function matching git_remote_create, with an additional + * void* as a callback payload. * - * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this: + * Callers of git_clone may provide a function matching this signature to override + * the remote creation and customization process during a clone operation. * - * git_clone_options opts = GIT_CLONE_OPTIONS_INIT; + * @param out the resulting remote + * @param repo the repository in which to create the remote + * @param name the remote's name + * @param url the remote's url + * @param payload an opaque payload + * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code + */ +typedef int (*git_remote_create_cb)( + git_remote **out, + git_repository *repo, + const char *name, + const char *url, + void *payload); + +/** + * The signature of a function matchin git_repository_init, with an + * aditional void * as callback payload. * - * - `checkout_opts` are option passed to the checkout step. To disable - * checkout, set the `checkout_strategy` to GIT_CHECKOUT_NONE. - * Generally you will want the use GIT_CHECKOUT_SAFE_CREATE to create - * all files in the working directory for the newly cloned repository. - * - `bare` should be set to zero (false) to create a standard repo, - * or non-zero for a bare repo - * - `ignore_cert_errors` should be set to 1 if errors validating the - * remote host's certificate should be ignored. + * Callers of git_clone my provide a function matching this signature + * to override the repository creation and customization process + * during a clone operation. * - * ** "origin" remote options: ** + * @param out the resulting repository + * @param path path in which to create the repository + * @param bare whether the repository is bare. This is the value from the clone options + * @param payload payload specified by the options + * @return 0, or a negative value to indicate error + */ +typedef int (*git_repository_create_cb)( + git_repository **out, + const char *path, + int bare, + void *payload); + +/** + * Clone options structure + * + * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this: * - * - `remote_name` is the name to be given to the "origin" remote. The - * default is "origin". - * - `checkout_branch` gives the name of the branch to checkout. NULL - * means use the remote's HEAD. - * - `signature` is the identity used when updating the reflog. NULL means to - * use the default signature using the config. + * git_clone_options opts = GIT_CLONE_OPTIONS_INIT; */ typedef struct git_clone_options { unsigned int version; + /** + * These options are passed to the checkout step. To disable + * checkout, set the `checkout_strategy` to + * `GIT_CHECKOUT_NONE`. Generally you will want the use + * GIT_CHECKOUT_SAFE_CREATE to create all files in the working + * directory for the newly cloned repository. + */ git_checkout_options checkout_opts; + + /** + * Callbacks to use for reporting fetch progress, and for acquiring + * credentials in the event they are needed. This parameter is ignored if + * the remote_cb parameter is set; if you provide a remote creation + * callback, then you have the opportunity to configure remote callbacks in + * provided function. + */ git_remote_callbacks remote_callbacks; + /** + * Set to zero (false) to create a standard repo, or non-zero + * for a bare repo + */ int bare; - int ignore_cert_errors; - const char *remote_name; + + /** + * Whether to use a fetch or copy the object database. + */ + git_clone_local_t local; + + /** + * The name of the branch to checkout. NULL means use the + * remote's default branch. + */ const char* checkout_branch; + + /** + * The identity used when updating the reflog. NULL means to + * use the default signature using the config. + */ git_signature *signature; + + /** + * A callback used to create the new repository into which to + * clone. If NULL, the 'bare' field will be used to determine + * whether to create a bare repository. + */ + git_repository_create_cb repository_cb; + + /** + * An opaque payload to pass to the git_repository creation callback. + * This parameter is ignored unless repository_cb is non-NULL. + */ + void *repository_cb_payload; + + /** + * A callback used to create the git_remote, prior to its being + * used to perform the clone operation. See the documentation for + * git_remote_create_cb for details. This parameter may be NULL, + * indicating that git_clone should provide default behavior. + */ + git_remote_create_cb remote_cb; + + /** + * An opaque payload to pass to the git_remote creation callback. + * This parameter is ignored unless remote_cb is non-NULL. + */ + void *remote_cb_payload; } git_clone_options; #define GIT_CLONE_OPTIONS_VERSION 1 #define GIT_CLONE_OPTIONS_INIT {GIT_CLONE_OPTIONS_VERSION, {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE_CREATE}, GIT_REMOTE_CALLBACKS_INIT} /** -* Initializes a `git_clone_options` with default values. Equivalent to -* creating an instance with GIT_CLONE_OPTIONS_INIT. -* -* @param opts the `git_clone_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_CLONE_OPTIONS_VERSION` here. -* @return Zero on success; -1 on failure. -*/ + * Initializes a `git_clone_options` with default values. Equivalent to + * creating an instance with GIT_CLONE_OPTIONS_INIT. + * + * @param opts The `git_clone_options` struct to initialize + * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ GIT_EXTERN(int) git_clone_init_options( - git_clone_options* opts, - int version); + git_clone_options *opts, + unsigned int version); /** * Clone a remote repository. * - * This version handles the simple case. If you'd like to create the - * repository or remote with non-default settings, you can create and - * configure them and then use `git_clone_into()`. + * By default this creates its repository and initial remote to match + * git's defaults. You can use the options in the callback to + * customize how these are created. * * @param out pointer that will receive the resulting repository object * @param url the remote repository to clone @@ -100,30 +210,6 @@ GIT_EXTERN(int) git_clone( const char *local_path, const git_clone_options *options); -/** - * Clone into a repository - * - * After creating the repository and remote and configuring them for - * paths and callbacks respectively, you can call this function to - * perform the clone operation and optionally checkout files. - * - * @param repo the repository to use - * @param remote the remote repository to clone from - * @param co_opts options to use during checkout - * @param branch the branch to checkout after the clone, pass NULL for the - * remote's default branch - * @param signature The identity used when updating the reflog. - * @return 0 on success, any non-zero return value from a callback - * function, or a negative value to indicate an error (use - * `giterr_last` for a detailed error message) - */ -GIT_EXTERN(int) git_clone_into( - git_repository *repo, - git_remote *remote, - const git_checkout_options *co_opts, - const char *branch, - const git_signature *signature); - /** @} */ GIT_END_DECL #endif diff --git a/include/git2/commit.h b/include/git2/commit.h index 834330b5d..fb53a701b 100644 --- a/include/git2/commit.h +++ b/include/git2/commit.h @@ -254,7 +254,8 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor( * is not direct, it will be resolved to a direct reference. * Use "HEAD" to update the HEAD of the current branch and * make it point to this commit. If the reference doesn't - * exist yet, it will be created. + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. * * @param author Signature with author and author time of commit * @@ -329,7 +330,7 @@ GIT_EXTERN(int) git_commit_create_v( * * The `update_ref` value works as in the regular `git_commit_create()`, * updating the ref to point to the newly rewritten commit. If you want - * to amend a commit that is not currently the HEAD of the branch and then + * to amend a commit that is not currently the tip of the branch and then * rewrite the following commits to reach a ref, pass this as NULL and * update the rest of the commit chain and ref separately. * diff --git a/include/git2/config.h b/include/git2/config.h index 663b4f6ba..21a5825a5 100644 --- a/include/git2/config.h +++ b/include/git2/config.h @@ -226,6 +226,22 @@ GIT_EXTERN(int) git_config_open_level( */ GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config); +/** + * Create a snapshot of the configuration + * + * Create a snapshot of the current state of a configuration, which + * allows you to look into a consistent view of the configuration for + * looking up complex values (e.g. a remote, submodule). + * + * The string returned when querying such a config object is valid + * until it is freed. + * + * @param out pointer in which to store the snapshot config object + * @param config configuration to snapshot + * @return 0 or an error code + */ +GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config); + /** * Reload changed config files @@ -312,7 +328,8 @@ GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char * Get the value of a string config variable. * * The string is owned by the variable and should not be freed by the - * user. + * user. The pointer will be valid until the next operation on this + * config object. * * All config files will be looked into, in the order of their * defined level. A higher level means a higher priority. The @@ -353,6 +370,9 @@ GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, cons /** * Return the current entry and advance the iterator * + * The pointers returned by this function are valid until the iterator + * is freed. + * * @param entry pointer to store the entry * @param iter the iterator * @return 0 or an error code. GIT_ITEROVER if the iteration has completed @@ -451,6 +471,9 @@ GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, co * If the callback returns a non-zero value, the function stops iterating * and returns that value to the caller. * + * The pointers passed to the callback are only valid as long as the + * iteration is ongoing. + * * @param cfg where to get the variables from * @param callback the function to call on each variable * @param payload the data to pass to the callback @@ -491,6 +514,9 @@ GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const gi * regular expression that filters which config keys are passed to the * callback. * + * The pointers passed to the callback are only valid as long as the + * iteration is ongoing. + * * @param cfg where to get the variables from * @param regexp regular expression to match against config names * @param callback the function to call on each variable diff --git a/include/git2/diff.h b/include/git2/diff.h index 273f471b6..8147fd31c 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -145,6 +145,19 @@ typedef enum { */ GIT_DIFF_ENABLE_FAST_UNTRACKED_DIRS = (1u << 14), + /** When diff finds a file in the working directory with stat + * information different from the index, but the OID ends up being the + * same, write the correct stat information into the index. Note: + * without this flag, diff will always leave the index untouched. + */ + GIT_DIFF_UPDATE_INDEX = (1u << 15), + + /** Include unreadable files in the diff */ + GIT_DIFF_INCLUDE_UNREADABLE = (1u << 16), + + /** Include unreadable files in the diff */ + GIT_DIFF_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 17), + /* * Options controlling how output will be generated */ @@ -205,9 +218,9 @@ typedef struct git_diff git_diff; * considered reserved for internal or future use. */ typedef enum { - GIT_DIFF_FLAG_BINARY = (1u << 0), /** file(s) treated as binary data */ - GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /** file(s) treated as text data */ - GIT_DIFF_FLAG_VALID_ID = (1u << 2), /** `id` value is known correct */ + GIT_DIFF_FLAG_BINARY = (1u << 0), /**< file(s) treated as binary data */ + GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /**< file(s) treated as text data */ + GIT_DIFF_FLAG_VALID_ID = (1u << 2), /**< `id` value is known correct */ } git_diff_flag_t; /** @@ -221,15 +234,16 @@ typedef enum { * DELETED pairs). */ typedef enum { - GIT_DELTA_UNMODIFIED = 0, /** no changes */ - GIT_DELTA_ADDED = 1, /** entry does not exist in old version */ - GIT_DELTA_DELETED = 2, /** entry does not exist in new version */ - GIT_DELTA_MODIFIED = 3, /** entry content changed between old and new */ - GIT_DELTA_RENAMED = 4, /** entry was renamed between old and new */ - GIT_DELTA_COPIED = 5, /** entry was copied from another old entry */ - GIT_DELTA_IGNORED = 6, /** entry is ignored item in workdir */ - GIT_DELTA_UNTRACKED = 7, /** entry is untracked item in workdir */ - GIT_DELTA_TYPECHANGE = 8, /** type of entry changed between old and new */ + GIT_DELTA_UNMODIFIED = 0, /**< no changes */ + GIT_DELTA_ADDED = 1, /**< entry does not exist in old version */ + GIT_DELTA_DELETED = 2, /**< entry does not exist in new version */ + GIT_DELTA_MODIFIED = 3, /**< entry content changed between old and new */ + GIT_DELTA_RENAMED = 4, /**< entry was renamed between old and new */ + GIT_DELTA_COPIED = 5, /**< entry was copied from another old entry */ + GIT_DELTA_IGNORED = 6, /**< entry is ignored item in workdir */ + GIT_DELTA_UNTRACKED = 7, /**< entry is untracked item in workdir */ + GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */ + GIT_DELTA_UNREADABLE = 9, /**< entry is unreadable */ } git_delta_t; /** @@ -381,17 +395,16 @@ typedef struct { {GIT_DIFF_OPTIONS_VERSION, 0, GIT_SUBMODULE_IGNORE_DEFAULT, {NULL,0}, NULL, NULL, 3} /** -* Initializes a `git_diff_options` with default values. Equivalent to -* creating an instance with GIT_DIFF_OPTIONS_INIT. -* -* @param opts the `git_diff_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_DIFF_OPTIONS_VERSION` here. -* @return Zero on success; -1 on failure. -*/ + * Initializes a `git_diff_options` with default values. Equivalent to + * creating an instance with GIT_DIFF_OPTIONS_INIT. + * + * @param opts The `git_diff_options` struct to initialize + * @param version Version of struct; pass `GIT_DIFF_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ GIT_EXTERN(int) git_diff_init_options( - git_diff_options* opts, - int version); + git_diff_options *opts, + unsigned int version); /** * When iterating over a diff, callback that will be made per file. @@ -410,12 +423,12 @@ typedef int (*git_diff_file_cb)( */ typedef struct git_diff_hunk git_diff_hunk; struct git_diff_hunk { - int old_start; /** Starting line number in old_file */ - int old_lines; /** Number of lines in old_file */ - int new_start; /** Starting line number in new_file */ - int new_lines; /** Number of lines in new_file */ - size_t header_len; /** Number of bytes in header text */ - char header[128]; /** Header text, NUL-byte terminated */ + int old_start; /**< Starting line number in old_file */ + int old_lines; /**< Number of lines in old_file */ + int new_start; /**< Starting line number in new_file */ + int new_lines; /**< Number of lines in new_file */ + size_t header_len; /**< Number of bytes in header text */ + char header[128]; /**< Header text, NUL-byte terminated */ }; /** @@ -458,13 +471,13 @@ typedef enum { */ typedef struct git_diff_line git_diff_line; struct git_diff_line { - char origin; /** A git_diff_line_t value */ - int old_lineno; /** Line number in old file or -1 for added line */ - int new_lineno; /** Line number in new file or -1 for deleted line */ - int num_lines; /** Number of newline characters in content */ - size_t content_len; /** Number of bytes of data */ - git_off_t content_offset; /** Offset in the original file to the content */ - const char *content; /** Pointer to diff text, not NUL-byte terminated */ + char origin; /**< A git_diff_line_t value */ + int old_lineno; /**< Line number in old file or -1 for added line */ + int new_lineno; /**< Line number in new file or -1 for deleted line */ + int num_lines; /**< Number of newline characters in content */ + size_t content_len; /**< Number of bytes of data */ + git_off_t content_offset; /**< Offset in the original file to the content */ + const char *content; /**< Pointer to diff text, not NUL-byte terminated */ }; /** @@ -476,10 +489,10 @@ struct git_diff_line { * of lines of file and hunk headers. */ typedef int (*git_diff_line_cb)( - const git_diff_delta *delta, /** delta that contains this data */ - const git_diff_hunk *hunk, /** hunk containing this data */ - const git_diff_line *line, /** line data */ - void *payload); /** user reference data */ + const git_diff_delta *delta, /**< delta that contains this data */ + const git_diff_hunk *hunk, /**< hunk containing this data */ + const git_diff_line *line, /**< line data */ + void *payload); /**< user reference data */ /** * Flags to control the behavior of diff rename/copy detection. @@ -622,17 +635,16 @@ typedef struct { #define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION} /** -* Initializes a `git_diff_find_options` with default values. Equivalent to -* creating an instance with GIT_DIFF_FIND_OPTIONS_INIT. -* -* @param opts the `git_diff_find_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_DIFF_FIND_OPTIONS_VERSION` here. -* @return Zero on success; -1 on failure. -*/ + * Initializes a `git_diff_find_options` with default values. Equivalent to + * creating an instance with GIT_DIFF_FIND_OPTIONS_INIT. + * + * @param opts The `git_diff_find_options` struct to initialize + * @param version Version of struct; pass `GIT_DIFF_FIND_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ GIT_EXTERN(int) git_diff_find_init_options( - git_diff_find_options* opts, - int version); + git_diff_find_options *opts, + unsigned int version); /** @name Diff Generator Functions * @@ -804,23 +816,6 @@ GIT_EXTERN(int) git_diff_find_similar( git_diff *diff, const git_diff_find_options *options); -/** - * Initialize diff options structure - * - * In most cases, you can probably just use `GIT_DIFF_OPTIONS_INIT` to - * initialize the diff options structure, but in some cases that is not - * going to work. You can call this function instead. Note that you - * must pass both a pointer to the structure to be initialized and the - * `GIT_DIFF_OPTIONS_VERSION` value from the header you compiled with. - * - * @param options Pointer to git_diff_options memory to be initialized - * @param version Should be `GIT_DIFF_OPTIONS_VERSION` - * @return 0 on success, negative on failure (such as unsupported version) - */ -GIT_EXTERN(int) git_diff_options_init( - git_diff_options *options, - unsigned int version); - /**@}*/ @@ -1233,17 +1228,17 @@ GIT_EXTERN(int) git_diff_commit_as_email( const git_diff_options *diff_opts); /** -* Initializes a `git_diff_format_email_options` with default values. Equivalent to -* creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT. -* -* @param opts the `git_diff_format_email_options` instance to initialize. -* @param version the version of the struct; you should pass -* `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION` here. -* @return Zero on success; -1 on failure. -*/ + * Initializes a `git_diff_format_email_options` with default values. + * + * Equivalent to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT. + * + * @param opts The `git_diff_format_email_options` struct to initialize + * @param version Version of struct; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION` + * @return Zero on success; -1 on failure. + */ GIT_EXTERN(int) git_diff_format_email_init_options( git_diff_format_email_options *opts, - int version); + unsigned int version); GIT_END_DECL diff --git a/include/git2/errors.h b/include/git2/errors.h index 287498423..1e3ed3acb 100644 --- a/include/git2/errors.h +++ b/include/git2/errors.h @@ -19,13 +19,13 @@ GIT_BEGIN_DECL /** Generic return codes */ typedef enum { - GIT_OK = 0, /*< No error */ + GIT_OK = 0, /**< No error */ - GIT_ERROR = -1, /*< Generic error */ - GIT_ENOTFOUND = -3, /*< Requested object could not be found */ - GIT_EEXISTS = -4, /*< Object exists preventing operation */ - GIT_EAMBIGUOUS = -5, /*< More than one object matches */ - GIT_EBUFS = -6, /*< Output buffer too short to hold data */ + GIT_ERROR = -1, /**< Generic error */ + GIT_ENOTFOUND = -3, /**< Requested object could not be found */ + GIT_EEXISTS = -4, /**< Object exists preventing operation */ + GIT_EAMBIGUOUS = -5, /**< More than one object matches */ + GIT_EBUFS = -6, /**< Output buffer too short to hold data */ /* GIT_EUSER is a special error that is never generated by libgit2 * code. You can return it from a callback (e.g to stop an iteration) @@ -33,17 +33,19 @@ typedef enum { */ GIT_EUSER = -7, - GIT_EBAREREPO = -8, /*< Operation not allowed on bare repository */ - GIT_EUNBORNBRANCH = -9, /*< HEAD refers to branch with no commits */ - GIT_EUNMERGED = -10, /*< Merge in progress prevented operation */ - GIT_ENONFASTFORWARD = -11, /*< Reference was not fast-forwardable */ - GIT_EINVALIDSPEC = -12, /*< Name/ref spec was not in a valid format */ - GIT_EMERGECONFLICT = -13, /*< Merge conflicts prevented operation */ - GIT_ELOCKED = -14, /*< Lock file prevented operation */ - GIT_EMODIFIED = -15, /*< Reference value does not match expected */ + GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository */ + GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits */ + GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */ + GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */ + GIT_EINVALIDSPEC = -12, /**< Name/ref spec was not in a valid format */ + GIT_EMERGECONFLICT = -13, /**< Merge conflicts prevented operation */ + GIT_ELOCKED = -14, /**< Lock file prevented operation */ + GIT_EMODIFIED = -15, /**< Reference value does not match expected */ + GIT_EAUTH = -16, /**< Authentication error */ + GIT_ECERTIFICATE = -17, /**< Server certificate is invalid */ - GIT_PASSTHROUGH = -30, /*< Internal only */ - GIT_ITEROVER = -31, /*< Signals end of iteration with iterator */ + GIT_PASSTHROUGH = -30, /**< Internal only */ + GIT_ITEROVER = -31, /**< Signals end of iteration with iterator */ } git_error_code; /** diff --git a/include/git2/filter.h b/include/git2/filter.h index f96b6766b..e57a67e73 100644 --- a/include/git2/filter.h +++ b/include/git2/filter.h @@ -35,6 +35,11 @@ typedef enum { GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB, } git_filter_mode_t; +typedef enum { + GIT_FILTER_OPT_DEFAULT = 0u, + GIT_FILTER_OPT_ALLOW_UNSAFE = (1u << 0), +} git_filter_opt_t; + /** * A filter that can transform file data * @@ -75,6 +80,7 @@ typedef struct git_filter_list git_filter_list; * @param blob The blob to which the filter will be applied (if known) * @param path Relative path of the file to be filtered * @param mode Filtering direction (WT->ODB or ODB->WT) + * @param options Combination of `git_filter_opt_t` flags * @return 0 on success (which could still return NULL if no filters are * needed for the requested file), <0 on error */ @@ -83,7 +89,8 @@ GIT_EXTERN(int) git_filter_list_load( git_repository *repo, git_blob *blob, /* can be NULL */ const char *path, - git_filter_mode_t mode); + git_filter_mode_t mode, + uint32_t options); /** * Apply filter list to a data buffer. diff --git a/include/git2/index.h b/include/git2/index.h index 05e58a632..0b4476b4e 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -61,7 +61,7 @@ typedef struct git_index_entry { unsigned short flags; unsigned short flags_extended; - char *path; + const char *path; } git_index_entry; /** @@ -73,10 +73,13 @@ typedef struct git_index_entry { */ #define GIT_IDXENTRY_NAMEMASK (0x0fff) #define GIT_IDXENTRY_STAGEMASK (0x3000) -#define GIT_IDXENTRY_EXTENDED (0x4000) -#define GIT_IDXENTRY_VALID (0x8000) #define GIT_IDXENTRY_STAGESHIFT 12 +typedef enum { + GIT_IDXENTRY_EXTENDED = (0x4000), + GIT_IDXENTRY_VALID = (0x8000), +} git_indxentry_flag_t; + #define GIT_IDXENTRY_STAGE(E) \ (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT) @@ -92,36 +95,36 @@ typedef struct git_index_entry { * in-memory only and used by libgit2. Only the flags in * `GIT_IDXENTRY_EXTENDED_FLAGS` will get saved on-disk. * - * These bitmasks match the three fields in the `git_index_entry` - * `flags_extended` value that belong on disk. You can use them to - * interpret the data in the `flags_extended`. + * Thee first three bitmasks match the three fields in the + * `git_index_entry` `flags_extended` value that belong on disk. You + * can use them to interpret the data in the `flags_extended`. + * + * The rest of the bitmasks match the other fields in the `git_index_entry` + * `flags_extended` value that are only used in-memory by libgit2. + * You can use them to interpret the data in the `flags_extended`. + * */ -#define GIT_IDXENTRY_INTENT_TO_ADD (1 << 13) -#define GIT_IDXENTRY_SKIP_WORKTREE (1 << 14) -/* GIT_IDXENTRY_EXTENDED2 is reserved for future extension */ -#define GIT_IDXENTRY_EXTENDED2 (1 << 15) +typedef enum { -#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE) + GIT_IDXENTRY_INTENT_TO_ADD = (1 << 13), + GIT_IDXENTRY_SKIP_WORKTREE = (1 << 14), + /** Reserved for future extension */ + GIT_IDXENTRY_EXTENDED2 = (1 << 15), -/** - * Bitmasks for in-memory only fields of `git_index_entry`'s `flags_extended` - * - * These bitmasks match the other fields in the `git_index_entry` - * `flags_extended` value that are only used in-memory by libgit2. You - * can use them to interpret the data in the `flags_extended`. - */ -#define GIT_IDXENTRY_UPDATE (1 << 0) -#define GIT_IDXENTRY_REMOVE (1 << 1) -#define GIT_IDXENTRY_UPTODATE (1 << 2) -#define GIT_IDXENTRY_ADDED (1 << 3) + GIT_IDXENTRY_EXTENDED_FLAGS = (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE), + GIT_IDXENTRY_UPDATE = (1 << 0), + GIT_IDXENTRY_REMOVE = (1 << 1), + GIT_IDXENTRY_UPTODATE = (1 << 2), + GIT_IDXENTRY_ADDED = (1 << 3), -#define GIT_IDXENTRY_HASHED (1 << 4) -#define GIT_IDXENTRY_UNHASHED (1 << 5) -#define GIT_IDXENTRY_WT_REMOVE (1 << 6) /* remove in work directory */ -#define GIT_IDXENTRY_CONFLICTED (1 << 7) + GIT_IDXENTRY_HASHED = (1 << 4), + GIT_IDXENTRY_UNHASHED = (1 << 5), + GIT_IDXENTRY_WT_REMOVE = (1 << 6), /**< remove in work directory */ + GIT_IDXENTRY_CONFLICTED = (1 << 7), -#define GIT_IDXENTRY_UNPACKED (1 << 8) -#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) + GIT_IDXENTRY_UNPACKED = (1 << 8), + GIT_IDXENTRY_NEW_SKIP_WORKTREE = (1 << 9), +} git_idxentry_extended_flag_t; /** Capabilities of system that affect index actions. */ typedef enum { @@ -412,10 +415,10 @@ GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_en * * This entry is calculated from the entry's flag attribute like this: * - * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT + * (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT * * @param entry The entry - * @returns the stage number + * @return the stage number */ GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry); diff --git a/include/git2/merge.h b/include/git2/merge.h index 6d97e81e6..bd5ebc1bd 100644 --- a/include/git2/merge.h +++ b/include/git2/merge.h @@ -10,6 +10,7 @@ #include "common.h" #include "types.h" #include "oid.h" +#include "oidarray.h" #include "checkout.h" #include "index.h" @@ -57,11 +58,11 @@ typedef struct { */ GIT_EXTERN(int) git_merge_file_init_input( git_merge_file_input *opts, - int version); + unsigned int version); /** * Flags for `git_merge_tree` options. A combination of these flags can be - * passed in via the `flags` value in the `git_merge_tree_opts`. + * passed in via the `flags` value in the `git_merge_options`. */ typedef enum { /** @@ -73,7 +74,7 @@ typedef enum { } git_merge_tree_flag_t; /** - * Merge file favor options for `git_merge_trees_opts` instruct the file-level + * Merge file favor options for `git_merge_options` instruct the file-level * merging functionality how to deal with conflicting regions of the files. */ typedef enum { @@ -164,7 +165,7 @@ typedef struct { */ GIT_EXTERN(int) git_merge_file_init_options( git_merge_file_options *opts, - int version); + unsigned int version); typedef struct { /** @@ -232,7 +233,7 @@ typedef struct { */ GIT_EXTERN(int) git_merge_init_options( git_merge_options *opts, - int version); + unsigned int version); /** * The results of `git_merge_analysis` indicate the merge opportunities. @@ -268,6 +269,26 @@ typedef enum { GIT_MERGE_ANALYSIS_UNBORN = (1 << 3), } git_merge_analysis_t; +typedef enum { + /* + * No configuration was found that suggests a preferred behavior for + * merge. + */ + GIT_MERGE_PREFERENCE_NONE = 0, + + /** + * There is a `merge.ff=false` configuration setting, suggesting that + * the user does not want to allow a fast-forward merge. + */ + GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0), + + /** + * There is a `merge.ff=only` configuration setting, suggesting that + * the user only wants fast-forward merges. + */ + GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1), +} git_merge_preference_t; + /** * Analyzes the given branch(es) and determines the opportunities for * merging them into the HEAD of the repository. @@ -280,6 +301,7 @@ typedef enum { */ GIT_EXTERN(int) git_merge_analysis( git_merge_analysis_t *analysis_out, + git_merge_preference_t *preference_out, git_repository *repo, const git_merge_head **their_heads, size_t their_heads_len); @@ -300,6 +322,21 @@ GIT_EXTERN(int) git_merge_base( const git_oid *two); /** + * Find merge bases between two commits + * + * @param out array in which to store the resulting ids + * @param repo the repository where the commits exist + * @param one one of the commits + * @param two the other commit + * @return 0 on success, GIT_ENOTFOUND if not found or error code + */ +GIT_EXTERN(int) git_merge_bases( + git_oidarray *out, + git_repository *repo, + const git_oid *one, + const git_oid *two); + +/** * Find a merge base given a list of commits * * @param out the OID of a merge base considering all the commits @@ -378,8 +415,8 @@ GIT_EXTERN(int) git_merge_head_from_id( /** * Gets the commit ID that the given `git_merge_head` refers to. * - * @param id pointer to commit id to be filled in * @param head the given merge head + * @return commit id */ GIT_EXTERN(const git_oid *) git_merge_head_id( const git_merge_head *head); @@ -424,8 +461,8 @@ GIT_EXTERN(int) git_merge_file( * @param out The git_merge_file_result to be filled in * @param repo The repository * @param ancestor The index entry for the ancestor file (stage level 1) - * @param our_path The index entry for our file (stage level 2) - * @param their_path The index entry for their file (stage level 3) + * @param ours The index entry for our file (stage level 2) + * @param theirs The index entry for their file (stage level 3) * @param opts The merge file options or NULL * @return 0 on success or error code */ @@ -497,8 +534,8 @@ GIT_EXTERN(int) git_merge_commits( * completes, resolve any conflicts and prepare a commit. * * @param repo the repository to merge - * @param merge_heads the heads to merge into - * @param merge_heads_len the number of heads to merge + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge * @param merge_opts merge options * @param checkout_opts checkout options * @return 0 on success or error code diff --git a/include/git2/message.h b/include/git2/message.h index bcdb72f6a..d78b1dce5 100644 --- a/include/git2/message.h +++ b/include/git2/message.h @@ -29,12 +29,14 @@ GIT_BEGIN_DECL * * @param message The message to be prettified. * - * @param strip_comments Non-zero to remove lines starting with "#", 0 to - * leave them in. + * @param strip_comments Non-zero to remove comment lines, 0 to leave them in. + * + * @param comment_char Comment character. Lines starting with this character + * are considered to be comments and removed if `strip_comments` is non-zero. * * @return 0 or an error code. */ -GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments); +GIT_EXTERN(int) git_message_prettify(git_buf *out, const char *message, int strip_comments, char comment_char); /** @} */ GIT_END_DECL diff --git a/include/git2/net.h b/include/git2/net.h index e70ba1f71..a727696a2 100644 --- a/include/git2/net.h +++ b/include/git2/net.h @@ -41,6 +41,11 @@ struct git_remote_head { git_oid oid; git_oid loid; char *name; + /** + * If the server send a symref mapping for this ref, this will + * point to the target. + */ + char *symref_target; }; /** diff --git a/include/git2/object.h b/include/git2/object.h index 7417ea913..9b13d824e 100644 --- a/include/git2/object.h +++ b/include/git2/object.h @@ -107,6 +107,11 @@ GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj); /** * Get a short abbreviated OID string for the object * + * This starts at the "core.abbrev" length (default 7 characters) and + * iteratively extends to a longer string if that length is ambiguous. + * The result will be unambiguous (at least until new objects are added to + * the repository). + * * @param out Buffer to write string into * @param obj The object to get an ID for * @return 0 on success, <0 for error diff --git a/include/git2/oid.h b/include/git2/oid.h index 1cfd4e5e2..db2f3af70 100644 --- a/include/git2/oid.h +++ b/include/git2/oid.h @@ -116,13 +116,17 @@ GIT_EXTERN(void) git_oid_nfmt(char *out, size_t n, const git_oid *id); GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id); /** - * Format a git_oid into a newly allocated c-string. + * Format a git_oid into a statically allocated c-string. + * + * The c-string is owned by the library and should not be freed + * by the user. If libgit2 is built with thread support, the string + * will be stored in TLS (i.e. one buffer per thread) to allow for + * concurrent calls of the function. * * @param id the oid structure to format - * @return the c-string; NULL if memory is exhausted. Caller must - * deallocate the string with git__free(). + * @return the c-string */ -GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *id); +GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid); /** * Format a git_oid into a buffer as a hex format c-string. diff --git a/include/git2/oidarray.h b/include/git2/oidarray.h new file mode 100644 index 000000000..0b3204597 --- /dev/null +++ b/include/git2/oidarray.h @@ -0,0 +1,40 @@ +/* + * 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_oidarray_h__ +#define INCLUDE_git_oidarray_h__ + +#include "common.h" +#include "oid.h" + +GIT_BEGIN_DECL + +/** Array of object ids */ +typedef struct git_oidarray { + git_oid *ids; + size_t count; +} git_oidarray; + +/** + * Free the OID array + * + * This method must (and must only) be called on `git_oidarray` + * objects where the array is allocated by the library. Not doing so, + * will result in a memory leak. + * + * This does not free the `git_oidarray` itself, since the library will + * never allocate that object directly itself (it is more commonly embedded + * inside another struct or created on the stack). + * + * @param array git_oidarray from which to free oid data + */ +GIT_EXTERN(void) git_oidarray_free(git_oidarray *array); + +/** @} */ +GIT_END_DECL + +#endif + diff --git a/include/git2/pathspec.h b/include/git2/pathspec.h index 2fb0bb716..de6f027c5 100644 --- a/include/git2/pathspec.h +++ b/include/git2/pathspec.h @@ -12,6 +12,8 @@ #include "strarray.h" #include "diff.h" +GIT_BEGIN_DECL + /** * Compiled pathspec */ @@ -257,4 +259,5 @@ GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount( GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry( const git_pathspec_match_list *m, size_t pos); +GIT_END_DECL #endif diff --git a/include/git2/push.h b/include/git2/push.h index 7a8bec12c..cbf115661 100644 --- a/include/git2/push.h +++ b/include/git2/push.h @@ -49,8 +49,8 @@ typedef struct { * @return Zero on success; -1 on failure. */ GIT_EXTERN(int) git_push_init_options( - git_push_options* opts, - int version); + git_push_options *opts, + unsigned int version); /** Push network progress notification function */ typedef int (*git_push_transfer_progress)( diff --git a/include/git2/reflog.h b/include/git2/reflog.h index df06e1b8e..ac42a231c 100644 --- a/include/git2/reflog.h +++ b/include/git2/reflog.h @@ -69,7 +69,7 @@ GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const g * * @param repo the repository * @param old_name the old name of the reference - * @param new_name the new name of the reference + * @param name the new name of the reference * @return 0 on success, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_reflog_rename(git_repository *repo, const char *old_name, const char *name); diff --git a/include/git2/refs.h b/include/git2/refs.h index 6a1db65a8..e5bb15c7c 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -178,7 +178,6 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor * @param name The name of the reference * @param id The object id pointed to by the reference. * @param force Overwrite existing references - * @param force Overwrite existing references * @param signature The identity that will used to populate the reflog entry * @param log_message The one line long message to be appended to the reflog * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code @@ -221,7 +220,6 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, * @param name The name of the reference * @param id The object id pointed to by the reference. * @param force Overwrite existing references - * @param force Overwrite existing references * @param current_id The expected value of the reference at the time of update * @param signature The identity that will used to populate the reflog entry * @param log_message The one line long message to be appended to the reflog @@ -415,7 +413,7 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref); * This method removes the named reference from the repository without * looking at its old value. * - * @param ref The reference to remove + * @param name The reference to remove * @return 0 or an error code */ GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name); @@ -525,6 +523,17 @@ GIT_EXTERN(int) git_reference_iterator_glob_new( */ GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter); +/** + * Get the next reference's name + * + * This function is provided for convenience in case only the names + * are interesting as it avoids the allocation of the `git_reference` + * object which `git_reference_next()` needs. + * + * @param out pointer in which to store the string + * @param iter the iterator + * @return 0, GIT_ITEROVER if there are no more; or an error code + */ GIT_EXTERN(int) git_reference_next_name(const char **out, git_reference_iterator *iter); /** diff --git a/include/git2/remote.h b/include/git2/remote.h index 11e1e26d0..055f5e517 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -384,15 +384,12 @@ GIT_EXTERN(int) git_remote_fetch( const char *reflog_message); /** - * Return whether a string is a valid remote URL * - * @param url the url to check - * @return 1 if the url is valid, 0 otherwise - */ -GIT_EXTERN(int) git_remote_valid_url(const char *url); - -/** - * Return whether the passed URL is supported by this version of the library. + * Return whether the library supports a particular URL scheme + * + * Both the built-in and externally-registered transport lists are + * searched for a transport which supports the scheme of the given + * URL. * * @param url the url to check * @return 1 if the url is supported, 0 otherwise @@ -411,30 +408,6 @@ GIT_EXTERN(int) git_remote_supported_url(const char* url); GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); /** - * Choose whether to check the server's certificate (applies to HTTPS only) - * - * @param remote the remote to configure - * @param check whether to check the server's certificate (defaults to yes) - */ -GIT_EXTERN(void) git_remote_check_cert(git_remote *remote, int check); - -/** - * Sets a custom transport for the remote. The caller can use this function - * to bypass the automatic discovery of a transport by URL scheme (i.e. - * http://, https://, git://) and supply their own transport to be used - * instead. After providing the transport to a remote using this function, - * the transport object belongs exclusively to that remote, and the remote will - * free it when it is freed with git_remote_free. - * - * @param remote the remote to configure - * @param transport the transport object for the remote to use - * @return 0 or an error code - */ -GIT_EXTERN(int) git_remote_set_transport( - git_remote *remote, - git_transport *transport); - -/** * Argument to the completion callback which tells it which operation * finished. */ @@ -475,6 +448,14 @@ struct git_remote_callbacks { git_cred_acquire_cb credentials; /** + * If cert verification fails, this will be called to let the + * user make the final decision of whether to allow the + * connection to proceed. Returns 1 to allow the connection, 0 + * to disallow it or a negative value to indicate an error. + */ + git_transport_certificate_check_cb certificate_check; + + /** * During the download of new data, this will be regularly * called with the current count of progress done by the * indexer. @@ -501,14 +482,13 @@ struct git_remote_callbacks { * Initializes a `git_remote_callbacks` with default values. Equivalent to * creating an instance with GIT_REMOTE_CALLBACKS_INIT. * - * @param opts the `git_remote_callbacks` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_REMOTE_CALLBACKS_VERSION` here. + * @param opts the `git_remote_callbacks` struct to initialize + * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` * @return Zero on success; -1 on failure. */ GIT_EXTERN(int) git_remote_init_callbacks( - git_remote_callbacks* opts, - int version); + git_remote_callbacks *opts, + unsigned int version); /** * Set the callbacks for a remote @@ -573,18 +553,17 @@ GIT_EXTERN(void) git_remote_set_autotag( * * A temporary in-memory remote cannot be given a name with this method. * + * @param problems non-default refspecs cannot be renamed and will be + * stored here for further processing by the caller. Always free this + * strarray on succesful return. * @param remote the remote to rename * @param new_name the new name the remote should bear - * @param callback Optional callback to notify the consumer of fetch refspecs - * that haven't been automatically updated and need potential manual tweaking. - * @param payload Additional data to pass to the callback * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code */ GIT_EXTERN(int) git_remote_rename( + git_strarray *problems, git_remote *remote, - const char *new_name, - git_remote_rename_problem_cb callback, - void *payload); + const char *new_name); /** * Retrieve the update FETCH_HEAD setting. @@ -611,6 +590,35 @@ GIT_EXTERN(void) git_remote_set_update_fetchhead(git_remote *remote, int value); */ GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); +/** +* Delete an existing persisted remote. +* +* All remote-tracking branches and configuration settings +* for the remote will be removed. +* +* @param remote A valid remote +* @return 0 on success, or an error code. +*/ +GIT_EXTERN(int) git_remote_delete(git_remote *remote); + +/** + * Retrieve the name of the remote's default branch + * + * The default branch of a repository is the branch which HEAD points + * to. If the remote does not support reporting this information + * directly, it performs the guess as git does; that is, if there are + * multiple branches which point to the same commit, the first one is + * chosen. If the master branch is a candidate, it wins. + * + * This function must only be called after connecting. + * + * @param out the buffern in which to store the reference name + * @param remote the remote + * @return 0, GIT_ENOTFOUND if the remote does not have any references + * or none of them point to HEAD's commit, or an error message. + */ +GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/repository.h b/include/git2/repository.h index 4433e71a2..268782648 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -196,6 +196,8 @@ GIT_EXTERN(int) git_repository_init( * looking the "template_path" from the options if set, or the * `init.templatedir` global config if not, or falling back on * "/usr/share/git-core/templates" if it exists. + * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is + * specified, use relative paths for the gitdir and core.worktree. */ typedef enum { GIT_REPOSITORY_INIT_BARE = (1u << 0), @@ -204,6 +206,7 @@ typedef enum { GIT_REPOSITORY_INIT_MKDIR = (1u << 3), GIT_REPOSITORY_INIT_MKPATH = (1u << 4), GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), + GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6), } git_repository_init_flag_t; /** @@ -271,14 +274,13 @@ typedef struct { * Initializes a `git_repository_init_options` with default values. Equivalent * to creating an instance with GIT_REPOSITORY_INIT_OPTIONS_INIT. * - * @param opts the `git_repository_init_options` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_REPOSITORY_INIT_OPTIONS_VERSION` here. + * @param opts the `git_repository_init_options` struct to initialize + * @param version Version of struct; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ GIT_EXTERN(int) git_repository_init_init_options( - git_repository_init_options* opts, - int version); + git_repository_init_options *opts, + unsigned int version); /** * Create a new Git repository in the given folder with extended controls. @@ -409,13 +411,29 @@ GIT_EXTERN(int) git_repository_is_bare(git_repository *repo); * The configuration file must be freed once it's no longer * being used by the user. * - * @param out Pointer to store the loaded config file + * @param out Pointer to store the loaded configuration * @param repo A repository object * @return 0, or an error code */ GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); /** + * Get a snapshot of the repository's configuration + * + * Convenience function to take a snapshot from the repository's + * configuration. The contents of this snapshot will not change, + * even if the underlying config files are modified. + * + * The configuration file must be freed once it's no longer + * being used by the user. + * + * @param out Pointer to store the loaded configuration + * @param repo the repository + * @return 0, or an error code + */ +GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo); + +/** * Get the Object Database for this repository. * * If a custom ODB has not been set, the default @@ -547,6 +565,10 @@ GIT_EXTERN(int) git_repository_mergehead_foreach( * hash a file in the repository and you want to apply filtering rules (e.g. * crlf filters) before generating the SHA, then use this function. * + * Note: if the repository has `core.safecrlf` set to fail and the + * filtering triggers that failure, then this function will return an + * error and not calculate the hash of the file. + * * @param out Output value of calculated SHA * @param repo Repository pointer * @param path Path to file on disk whose contents should be hashed. If the @@ -556,6 +578,7 @@ GIT_EXTERN(int) git_repository_mergehead_foreach( * NULL, then the `path` parameter will be used instead. If * this is passed as the empty string, then no filters will be * applied when calculating the hash. + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_hashfile( git_oid *out, @@ -629,7 +652,7 @@ GIT_EXTERN(int) git_repository_set_head_detached( * * @param repo Repository pointer * @param signature The identity that will used to populate the reflog entry - * @param log_message The one line long message to be appended to the reflog + * @param reflog_message The one line long message to be appended to the reflog * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing * branch or an error code */ @@ -642,7 +665,7 @@ typedef enum { GIT_REPOSITORY_STATE_NONE, GIT_REPOSITORY_STATE_MERGE, GIT_REPOSITORY_STATE_REVERT, - GIT_REPOSITORY_STATE_CHERRY_PICK, + GIT_REPOSITORY_STATE_CHERRYPICK, GIT_REPOSITORY_STATE_BISECT, GIT_REPOSITORY_STATE_REBASE, GIT_REPOSITORY_STATE_REBASE_INTERACTIVE, diff --git a/include/git2/reset.h b/include/git2/reset.h index 1759cc036..ea7217efe 100644 --- a/include/git2/reset.h +++ b/include/git2/reset.h @@ -7,6 +7,10 @@ #ifndef INCLUDE_git_reset_h__ #define INCLUDE_git_reset_h__ +#include "common.h" +#include "types.h" +#include "strarray.h" + /** * @file git2/reset.h * @brief Git reset management routines @@ -19,9 +23,9 @@ GIT_BEGIN_DECL * Kinds of reset operation */ typedef enum { - GIT_RESET_SOFT = 1, /** Move the head to the given commit */ - GIT_RESET_MIXED = 2, /** SOFT plus reset index to the commit */ - GIT_RESET_HARD = 3, /** MIXED plus changes in working tree discarded */ + GIT_RESET_SOFT = 1, /**< Move the head to the given commit */ + GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */ + GIT_RESET_HARD = 3, /**< MIXED plus changes in working tree discarded */ } git_reset_t; /** diff --git a/include/git2/revert.h b/include/git2/revert.h index 3a6beb6b8..ab9dd9af9 100644 --- a/include/git2/revert.h +++ b/include/git2/revert.h @@ -37,14 +37,13 @@ typedef struct { * Initializes a `git_revert_options` with default values. Equivalent to * creating an instance with GIT_REVERT_OPTIONS_INIT. * - * @param opts the `git_revert_options` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_REVERT_OPTIONS_VERSION` here. + * @param opts the `git_revert_options` struct to initialize + * @param version Version of struct; pass `GIT_REVERT_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ -GIT_EXTERN(int) git_revert_init_opts( - git_revert_options* opts, - int version); +GIT_EXTERN(int) git_revert_init_options( + git_revert_options *opts, + unsigned int version); /** * Reverts the given commit against the given "our" commit, producing an @@ -57,10 +56,10 @@ GIT_EXTERN(int) git_revert_init_opts( * @param revert_commit the commit to revert * @param our_commit the commit to revert against (eg, HEAD) * @param mainline the parent of the revert commit, if it is a merge - * @param merge_tree_opts the merge tree options (or null for defaults) + * @param merge_options the merge options (or null for defaults) * @return zero on success, -1 on failure. */ -int git_revert_commit( +GIT_EXTERN(int) git_revert_commit( git_index **out, git_repository *repo, git_commit *revert_commit, @@ -72,9 +71,8 @@ int git_revert_commit( * Reverts the given commit, producing changes in the working directory. * * @param repo the repository to revert - * @param commits the commits to revert - * @param commits_len the number of commits to revert - * @param flags merge flags + * @param commit the commit to revert + * @param given_opts merge flags * @return zero on success, -1 on failure. */ GIT_EXTERN(int) git_revert( diff --git a/include/git2/signature.h b/include/git2/signature.h index a1dd1ec7a..feb1b4073 100644 --- a/include/git2/signature.h +++ b/include/git2/signature.h @@ -69,7 +69,7 @@ GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo) * Call `git_signature_free()` to free the data. * * @param dest pointer where to store the copy - * @param entry signature to duplicate + * @param sig signature to duplicate * @return 0 or an error code */ GIT_EXTERN(int) git_signature_dup(git_signature **dest, const git_signature *sig); diff --git a/include/git2/status.h b/include/git2/status.h index 6af45c7dd..3c86e5d7b 100644 --- a/include/git2/status.h +++ b/include/git2/status.h @@ -43,6 +43,7 @@ typedef enum { GIT_STATUS_WT_DELETED = (1u << 9), GIT_STATUS_WT_TYPECHANGE = (1u << 10), GIT_STATUS_WT_RENAMED = (1u << 11), + GIT_STATUS_WT_UNREADABLE = (1u << 12), GIT_STATUS_IGNORED = (1u << 14), } git_status_t; @@ -121,6 +122,11 @@ typedef enum { * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of * doing a "soft" index reload (i.e. reloading the index data if the * file on disk has been modified outside libgit2). + * - GIT_STATUS_OPT_UPDATE_INDEX tells libgit2 to refresh the stat cache + * in the index for files that are unchanged but have out of date stat + * information in the index. It will result in less work being done on + * subsequent calls to get status. This is mutually exclusive with the + * NO_REFRESH option. * * Calling `git_status_foreach()` is like calling the extended version * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED, @@ -128,19 +134,22 @@ typedef enum { * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline. */ typedef enum { - GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0), - GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1), - GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2), - GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3), - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4), - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5), - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6), - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7), - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8), - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9), - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10), - GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11), - GIT_STATUS_OPT_NO_REFRESH = (1u << 12), + GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0), + GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1), + GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2), + GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3), + GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4), + GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5), + GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6), + GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7), + GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8), + GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9), + GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10), + GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11), + GIT_STATUS_OPT_NO_REFRESH = (1u << 12), + GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13), + GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14), + GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15), } git_status_opt_t; #define GIT_STATUS_OPT_DEFAULTS \ @@ -178,14 +187,13 @@ typedef struct { * Initializes a `git_status_options` with default values. Equivalent to * creating an instance with GIT_STATUS_OPTIONS_INIT. * - * @param opts the `git_status_options` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_STATUS_OPTIONS_VERSION` here. + * @param opts The `git_status_options` instance to initialize. + * @param version Version of struct; pass `GIT_STATUS_OPTIONS_VERSION` * @return Zero on success; -1 on failure. */ GIT_EXTERN(int) git_status_init_options( - git_status_options* opts, - int version); + git_status_options *opts, + unsigned int version); /** * A status entry, providing the differences between the file as it exists diff --git a/include/git2/submodule.h b/include/git2/submodule.h index 28e235725..616890df6 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -283,7 +283,7 @@ GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule); * Resolve a submodule url relative to the given repository. * * @param out buffer to store the absolute submodule url in - * @param repository Pointer to repository object + * @param repo Pointer to repository object * @param url Relative url * @return 0 or an error code */ @@ -471,6 +471,24 @@ GIT_EXTERN(git_submodule_recurse_t) git_submodule_set_fetch_recurse_submodules( GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite); /** + * Set up the subrepository for a submodule in preparation for clone. + * + * This function can be called to init and set up a submodule + * repository from a submodule in preparation to clone it from + * its remote. + * + * @param out Output pointer to the created git repository. + * @param sm The submodule to create a new subrepository from. + * @param use_gitlink Should the workdir contain a gitlink to + * the repo in .git/modules vs. repo directly in workdir. + * @return 0 on success, <0 on failure. + */ +GIT_EXTERN(int) git_submodule_repo_init( + git_repository **out, + const git_submodule *sm, + int use_gitlink); + +/** * Copy submodule remote info into submodule repo. * * This copies the information about the submodules URL into the checked out diff --git a/include/git2/sys/config.h b/include/git2/sys/config.h index 3df2ba327..85e0d6417 100644 --- a/include/git2/sys/config.h +++ b/include/git2/sys/config.h @@ -57,13 +57,15 @@ struct git_config_backend { /* Open means open the file/database and parse if necessary */ int (*open)(struct git_config_backend *, git_config_level_t level); - int (*get)(const struct git_config_backend *, const char *key, const git_config_entry **entry); + int (*get)(struct git_config_backend *, const char *key, const git_config_entry **entry); int (*set)(struct git_config_backend *, const char *key, const char *value); int (*set_multivar)(git_config_backend *cfg, const char *name, const char *regexp, const char *value); int (*del)(struct git_config_backend *, const char *key); int (*del_multivar)(struct git_config_backend *, const char *key, const char *regexp); int (*iterator)(git_config_iterator **, struct git_config_backend *); int (*refresh)(struct git_config_backend *); + /** Produce a read-only version of this backend */ + int (*snapshot)(struct git_config_backend **, struct git_config_backend *); void (*free)(struct git_config_backend *); }; #define GIT_CONFIG_BACKEND_VERSION 1 @@ -73,14 +75,13 @@ struct git_config_backend { * Initializes a `git_config_backend` with default values. Equivalent to * creating an instance with GIT_CONFIG_BACKEND_INIT. * - * @param opts the `git_config_backend` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_CONFIG_BACKEND_VERSION` here. + * @param opts 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, - int version); + git_config_backend *backend, + unsigned int version); /** * Add a generic config file instance to an existing config diff --git a/include/git2/sys/diff.h b/include/git2/sys/diff.h index bc6cdf393..48d72f4f9 100644 --- a/include/git2/sys/diff.h +++ b/include/git2/sys/diff.h @@ -10,6 +10,8 @@ #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 @@ -58,6 +60,32 @@ GIT_EXTERN(int) git_diff_print_callback__to_file_handle( const git_diff_line *line, void *payload); /*< payload must be a `FILE *` */ + +typedef struct { + unsigned int version; + size_t stat_calls; + size_t oid_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/filter.h b/include/git2/sys/filter.h index 8fe21c9c0..60248271a 100644 --- a/include/git2/sys/filter.h +++ b/include/git2/sys/filter.h @@ -55,7 +55,10 @@ GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); * your own chains of filters. */ GIT_EXTERN(int) git_filter_list_new( - git_filter_list **out, git_repository *repo, git_filter_mode_t mode); + 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. @@ -115,10 +118,15 @@ GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src); /** - * Get the git_filter_mode_t to be applied + * 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_opt_t options to be applied + */ +GIT_EXTERN(uint32_t) git_filter_source_options(const git_filter_source *src); + /* * struct git_filter * diff --git a/include/git2/sys/odb_backend.h b/include/git2/sys/odb_backend.h index 77fe0dd31..1fc3c3159 100644 --- a/include/git2/sys/odb_backend.h +++ b/include/git2/sys/odb_backend.h @@ -93,14 +93,13 @@ struct git_odb_backend { * Initializes a `git_odb_backend` with default values. Equivalent to * creating an instance with GIT_ODB_BACKEND_INIT. * - * @param opts the `git_odb_backend` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_ODB_BACKEND_VERSION` here. + * @param opts 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, - int version); + git_odb_backend *backend, + unsigned int version); GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h index dce142c77..3b216a287 100644 --- a/include/git2/sys/refdb_backend.h +++ b/include/git2/sys/refdb_backend.h @@ -162,14 +162,13 @@ struct git_refdb_backend { * Initializes a `git_refdb_backend` with default values. Equivalent to * creating an instance with GIT_REFDB_BACKEND_INIT. * - * @param opts the `git_refdb_backend` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_REFDB_BACKEND_VERSION` here. + * @param opts 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, - int version); + git_refdb_backend *backend, + unsigned int version); /** * Constructors for default filesystem-based refdb backend diff --git a/include/git2/sys/repository.h b/include/git2/sys/repository.h index 36f8b5836..dd7b22e06 100644 --- a/include/git2/sys/repository.h +++ b/include/git2/sys/repository.h @@ -119,6 +119,19 @@ GIT_EXTERN(void) git_repository_set_refdb(git_repository *repo, git_refdb *refdb */ GIT_EXTERN(void) 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); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h new file mode 100644 index 000000000..1e8f4e4ed --- /dev/null +++ b/include/git2/sys/transport.h @@ -0,0 +1,352 @@ +/* + * 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/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 enum { + GIT_TRANSPORTFLAGS_NONE = 0, +} git_transport_flags_t; + +typedef struct git_transport git_transport; + +struct git_transport { + unsigned int version; + /* Set progress and error callbacks */ + int (*set_callbacks)( + git_transport *transport, + git_transport_message_cb progress_cb, + git_transport_message_cb error_cb, + git_transport_certificate_check_cb certificate_check_cb, + void *payload); + + /* Connect the transport to the remote repository, using the given + * direction. */ + int (*connect)( + git_transport *transport, + const char *url, + git_cred_acquire_cb cred_acquire_cb, + void *cred_acquire_payload, + int direction, + int flags); + + /* This function may be called after a successful call to + * connect(). The array returned is owned by the transport and + * is guranteed until the next call of a transport function. */ + int (*ls)( + const git_remote_head ***out, + size_t *size, + git_transport *transport); + + /* Executes the push whose context is in the git_push object. */ + int (*push)(git_transport *transport, git_push *push); + + /* This function may be called after a successful call to connect(), when + * the direction is FETCH. The function performs a negotiation to calculate + * the wants list for the fetch. */ + int (*negotiate_fetch)( + git_transport *transport, + git_repository *repo, + const git_remote_head * const *refs, + size_t count); + + /* This function may be called after a successful call to negotiate_fetch(), + * when the direction is FETCH. This function retrieves the pack file for + * the fetch from the remote end. */ + int (*download_pack)( + git_transport *transport, + git_repository *repo, + git_transfer_progress *stats, + git_transfer_progress_cb progress_cb, + void *progress_payload); + + /* Checks to see if the transport is connected */ + int (*is_connected)(git_transport *transport); + + /* Reads the flags value previously passed into connect() */ + int (*read_flags)(git_transport *transport, int *flags); + + /* Cancels any outstanding transport operation */ + void (*cancel)(git_transport *transport); + + /* This function is the reverse of connect() -- it terminates the + * connection to the remote end. */ + int (*close)(git_transport *transport); + + /* Frees/destructs the git_transport object. */ + void (*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); + +/* Signature of a function which creates a transport */ +typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param); + +/** + * 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. + * + * @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); + +/* + *** End of base transport interface *** + *** Begin interface for subtransports for the smart transport *** + */ + +/* 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 implemented: git, http, and winhttp. (The http and + * winhttp transports each implement both http and https.) */ + +/* 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 and winhttp are both + * RPC = 1. */ + +/* 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 */ +struct git_smart_subtransport_stream { + /* The owning subtransport */ + git_smart_subtransport *subtransport; + + int (*read)( + git_smart_subtransport_stream *stream, + char *buffer, + size_t buf_size, + size_t *bytes_read); + + int (*write)( + git_smart_subtransport_stream *stream, + const char *buffer, + size_t len); + + void (*free)( + git_smart_subtransport_stream *stream); +}; + +/* An implementation of a subtransport which carries data for the + * smart transport */ +struct git_smart_subtransport { + int (* action)( + git_smart_subtransport_stream **out, + git_smart_subtransport *transport, + const char *url, + git_smart_service_t action); + + /* Subtransports are guaranteed a call to close() between + * calls to action(), except for the following two "natural" progressions + * of actions against a constant URL. + * + * 1. UPLOADPACK_LS -> UPLOADPACK + * 2. RECEIVEPACK_LS -> RECEIVEPACK */ + int (*close)(git_smart_subtransport *transport); + + void (*free)(git_smart_subtransport *transport); +}; + +/* A function which creates a new subtransport for the smart transport */ +typedef int (*git_smart_subtransport_cb)( + git_smart_subtransport **out, + git_transport* owner); + +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; +} git_smart_subtransport_definition; + +/* Smart transport subtransports that come with libgit2 */ + +/** + * Create an instance of the http subtransport. This subtransport + * also supports https. On Win32, this subtransport may be implemented + * using the WinHTTP library. + * + * @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); + +/** + * 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); + +/** + * 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); + +/** + * Sets a custom transport factory for the remote. The caller can use this + * function to override the transport used for this remote when performing + * network operations. + * + * @param remote the remote to configure + * @param transport_cb the function to use to create a transport + * @param payload opaque parameter passed to transport_cb + * @return 0 or an error code + */ +GIT_EXTERN(int) git_remote_set_transport( + git_remote *remote, + git_transport_cb transport_cb, + void *payload); + +/** @} */ +GIT_END_DECL +#endif diff --git a/include/git2/transport.h b/include/git2/transport.h index a33146ca8..39df479c7 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -11,10 +11,6 @@ #include "net.h" #include "types.h" -#ifdef GIT_SSH -#include <libssh2.h> -#endif - /** * @file git2/transport.h * @brief Git transport interfaces and functions @@ -24,6 +20,63 @@ */ GIT_BEGIN_DECL +/** + * Type of SSH host fingerprint + */ +typedef enum { + /** MD5 is available */ + GIT_CERT_SSH_MD5 = (1 << 0), + /** SHA-1 is available */ + GIT_CERT_SSH_SHA1 = (1 << 1), +} git_cert_ssh_t; + +/** + * Hostkey information taken from libssh2 + */ +typedef struct { + /** + * Type of certificate. Here to share the header with + * `git_cert`. + */ + git_cert_t cert_type; + /** + * A hostkey type from libssh2, either + * `GIT_CERT_SSH_MD5` or `GIT_CERT_SSH_SHA1` + */ + git_cert_ssh_t type; + + /** + * Hostkey hash. If type has `GIT_CERT_SSH_MD5` set, this will + * have the MD5 hash of the hostkey. + */ + unsigned char hash_md5[16]; + + /** + * Hostkey hash. If type has `GIT_CERT_SSH_SHA1` set, this will + * have the SHA-1 hash of the hostkey. + */ + unsigned char hash_sha1[20]; +} git_cert_hostkey; + +/** + * X.509 certificate information + */ +typedef struct { + /** + * Type of certificate. Here to share the header with + * `git_cert`. + */ + git_cert_t cert_type; + /** + * Pointer to the X.509 certificate data + */ + void *data; + /** + * Length of the memory block pointed to by `data`. + */ + size_t len; +} git_cert_x509; + /* *** Begin interface for credentials acquisition *** */ @@ -44,6 +97,14 @@ typedef enum { /* git_cred_ssh_interactive */ GIT_CREDTYPE_SSH_INTERACTIVE = (1u << 4), + + /** + * Username-only information + * + * If the SSH transport does not know which username to use, + * it will ask via this credential type. + */ + GIT_CREDTYPE_USERNAME = (1u << 5), } git_credtype_t; /* The base structure for all credential types */ @@ -61,14 +122,20 @@ typedef struct { char *password; } git_cred_userpass_plaintext; -#ifdef GIT_SSH -typedef LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC((*git_cred_sign_callback)); -typedef LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC((*git_cred_ssh_interactive_callback)); -#else -typedef int (*git_cred_sign_callback)(void *, ...); -typedef int (*git_cred_ssh_interactive_callback)(void *, ...); + +/* + * If the user hasn't included libssh2.h before git2.h, we need to + * define a few types for the callback signatures. + */ +#ifndef LIBSSH2_VERSION +typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; +typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; +typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; #endif +typedef int (*git_cred_sign_callback)(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, const unsigned char *data, size_t data_len, void **abstract); +typedef void (*git_cred_ssh_interactive_callback)(const char* name, int name_len, const char* instruction, int instruction_len, int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT* prompts, LIBSSH2_USERAUTH_KBDINT_RESPONSE* responses, void **abstract); + /** * A ssh key from disk */ @@ -105,6 +172,12 @@ typedef struct git_cred_ssh_custom { /** A key for NTLM/Kerberos "default" credentials */ typedef struct git_cred git_cred_default; +/** Username-only credential information */ +typedef struct git_cred_username { + git_cred parent; + char username[1]; +} git_cred_username; + /** * Check whether a credential object contains username information. * @@ -207,6 +280,14 @@ GIT_EXTERN(int) git_cred_ssh_custom_new( GIT_EXTERN(int) git_cred_default_new(git_cred **out); /** + * Create a credential to specify a username. + * + * This is used with ssh authentication to query for the username if + * none is specified in the url. + */ +GIT_EXTERN(int) git_cred_username_new(git_cred **cred, const char *username); + +/** * Signature of a function which acquires a credential object. * * - cred: The newly created credential object. @@ -225,320 +306,6 @@ typedef int (*git_cred_acquire_cb)( unsigned int allowed_types, void *payload); -/* - *** End interface for credentials acquisition *** - *** Begin base transport interface *** - */ - -typedef enum { - GIT_TRANSPORTFLAGS_NONE = 0, - /* If the connection is secured with SSL/TLS, the authenticity - * of the server certificate should not be verified. */ - GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1 -} git_transport_flags_t; - -typedef int (*git_transport_message_cb)(const char *str, int len, void *data); - -typedef struct git_transport git_transport; - -struct git_transport { - unsigned int version; - /* Set progress and error callbacks */ - int (*set_callbacks)( - git_transport *transport, - git_transport_message_cb progress_cb, - git_transport_message_cb error_cb, - void *payload); - - /* Connect the transport to the remote repository, using the given - * direction. */ - int (*connect)( - git_transport *transport, - const char *url, - git_cred_acquire_cb cred_acquire_cb, - void *cred_acquire_payload, - int direction, - int flags); - - /* This function may be called after a successful call to - * connect(). The array returned is owned by the transport and - * is guranteed until the next call of a transport function. */ - int (*ls)( - const git_remote_head ***out, - size_t *size, - git_transport *transport); - - /* Executes the push whose context is in the git_push object. */ - int (*push)(git_transport *transport, git_push *push); - - /* This function may be called after a successful call to connect(), when - * the direction is FETCH. The function performs a negotiation to calculate - * the wants list for the fetch. */ - int (*negotiate_fetch)( - git_transport *transport, - git_repository *repo, - const git_remote_head * const *refs, - size_t count); - - /* This function may be called after a successful call to negotiate_fetch(), - * when the direction is FETCH. This function retrieves the pack file for - * the fetch from the remote end. */ - int (*download_pack)( - git_transport *transport, - git_repository *repo, - git_transfer_progress *stats, - git_transfer_progress_cb progress_cb, - void *progress_payload); - - /* Checks to see if the transport is connected */ - int (*is_connected)(git_transport *transport); - - /* Reads the flags value previously passed into connect() */ - int (*read_flags)(git_transport *transport, int *flags); - - /* Cancels any outstanding transport operation */ - void (*cancel)(git_transport *transport); - - /* This function is the reverse of connect() -- it terminates the - * connection to the remote end. */ - int (*close)(git_transport *transport); - - /* Frees/destructs the git_transport object. */ - void (*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` instance to initialize. - * @param version the version of the struct; you should pass - * `GIT_TRANSPORT_VERSION` here. - * @return Zero on success; -1 on failure. - */ -GIT_EXTERN(int) git_transport_init( - git_transport* opts, - 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); - -/* Signature of a function which creates a transport */ -typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param); - -/** - * 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 priority The priority of this transport relative to others with - * the same prefix. Built-in transports have a priority of 1. - * @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, - unsigned priority, - git_transport_cb cb, - void *param); - -/** - * - * Unregister a custom transport definition which was previously registered - * with git_transport_register. - * - * @param prefix From the previous call to git_transport_register - * @param priority From the previous call to git_transport_register - * @return 0 or an error code - */ -GIT_EXTERN(int) git_transport_unregister( - const char *prefix, - unsigned priority); - -/* 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); - -/* - *** End of base transport interface *** - *** Begin interface for subtransports for the smart transport *** - */ - -/* 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 implemented: git, http, and winhttp. (The http and - * winhttp transports each implement both http and https.) */ - -/* 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 and winhttp are both - * RPC = 1. */ - -/* 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 */ -struct git_smart_subtransport_stream { - /* The owning subtransport */ - git_smart_subtransport *subtransport; - - int (*read)( - git_smart_subtransport_stream *stream, - char *buffer, - size_t buf_size, - size_t *bytes_read); - - int (*write)( - git_smart_subtransport_stream *stream, - const char *buffer, - size_t len); - - void (*free)( - git_smart_subtransport_stream *stream); -}; - -/* An implementation of a subtransport which carries data for the - * smart transport */ -struct git_smart_subtransport { - int (* action)( - git_smart_subtransport_stream **out, - git_smart_subtransport *transport, - const char *url, - git_smart_service_t action); - - /* Subtransports are guaranteed a call to close() between - * calls to action(), except for the following two "natural" progressions - * of actions against a constant URL. - * - * 1. UPLOADPACK_LS -> UPLOADPACK - * 2. RECEIVEPACK_LS -> RECEIVEPACK */ - int (*close)(git_smart_subtransport *transport); - - void (*free)(git_smart_subtransport *transport); -}; - -/* A function which creates a new subtransport for the smart transport */ -typedef int (*git_smart_subtransport_cb)( - git_smart_subtransport **out, - git_transport* owner); - -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; -} git_smart_subtransport_definition; - -/* Smart transport subtransports that come with libgit2 */ - -/** - * Create an instance of the http subtransport. This subtransport - * also supports https. On Win32, this subtransport may be implemented - * using the WinHTTP library. - * - * @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); - -/** - * 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); - -/** - * 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); - -/* - *** End interface for subtransports for the smart transport *** - */ - /** @} */ GIT_END_DECL #endif diff --git a/include/git2/tree.h b/include/git2/tree.h index 6669652ae..42b68193e 100644 --- a/include/git2/tree.h +++ b/include/git2/tree.h @@ -151,7 +151,7 @@ GIT_EXTERN(int) git_tree_entry_bypath( * and must be freed explicitly with `git_tree_entry_free()`. * * @param dest pointer where to store the copy - * @param entry tree entry to duplicate + * @param source tree entry to duplicate * @return 0 or an error code */ GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source); @@ -301,8 +301,10 @@ GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( * If an entry named `filename` already exists, its attributes * will be updated with the given ones. * - * The optional pointer `out` can be used to retrieve a pointer to - * the newly created/updated entry. Pass NULL if you do not need it. + * The optional pointer `out` can be used to retrieve a pointer to the + * newly created/updated entry. Pass NULL if you do not need it. The + * pointer may not be valid past the next operation in this + * builder. Duplicate the entry if you want to keep it. * * No attempt is being made to ensure that the provided oid points * to an existing git object in the object database, nor that the diff --git a/include/git2/types.h b/include/git2/types.h index 1b6f4cca1..7ee7cc344 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -154,15 +154,15 @@ typedef struct git_packbuilder git_packbuilder; /** Time in a signature */ typedef struct git_time { - git_time_t time; /** time in seconds from epoch */ - int offset; /** timezone offset, in minutes */ + git_time_t time; /**< time in seconds from epoch */ + int offset; /**< timezone offset, in minutes */ } git_time; /** An action signature (e.g. for committers, taggers, etc) */ typedef struct git_signature { - char *name; /** full name of the author */ - char *email; /** email of the author */ - git_time when; /** time when the action happened */ + char *name; /**< full name of the author */ + char *email; /**< email of the author */ + git_time when; /**< time when the action happened */ } git_signature; /** In-memory representation of a reference. */ @@ -183,9 +183,9 @@ typedef struct git_status_list git_status_list; /** Basic type of any Git reference. */ typedef enum { - GIT_REF_INVALID = 0, /** Invalid reference */ - GIT_REF_OID = 1, /** A reference which points at an object id */ - GIT_REF_SYMBOLIC = 2, /** A reference which points at another reference */ + GIT_REF_INVALID = 0, /**< Invalid reference */ + GIT_REF_OID = 1, /**< A reference which points at an object id */ + GIT_REF_SYMBOLIC = 2, /**< A reference which points at another reference */ GIT_REF_LISTALL = GIT_REF_OID|GIT_REF_SYMBOLIC, } git_ref_t; @@ -198,12 +198,12 @@ typedef enum { /** Valid modes for index and tree entries. */ typedef enum { - GIT_FILEMODE_NEW = 0000000, - GIT_FILEMODE_TREE = 0040000, - GIT_FILEMODE_BLOB = 0100644, - GIT_FILEMODE_BLOB_EXECUTABLE = 0100755, - GIT_FILEMODE_LINK = 0120000, - GIT_FILEMODE_COMMIT = 0160000, + GIT_FILEMODE_UNREADABLE = 0000000, + GIT_FILEMODE_TREE = 0040000, + GIT_FILEMODE_BLOB = 0100644, + GIT_FILEMODE_BLOB_EXECUTABLE = 0100755, + GIT_FILEMODE_LINK = 0120000, + GIT_FILEMODE_COMMIT = 0160000, } git_filemode_t; typedef struct git_refspec git_refspec; @@ -244,6 +244,54 @@ typedef struct git_transfer_progress { typedef int (*git_transfer_progress_cb)(const git_transfer_progress *stats, void *payload); /** + * Type for messages delivered by the transport. Return a negative value + * to cancel the network operation. + * + * @param str The message from the transport + * @param len The length of the message + * @param payload Payload provided by the caller + */ +typedef int (*git_transport_message_cb)(const char *str, int len, void *payload); + +/** + * Type of host certificate structure that is passed to the check callback + */ +typedef enum git_cert_t { + /** + * The `data` argument to the callback will be a pointer to + * the DER-encoded data. + */ + GIT_CERT_X509, + /** + * The `data` argument to the callback will be a pointer to a + * `git_cert_hostkey` structure. + */ + GIT_CERT_HOSTKEY_LIBSSH2, +} git_cert_t; + +/** + * Parent type for `git_cert_hostkey` and `git_cert_x509`. + */ +typedef struct { + /** + * Type of certificate. A `GIT_CERT_` value. + */ + git_cert_t cert_type; +} git_cert; + +/** + * Callback for the user's custom certificate checks. + * + * @param type The type of certificate or host info, SSH or X.509 + * @param data The data for the certificate or host info + * @param len The size of the certificate or host info + * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think + * this certificate is valid + * @param payload Payload provided by the caller + */ +typedef int (*git_transport_certificate_check_cb)(git_cert *cert, int valid, void *payload); + +/** * Opaque structure representing a submodule. */ typedef struct git_submodule git_submodule; @@ -314,12 +362,12 @@ typedef enum { * when we don't want any particular ignore rule to be specified. */ typedef enum { - GIT_SUBMODULE_IGNORE_RESET = -1, /* reset to on-disk value */ + GIT_SUBMODULE_IGNORE_RESET = -1, /**< reset to on-disk value */ - GIT_SUBMODULE_IGNORE_NONE = 1, /* any change or untracked == dirty */ - GIT_SUBMODULE_IGNORE_UNTRACKED = 2, /* dirty if tracked files change */ - GIT_SUBMODULE_IGNORE_DIRTY = 3, /* only dirty if HEAD moved */ - GIT_SUBMODULE_IGNORE_ALL = 4, /* never dirty */ + GIT_SUBMODULE_IGNORE_NONE = 1, /**< any change or untracked == dirty */ + GIT_SUBMODULE_IGNORE_UNTRACKED = 2, /**< dirty if tracked files change */ + GIT_SUBMODULE_IGNORE_DIRTY = 3, /**< only dirty if HEAD moved */ + GIT_SUBMODULE_IGNORE_ALL = 4, /**< never dirty */ GIT_SUBMODULE_IGNORE_DEFAULT = 0 } git_submodule_ignore_t; diff --git a/include/git2/version.h b/include/git2/version.h index c4c5e8eb1..5bda42735 100644 --- a/include/git2/version.h +++ b/include/git2/version.h @@ -7,9 +7,11 @@ #ifndef INCLUDE_git_version_h__ #define INCLUDE_git_version_h__ -#define LIBGIT2_VERSION "0.20.0" +#define LIBGIT2_VERSION "0.21.0" #define LIBGIT2_VER_MAJOR 0 -#define LIBGIT2_VER_MINOR 20 +#define LIBGIT2_VER_MINOR 21 #define LIBGIT2_VER_REVISION 0 +#define LIBGIT2_SOVERSION 21 + #endif |