diff options
| author | Ben Straub <bs@github.com> | 2012-11-27 18:59:22 -0800 |
|---|---|---|
| committer | Ben Straub <bs@github.com> | 2012-11-27 18:59:22 -0800 |
| commit | 64c5112188647fcbfbe2bbfb897abfbc21912ba8 (patch) | |
| tree | 5113408a049178d14664f72cc1666655783d95d5 /include/git2 | |
| parent | 469827812f95e979e3c6468567b2c9ed138a9849 (diff) | |
| parent | ca94e031fa21787ae6336f0aada1b01b2dd22077 (diff) | |
| download | libgit2-64c5112188647fcbfbe2bbfb897abfbc21912ba8.tar.gz | |
Merge pull request #1087 from libgit2/great-renaming
The Great Renaming of 2012
Diffstat (limited to 'include/git2')
34 files changed, 711 insertions, 549 deletions
diff --git a/include/git2/attr.h b/include/git2/attr.h index 2de9f4b0e..b1a7e0eb6 100644 --- a/include/git2/attr.h +++ b/include/git2/attr.h @@ -183,6 +183,8 @@ GIT_EXTERN(int) git_attr_get_many( size_t num_attr, const char **names); +typedef int (*git_attr_foreach_cb)(const char *name, const char *value, void *payload); + /** * Loop over all the git attributes for a path. * @@ -204,7 +206,7 @@ GIT_EXTERN(int) git_attr_foreach( git_repository *repo, uint32_t flags, const char *path, - int (*callback)(const char *name, const char *value, void *payload), + git_attr_foreach_cb callback, void *payload); /** diff --git a/include/git2/blob.h b/include/git2/blob.h index f0719f15d..a68c78b5a 100644 --- a/include/git2/blob.h +++ b/include/git2/blob.h @@ -68,6 +68,17 @@ GIT_INLINE(void) git_blob_free(git_blob *blob) git_object_free((git_object *) blob); } +/** + * Get the id of a blob. + * + * @param blob a previously loaded blob. + * @return SHA1 hash for this blob. + */ +GIT_INLINE(const git_oid *) git_blob_id(const git_blob *blob) +{ + return git_object_id((const git_object *)blob); +} + /** * Get a read-only buffer with the raw content of a blob. @@ -88,32 +99,35 @@ GIT_EXTERN(const void *) git_blob_rawcontent(git_blob *blob); * @param blob pointer to the blob * @return size on bytes */ -GIT_EXTERN(size_t) git_blob_rawsize(git_blob *blob); +GIT_EXTERN(git_off_t) git_blob_rawsize(git_blob *blob); /** * Read a file from the working folder of a repository * and write it to the Object Database as a loose blob * - * @param oid return the id of the written blob + * @param id return the id of the written blob * @param repo repository where the blob will be written. * this repository cannot be bare - * @param path file from which the blob will be created, + * @param relative_path file from which the blob will be created, * relative to the repository's working dir * @return 0 or an error code */ -GIT_EXTERN(int) git_blob_create_fromfile(git_oid *oid, git_repository *repo, const char *path); +GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path); /** * Read a file from the filesystem and write its content * to the Object Database as a loose blob * - * @param oid return the id of the written blob + * @param id return the id of the written blob * @param repo repository where the blob will be written. * this repository can be bare or not * @param path file from which the blob will be created * @return 0 or an error code */ -GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, const char *path); +GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *id, git_repository *repo, const char *path); + + +typedef int (*git_blob_chunk_cb)(char *content, size_t max_length, void *payload); /** * Write a loose blob to the Object Database from a @@ -141,7 +155,7 @@ GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, con * - When an error occurs, the callback should return -1. * * - * @param oid Return the id of the written blob + * @param id Return the id of the written blob * * @param repo repository where the blob will be written. * This repository can be bare or not. @@ -152,10 +166,10 @@ GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *oid, git_repository *repo, con * @return GIT_SUCCESS or an error code */ GIT_EXTERN(int) git_blob_create_fromchunks( - git_oid *oid, + git_oid *id, git_repository *repo, const char *hintpath, - int (*source_cb)(char *content, size_t max_length, void *payload), + git_blob_chunk_cb callback, void *payload); /** diff --git a/include/git2/branch.h b/include/git2/branch.h index f06609a51..c9ae9cc5d 100644 --- a/include/git2/branch.h +++ b/include/git2/branch.h @@ -29,7 +29,7 @@ GIT_BEGIN_DECL * * The returned reference must be freed by the user. * - * @param branch_out Pointer where to store the underlying reference. + * @param out Pointer where to store the underlying reference. * * @param branch_name Name for the branch; this name is * validated for consistency. It should also not conflict with @@ -47,10 +47,10 @@ GIT_BEGIN_DECL * pointing to the provided target commit. */ GIT_EXTERN(int) git_branch_create( - git_reference **branch_out, + git_reference **out, git_repository *repo, const char *branch_name, - const git_object *target, + const git_commit *target, int force); /** @@ -113,7 +113,7 @@ GIT_EXTERN(int) git_branch_move( * * The generated reference must be freed by the user. * - * @param branch_out pointer to the looked-up branch reference + * @param out pointer to the looked-up branch reference * * @param repo the repository to look up the branch * @@ -127,7 +127,7 @@ GIT_EXTERN(int) git_branch_move( * exists, otherwise an error code. */ GIT_EXTERN(int) git_branch_lookup( - git_reference **branch_out, + git_reference **out, git_repository *repo, const char *branch_name, git_branch_t branch_type); @@ -136,7 +136,7 @@ GIT_EXTERN(int) git_branch_lookup( * Return the reference supporting the remote tracking branch, * given a local branch reference. * - * @param tracking_out Pointer where to store the retrieved + * @param out Pointer where to store the retrieved * reference. * * @param branch Current underlying reference of the branch. @@ -145,7 +145,7 @@ GIT_EXTERN(int) git_branch_lookup( * reference exists, otherwise an error code. */ GIT_EXTERN(int) git_branch_tracking( - git_reference **tracking_out, + git_reference **out, git_reference *branch); /** diff --git a/include/git2/checkout.h b/include/git2/checkout.h index 27ecc7102..bd988db2c 100644 --- a/include/git2/checkout.h +++ b/include/git2/checkout.h @@ -146,8 +146,12 @@ typedef enum { * Checkout options structure * * Use zeros to indicate default settings. + * This needs to be initialized with the `GIT_CHECKOUT_OPTS_INIT` macro: + * + * git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT; */ typedef struct git_checkout_opts { + unsigned int version; unsigned int checkout_strategy; /** default will be a dry run */ int disable_filters; /** don't apply filters like CRLF conversion */ @@ -182,6 +186,8 @@ typedef struct git_checkout_opts { git_strarray paths; } git_checkout_opts; +#define GIT_CHECKOUT_OPTS_INIT {1, 0} + /** * Updates files in the index and the working tree to match the content of the * commit pointed at by HEAD. @@ -223,7 +229,7 @@ GIT_EXTERN(int) git_checkout_index( */ GIT_EXTERN(int) git_checkout_tree( git_repository *repo, - git_object *treeish, + const git_object *treeish, git_checkout_opts *opts); /** @} */ diff --git a/include/git2/clone.h b/include/git2/clone.h index 7d8d32118..2a0272339 100644 --- a/include/git2/clone.h +++ b/include/git2/clone.h @@ -42,9 +42,9 @@ GIT_EXTERN(int) git_clone( git_repository **out, const char *origin_url, const char *workdir_path, + git_checkout_opts *checkout_opts, git_transfer_progress_callback fetch_progress_cb, - void *fetch_progress_payload, - git_checkout_opts *checkout_opts); + void *fetch_progress_payload); /** * Create a bare clone of a remote repository. diff --git a/include/git2/commit.h b/include/git2/commit.h index a159b79e1..872f691ce 100644 --- a/include/git2/commit.h +++ b/include/git2/commit.h @@ -76,7 +76,10 @@ GIT_INLINE(void) git_commit_free(git_commit *commit) * @param commit a previously loaded commit. * @return object identity for the commit. */ -GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit); +GIT_INLINE(const git_oid *) git_commit_id(const git_commit *commit) +{ + return git_object_id((const git_object *)commit); +} /** * Get the encoding for the message of a commit, @@ -88,7 +91,7 @@ GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit); * @param commit a previously loaded commit. * @return NULL, or the encoding */ -GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit); +GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit); /** * Get the full message of a commit. @@ -96,7 +99,7 @@ GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit); * @param commit a previously loaded commit. * @return the message of a commit */ -GIT_EXTERN(const char *) git_commit_message(git_commit *commit); +GIT_EXTERN(const char *) git_commit_message(const git_commit *commit); /** * Get the commit time (i.e. committer time) of a commit. @@ -104,7 +107,7 @@ GIT_EXTERN(const char *) git_commit_message(git_commit *commit); * @param commit a previously loaded commit. * @return the time of a commit */ -GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit); +GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit); /** * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. @@ -112,7 +115,7 @@ GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit); * @param commit a previously loaded commit. * @return positive or negative timezone offset, in minutes from UTC */ -GIT_EXTERN(int) git_commit_time_offset(git_commit *commit); +GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit); /** * Get the committer of a commit. @@ -120,7 +123,7 @@ GIT_EXTERN(int) git_commit_time_offset(git_commit *commit); * @param commit a previously loaded commit. * @return the committer of a commit */ -GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit); +GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit); /** * Get the author of a commit. @@ -128,7 +131,7 @@ GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit); * @param commit a previously loaded commit. * @return the author of a commit */ -GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit); +GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit); /** * Get the tree pointed to by a commit. @@ -137,7 +140,7 @@ GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit); * @param commit a previously loaded commit. * @return 0 or an error code */ -GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit); +GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit); /** * Get the id of the tree pointed to by a commit. This differs from @@ -147,7 +150,7 @@ GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit); * @param commit a previously loaded commit. * @return the id of tree pointed to by commit. */ -GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit); +GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit); /** * Get the number of parents of this commit @@ -155,17 +158,17 @@ GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit); * @param commit a previously loaded commit. * @return integer of count of parents */ -GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit); +GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit); /** * Get the specified parent of the commit. * - * @param parent Pointer where to store the parent commit + * @param out Pointer where to store the parent commit * @param commit a previously loaded commit. * @param n the position of the parent (from 0 to `parentcount`) * @return 0 or an error code */ -GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n); +GIT_EXTERN(int) git_commit_parent(git_commit **out, git_commit *commit, unsigned int n); /** * Get the oid of a specified parent for a commit. This is different from @@ -176,7 +179,7 @@ GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsig * @param n the position of the parent (from 0 to `parentcount`) * @return the id of the parent, NULL on error. */ -GIT_EXTERN(const git_oid *) git_commit_parent_oid(git_commit *commit, unsigned int n); +GIT_EXTERN(const git_oid *) git_commit_parent_id(git_commit *commit, unsigned int n); /** * Get the commit object that is the <n>th generation ancestor @@ -204,7 +207,7 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor( * The message will not be cleaned up. This can be achieved * through `git_message_prettify()`. * - * @param oid Pointer where to store the OID of the + * @param id Pointer where to store the OID of the * newly created commit * * @param repo Repository where to store the commit @@ -245,7 +248,7 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor( * the given reference will be updated to point to it */ GIT_EXTERN(int) git_commit_create( - git_oid *oid, + git_oid *id, git_repository *repo, const char *update_ref, const git_signature *author, @@ -273,7 +276,7 @@ GIT_EXTERN(int) git_commit_create( * @see git_commit_create */ GIT_EXTERN(int) git_commit_create_v( - git_oid *oid, + git_oid *id, git_repository *repo, const char *update_ref, const git_signature *author, diff --git a/include/git2/config.h b/include/git2/config.h index 8ec78e35c..af4d54044 100644 --- a/include/git2/config.h +++ b/include/git2/config.h @@ -41,23 +41,26 @@ typedef struct { unsigned int level; } git_config_entry; +typedef int (*git_config_foreach_cb)(const git_config_entry *, void *); + + /** * Generic backend that implements the interface to * access a configuration file */ -struct git_config_file { +struct git_config_backend { struct git_config *cfg; /* Open means open the file/database and parse if necessary */ - int (*open)(struct git_config_file *, unsigned int level); - int (*get)(struct git_config_file *, const char *key, const git_config_entry **entry); - int (*get_multivar)(struct git_config_file *, const char *key, const char *regexp, int (*fn)(const git_config_entry *, void *), void *data); - int (*set)(struct git_config_file *, const char *key, const char *value); - int (*set_multivar)(git_config_file *cfg, const char *name, const char *regexp, const char *value); - int (*del)(struct git_config_file *, const char *key); - int (*foreach)(struct git_config_file *, const char *, int (*fn)(const git_config_entry *, void *), void *data); - int (*refresh)(struct git_config_file *); - void (*free)(struct git_config_file *); + int (*open)(struct git_config_backend *, unsigned int level); + int (*get)(const struct git_config_backend *, const char *key, const git_config_entry **entry); + int (*get_multivar)(struct git_config_backend *, const char *key, const char *regexp, git_config_foreach_cb callback, void *payload); + 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 (*foreach)(struct git_config_backend *, const char *, git_config_foreach_cb callback, void *payload); + int (*refresh)(struct git_config_backend *); + void (*free)(struct git_config_backend *); }; typedef enum { @@ -87,11 +90,11 @@ typedef struct { * This method will not guess the path to the xdg compatible * config file (.config/git/config). * - * @param global_config_path Buffer of GIT_PATH_MAX length to store the path - * @return 0 if a global configuration file has been - * found. Its path will be stored in `buffer`. + * @param out Buffer to store the path in + * @param length size of the buffer in bytes + * @return 0 if a global configuration file has been found. Its path will be stored in `buffer`. */ -GIT_EXTERN(int) git_config_find_global(char *global_config_path, size_t length); +GIT_EXTERN(int) git_config_find_global(char *out, size_t length); /** * Locate the path to the global xdg compatible configuration file @@ -104,11 +107,12 @@ GIT_EXTERN(int) git_config_find_global(char *global_config_path, size_t length); * may be used on any `git_config` call to load the * xdg compatible configuration file. * - * @param xdg_config_path Buffer of GIT_PATH_MAX length to store the path + * @param out Buffer to store the path in + * @param length size of the buffer in bytes * @return 0 if a xdg compatible configuration file has been * found. Its path will be stored in `buffer`. */ -GIT_EXTERN(int) git_config_find_xdg(char *xdg_config_path, size_t length); +GIT_EXTERN(int) git_config_find_xdg(char *out, size_t length); /** * Locate the path to the system configuration file @@ -116,11 +120,12 @@ GIT_EXTERN(int) git_config_find_xdg(char *xdg_config_path, size_t length); * If /etc/gitconfig doesn't exist, it will look for * %PROGRAMFILES%\Git\etc\gitconfig. - * @param system_config_path Buffer of GIT_PATH_MAX length to store the path + * @param global_config_path Buffer to store the path in + * @param length size of the buffer in bytes * @return 0 if a system configuration file has been * found. Its path will be stored in `buffer`. */ -GIT_EXTERN(int) git_config_find_system(char *system_config_path, size_t length); +GIT_EXTERN(int) git_config_find_system(char *out, size_t length); /** * Open the global, XDG and system configuration files @@ -163,9 +168,9 @@ GIT_EXTERN(int) git_config_new(git_config **out); * @return 0 on success, GIT_EEXISTS when adding more than one file * for a given priority level (and force_replace set to 0), or error code */ -GIT_EXTERN(int) git_config_add_file( +GIT_EXTERN(int) git_config_add_backend( git_config *cfg, - git_config_file *file, + git_config_backend *file, unsigned int level, int force); @@ -223,12 +228,15 @@ GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path); * will return different config instances, but containing the same config_file * instance. * + * @param out The configuration instance to create + * @param parent Multi-level config to search for the given level + * @param level Configuration level to search for * @return 0, GIT_ENOTFOUND if the passed level cannot be found in the * multi-level parent config, or an error code */ GIT_EXTERN(int) git_config_open_level( - git_config **cfg_out, - git_config *cfg_parent, + git_config **out, + const git_config *parent, unsigned int level); /** @@ -262,7 +270,10 @@ GIT_EXTERN(void) git_config_free(git_config *cfg); * @param name the variable's name * @return 0 or an error code */ -GIT_EXTERN(int) git_config_get_entry(const git_config_entry **out, git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_get_entry( + const git_config_entry **out, + const git_config *cfg, + const char *name); /** * Get the value of an integer config variable. @@ -276,7 +287,7 @@ GIT_EXTERN(int) git_config_get_entry(const git_config_entry **out, git_config *c * @param name the variable's name * @return 0 or an error code */ -GIT_EXTERN(int) git_config_get_int32(int32_t *out, git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name); /** * Get the value of a long integer config variable. @@ -290,7 +301,7 @@ GIT_EXTERN(int) git_config_get_int32(int32_t *out, git_config *cfg, const char * * @param name the variable's name * @return 0 or an error code */ -GIT_EXTERN(int) git_config_get_int64(int64_t *out, git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name); /** * Get the value of a boolean config variable. @@ -307,7 +318,7 @@ GIT_EXTERN(int) git_config_get_int64(int64_t *out, git_config *cfg, const char * * @param name the variable's name * @return 0 or an error code */ -GIT_EXTERN(int) git_config_get_bool(int *out, git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name); /** * Get the value of a string config variable. @@ -324,7 +335,7 @@ GIT_EXTERN(int) git_config_get_bool(int *out, git_config *cfg, const char *name) * @param name the variable's name * @return 0 or an error code */ -GIT_EXTERN(int) git_config_get_string(const char **out, git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name); /** * Get each value of a multivar. @@ -338,7 +349,7 @@ GIT_EXTERN(int) git_config_get_string(const char **out, git_config *cfg, const c * @param fn the function to be called on each value of the variable * @param data opaque pointer to pass to the callback */ -GIT_EXTERN(int) git_config_get_multivar(git_config *cfg, const char *name, const char *regexp, int (*fn)(const git_config_entry *, void *), void *data); +GIT_EXTERN(int) git_config_get_multivar(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload); /** * Set the value of an integer config variable in the config file @@ -404,7 +415,7 @@ GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const * @param cfg the configuration * @param name the variable to delete */ -GIT_EXTERN(int) git_config_delete(git_config *cfg, const char *name); +GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name); /** * Perform an operation on each config variable. @@ -420,8 +431,8 @@ GIT_EXTERN(int) git_config_delete(git_config *cfg, const char *name); * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ GIT_EXTERN(int) git_config_foreach( - git_config *cfg, - int (*callback)(const git_config_entry *, void *payload), + const git_config *cfg, + git_config_foreach_cb callback, void *payload); /** @@ -438,9 +449,9 @@ GIT_EXTERN(int) git_config_foreach( * @return 0 or the return value of the callback which didn't return 0 */ GIT_EXTERN(int) git_config_foreach_match( - git_config *cfg, + const git_config *cfg, const char *regexp, - int (*callback)(const git_config_entry *entry, void *payload), + git_config_foreach_cb callback, void *payload); /** @@ -477,7 +488,12 @@ GIT_EXTERN(int) git_config_foreach_match( * @param map_n number of mapping objects in `maps` * @return 0 on success, error code otherwise */ -GIT_EXTERN(int) git_config_get_mapped(int *out, git_config *cfg, const char *name, git_cvar_map *maps, size_t map_n); +GIT_EXTERN(int) git_config_get_mapped( + int *out, + const git_config *cfg, + const char *name, + const git_cvar_map *maps, + size_t map_n); /** * Maps a string value to an integer constant @@ -489,7 +505,7 @@ GIT_EXTERN(int) git_config_get_mapped(int *out, git_config *cfg, const char *nam */ GIT_EXTERN(int) git_config_lookup_map_value( int *out, - git_cvar_map *maps, + const git_cvar_map *maps, size_t map_n, const char *value); @@ -506,7 +522,7 @@ GIT_EXTERN(int) git_config_lookup_map_value( GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value); /** - * Parse a string value as an int64. + * Parse a string value as an int32. * * An optional value suffix of 'k', 'm', or 'g' will * cause the value to be multiplied by 1024, 1048576, @@ -515,10 +531,10 @@ GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value); * @param out place to store the result of the parsing * @param value value to parse */ -GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); +GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value); /** - * Parse a string value as an int32. + * Parse a string value as an int64. * * An optional value suffix of 'k', 'm', or 'g' will * cause the value to be multiplied by 1024, 1048576, @@ -527,7 +543,7 @@ GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); * @param out place to store the result of the parsing * @param value value to parse */ -GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value); +GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); /** @} */ diff --git a/include/git2/diff.h b/include/git2/diff.h index 47bfa5f69..fd00378af 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -106,6 +106,7 @@ typedef enum { * - max_size: maximum blob size to diff, above this treated as binary */ typedef struct { + unsigned int version; /**< version for the struct */ uint32_t flags; /**< defaults to GIT_DIFF_NORMAL */ uint16_t context_lines; /**< defaults to 3 */ uint16_t interhunk_lines; /**< defaults to 0 */ @@ -186,10 +187,10 @@ typedef struct { /** * When iterating over a diff, callback that will be made per file. */ -typedef int (*git_diff_file_fn)( - void *cb_data, +typedef int (*git_diff_file_cb)( const git_diff_delta *delta, - float progress); + float progress, + void *payload); /** * Structure describing a hunk of a diff. @@ -204,31 +205,31 @@ typedef struct { /** * When iterating over a diff, callback that will be made per hunk. */ -typedef int (*git_diff_hunk_fn)( - void *cb_data, +typedef int (*git_diff_hunk_cb)( const git_diff_delta *delta, const git_diff_range *range, const char *header, - size_t header_len); + size_t header_len, + void *payload); /** * Line origin constants. * * These values describe where a line came from and will be passed to - * the git_diff_data_fn when iterating over a diff. There are some + * the git_diff_data_cb when iterating over a diff. There are some * special origin constants at the end that are used for the text * output callbacks to demarcate lines that are actually part of * the file or hunk headers. */ typedef enum { - /* These values will be sent to `git_diff_data_fn` along with the line */ + /* These values will be sent to `git_diff_data_cb` along with the line */ GIT_DIFF_LINE_CONTEXT = ' ', GIT_DIFF_LINE_ADDITION = '+', GIT_DIFF_LINE_DELETION = '-', GIT_DIFF_LINE_ADD_EOFNL = '\n', /**< Removed line w/o LF & added one with */ GIT_DIFF_LINE_DEL_EOFNL = '\0', /**< LF was removed at end of file */ - /* The following values will only be sent to a `git_diff_data_fn` when + /* The following values will only be sent to a `git_diff_data_cb` when * the content of a diff is being formatted (eg. through * git_diff_print_patch() or git_diff_print_compact(), for instance). */ @@ -245,13 +246,13 @@ typedef enum { * of text. This uses some extra GIT_DIFF_LINE_... constants for output * of lines of file and hunk headers. */ -typedef int (*git_diff_data_fn)( - void *cb_data, +typedef int (*git_diff_data_cb)( const git_diff_delta *delta, const git_diff_range *range, char line_origin, /**< GIT_DIFF_LINE_... value from above */ const char *content, - size_t content_len); + size_t content_len, + void *payload); /** * The diff patch is used to store all the text diffs for a delta. @@ -283,6 +284,8 @@ typedef enum { * Control behavior of rename and copy detection */ typedef struct { + unsigned int version; + /** Combination of git_diff_find_t values (default FIND_RENAMES) */ unsigned int flags; @@ -461,7 +464,6 @@ GIT_EXTERN(int) git_diff_find_similar( * the iteration and cause this return `GIT_EUSER`. * * @param diff A git_diff_list generated by one of the above functions. - * @param cb_data Reference pointer that will be passed to your callbacks. * @param file_cb Callback function to make per file in the diff. * @param hunk_cb Optional callback to make per hunk of text diff. This * callback is called to describe a range of lines in the @@ -469,14 +471,15 @@ GIT_EXTERN(int) git_diff_find_similar( * @param line_cb Optional callback to make per line of diff text. This * same callback will be made for context lines, added, and * removed lines, and even for a deleted trailing newline. + * @param payload Reference pointer that will be passed to your callbacks. * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ GIT_EXTERN(int) git_diff_foreach( git_diff_list *diff, - void *cb_data, - git_diff_file_fn file_cb, - git_diff_hunk_fn hunk_cb, - git_diff_data_fn line_cb); + git_diff_file_cb file_cb, + git_diff_hunk_cb hunk_cb, + git_diff_data_cb line_cb, + void *payload); /** * Iterate over a diff generating text output like "git diff --name-status". @@ -485,14 +488,14 @@ GIT_EXTERN(int) git_diff_foreach( * iteration and cause this return `GIT_EUSER`. * * @param diff A git_diff_list generated by one of the above functions. - * @param cb_data Reference pointer that will be passed to your callback. * @param print_cb Callback to make per line of diff text. + * @param payload Reference pointer that will be passed to your callback. * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ GIT_EXTERN(int) git_diff_print_compact( git_diff_list *diff, - void *cb_data, - git_diff_data_fn print_cb); + git_diff_data_cb print_cb, + void *payload); /** * Look up the single character abbreviation for a delta status code. @@ -517,7 +520,7 @@ GIT_EXTERN(char) git_diff_status_char(git_delta_t status); * iteration and cause this return `GIT_EUSER`. * * @param diff A git_diff_list generated by one of the above functions. - * @param cb_data Reference pointer that will be passed to your callbacks. + * @param payload Reference pointer that will be passed to your callbacks. * @param print_cb Callback function to output lines of the diff. This * same function will be called for file headers, hunk * headers, and diff lines. Fortunately, you can probably @@ -527,8 +530,8 @@ GIT_EXTERN(char) git_diff_status_char(git_delta_t status); */ GIT_EXTERN(int) git_diff_print_patch( git_diff_list *diff, - void *cb_data, - git_diff_data_fn print_cb); + git_diff_data_cb print_cb, + void *payload); /** * Query how many diff records are there in a diff list. @@ -572,15 +575,15 @@ GIT_EXTERN(size_t) git_diff_num_deltas_of_type( * It is okay to pass NULL for either of the output parameters; if you pass * NULL for the `git_diff_patch`, then the text diff will not be calculated. * - * @param patch Output parameter for the delta patch object - * @param delta Output parameter for the delta object + * @param patch_out Output parameter for the delta patch object + * @param delta_out Output parameter for the delta object * @param diff Diff list object * @param idx Index into diff list * @return 0 on success, other value < 0 on error */ GIT_EXTERN(int) git_diff_get_patch( - git_diff_patch **patch, - const git_diff_delta **delta, + git_diff_patch **patch_out, + const git_diff_delta **delta_out, git_diff_list *diff, size_t idx); @@ -672,15 +675,15 @@ GIT_EXTERN(int) git_diff_patch_get_line_in_hunk( * and cause this return `GIT_EUSER`. * * @param patch A git_diff_patch representing changes to one file - * @param cb_data Reference pointer that will be passed to your callbacks. * @param print_cb Callback function to output lines of the patch. Will be * called for file headers, hunk headers, and diff lines. + * @param payload Reference pointer that will be passed to your callbacks. * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ GIT_EXTERN(int) git_diff_patch_print( git_diff_patch *patch, - void *cb_data, - git_diff_data_fn print_cb); + git_diff_data_cb print_cb, + void *payload); /** * Get the content of a patch as a single diff text. @@ -718,10 +721,10 @@ GIT_EXTERN(int) git_diff_blobs( git_blob *old_blob, git_blob *new_blob, const git_diff_options *options, - void *cb_data, - git_diff_file_fn file_cb, - git_diff_hunk_fn hunk_cb, - git_diff_data_fn line_cb); + git_diff_file_cb file_cb, + git_diff_hunk_cb hunk_cb, + git_diff_data_cb line_cb, + void *payload); GIT_END_DECL diff --git a/include/git2/index.h b/include/git2/index.h index 8e1a7e521..fa9a19785 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -21,10 +21,10 @@ */ GIT_BEGIN_DECL -#define GIT_IDXENTRY_NAMEMASK (0x0fff) +#define GIT_IDXENTRY_NAMEMASK (0x0fff) #define GIT_IDXENTRY_STAGEMASK (0x3000) -#define GIT_IDXENTRY_EXTENDED (0x4000) -#define GIT_IDXENTRY_VALID (0x8000) +#define GIT_IDXENTRY_EXTENDED (0x4000) +#define GIT_IDXENTRY_VALID (0x8000) #define GIT_IDXENTRY_STAGESHIFT 12 /* @@ -34,26 +34,26 @@ GIT_BEGIN_DECL * * In-memory only flags: */ -#define GIT_IDXENTRY_UPDATE (1 << 0) -#define GIT_IDXENTRY_REMOVE (1 << 1) -#define GIT_IDXENTRY_UPTODATE (1 << 2) -#define GIT_IDXENTRY_ADDED (1 << 3) +#define GIT_IDXENTRY_UPDATE (1 << 0) +#define GIT_IDXENTRY_REMOVE (1 << 1) +#define GIT_IDXENTRY_UPTODATE (1 << 2) +#define 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) +#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) -#define GIT_IDXENTRY_UNPACKED (1 << 8) +#define GIT_IDXENTRY_UNPACKED (1 << 8) #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) /* * Extended on-disk flags: */ -#define GIT_IDXENTRY_INTENT_TO_ADD (1 << 13) -#define GIT_IDXENTRY_SKIP_WORKTREE (1 << 14) +#define GIT_IDXENTRY_INTENT_TO_ADD (1 << 13) +#define GIT_IDXENTRY_SKIP_WORKTREE (1 << 14) /* GIT_IDXENTRY_EXTENDED2 is for future extension */ -#define GIT_IDXENTRY_EXTENDED2 (1 << 15) +#define GIT_IDXENTRY_EXTENDED2 (1 << 15) #define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE) @@ -119,11 +119,11 @@ enum { * * The index must be freed once it's no longer in use. * - * @param index the pointer for the new index + * @param out the pointer for the new index * @param index_path the path to the index file in disk * @return 0 or an error code */ -GIT_EXTERN(int) git_index_open(git_index **index, const char *index_path); +GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); /** * Create an in-memory index object. @@ -133,10 +133,10 @@ GIT_EXTERN(int) git_index_open(git_index **index, const char *index_path); * * The index must be freed once it's no longer in use. * - * @param index the pointer for the new index + * @param out the pointer for the new index * @return 0 or an error code */ -GIT_EXTERN(int) git_index_new(git_index **index); +GIT_EXTERN(int) git_index_new(git_index **out); /** * Free an existing index object. @@ -201,7 +201,7 @@ GIT_EXTERN(int) git_index_write(git_index *index); * @param tree tree to read * @return 0 or an error code */ -GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree); +GIT_EXTERN(int) git_index_read_tree(git_index *index, const git_tree *tree); /** * Write the index as a tree @@ -217,12 +217,12 @@ GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree); * * The index must not contain any file in conflict. * - * @param oid Pointer where to store the OID of the written tree + * @param out Pointer where to store the OID of the written tree * @param index Index to write * @return 0 on success, GIT_EUNMERGED when the index is not clean * or an error code */ -GIT_EXTERN(int) git_index_write_tree(git_oid *oid, git_index *index); +GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index); /** * Write the index as a tree to the given repository @@ -233,13 +233,13 @@ GIT_EXTERN(int) git_index_write_tree(git_oid *oid, git_index *index); * * The index must not contain any file in conflict. * - * @param oid Pointer where to store OID of the the written tree + * @param out Pointer where to store OID of the the written tree * @param index Index to write * @param repo Repository where to write the tree * @return 0 on success, GIT_EUNMERGED when the index is not clean * or an error code */ -GIT_EXTERN(int) git_index_write_tree_to(git_oid *oid, git_index *index, git_repository *repo); +GIT_EXTERN(int) git_index_write_tree_to(git_oid *out, git_index *index, git_repository *repo); /**@}*/ @@ -258,7 +258,7 @@ GIT_EXTERN(int) git_index_write_tree_to(git_oid *oid, git_index *index, git_repo * @param index an existing index object * @return integer of count of current entries */ -GIT_EXTERN(unsigned int) git_index_entrycount(git_index *index); +GIT_EXTERN(size_t) git_index_entrycount(const git_index *index); /** * Clear the contents (all the entries) of an index object. @@ -282,7 +282,8 @@ GIT_EXTERN(void) git_index_clear(git_index *index); * @param n the position of the entry * @return a pointer to the entry; NULL if out of bounds */ -GIT_EXTERN(git_index_entry *) git_index_get_byindex(git_index *index, size_t n); +GIT_EXTERN(const git_index_entry *) git_index_get_byindex( + git_index *index, size_t n); /** * Get a pointer to one of the entries in the index @@ -298,7 +299,8 @@ GIT_EXTERN(git_index_entry *) git_index_get_byindex(git_index *index, size_t n); * @param stage stage to search * @return a pointer to the entry; NULL if it was not found */ -GIT_EXTERN(git_index_entry *) git_index_get_bypath(git_index *index, const char *path, int stage); +GIT_EXTERN(const git_index_entry *) git_index_get_bypath( + git_index *index, const char *path, int stage); /** * Remove an entry from the index @@ -402,7 +404,8 @@ GIT_EXTERN(int) git_index_find(git_index *index, const char *path); * @param their_entry the entry data for their side of the merge conflict * @return 0 or an error code */ -GIT_EXTERN(int) git_index_conflict_add(git_index *index, +GIT_EXTERN(int) git_index_conflict_add( + git_index *index, const git_index_entry *ancestor_entry, const git_index_entry *our_entry, const git_index_entry *their_entry); @@ -442,7 +445,7 @@ GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index); * * @return 1 if at least one conflict is found, 0 otherwise. */ -GIT_EXTERN(int) git_index_has_conflicts(git_index *index); +GIT_EXTERN(int) git_index_has_conflicts(const git_index *index); /**@}*/ @@ -475,7 +478,7 @@ GIT_EXTERN(int) git_index_reuc_find(git_index *index, const char *path); * Get a resolve undo entry from the index. * * The returned entry is read-only and should not be modified - * of freed by the caller. + * or freed by the caller. * * @param index an existing index object * @param path path to search @@ -487,7 +490,7 @@ GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *in * Get a resolve undo entry from the index. * * The returned entry is read-only and should not be modified - * of freed by the caller. + * or freed by the caller. * * @param index an existing index object * @param n the position of the entry @@ -496,7 +499,7 @@ GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *in GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n); /** - * Adds an resolve undo entry for a file based on the given parameters. + * Adds a resolve undo entry for a file based on the given parameters. * * The resolve undo entry contains the OIDs of files that were involved * in a merge conflict after the conflict has been resolved. This allows @@ -510,26 +513,26 @@ GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *i * @param index an existing index object * @param path filename to add * @param ancestor_mode mode of the ancestor file - * @param ancestor_oid oid of the ancestor file + * @param ancestor_id oid of the ancestor file * @param our_mode mode of our file - * @param our_oid oid of our file + * @param our_id oid of our file * @param their_mode mode of their file - * @param their_oid oid of their file + * @param their_id oid of their file * @return 0 or an error code */ GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path, - int ancestor_mode, git_oid *ancestor_oid, - int our_mode, git_oid *our_oid, - int their_mode, git_oid *their_oid); + int ancestor_mode, git_oid *ancestor_id, + int our_mode, git_oid *our_id, + int their_mode, git_oid *their_id); /** * Remove an resolve undo entry from the index * * @param index an existing index object - * @param position position of the resolve undo entry to remove + * @param n position of the resolve undo entry to remove * @return 0 or an error code */ -GIT_EXTERN(int) git_index_reuc_remove(git_index *index, int position); +GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n); /**@}*/ diff --git a/include/git2/indexer.h b/include/git2/indexer.h index a2a155473..41a1503a4 100644 --- a/include/git2/indexer.h +++ b/include/git2/indexer.h @@ -44,14 +44,14 @@ GIT_EXTERN(int) git_indexer_stream_new( git_indexer_stream **out, const char *path, git_transfer_progress_callback progress_cb, - void *progress_callback_payload); + void *progress_cb_payload); /** * Add data to the indexer * * @param idx the indexer * @param data the data to add - * @param size the size of the data + * @param size the size of the data in bytes * @param stats stat storage */ GIT_EXTERN(int) git_indexer_stream_add(git_indexer_stream *idx, const void *data, size_t size, git_transfer_progress *stats); @@ -73,7 +73,7 @@ GIT_EXTERN(int) git_indexer_stream_finalize(git_indexer_stream *idx, git_transfe * * @param idx the indexer instance */ -GIT_EXTERN(const git_oid *) git_indexer_stream_hash(git_indexer_stream *idx); +GIT_EXTERN(const git_oid *) git_indexer_stream_hash(const git_indexer_stream *idx); /** * Free the indexer and its resources @@ -120,7 +120,7 @@ GIT_EXTERN(int) git_indexer_write(git_indexer *idx); * * @param idx the indexer instance */ -GIT_EXTERN(const git_oid *) git_indexer_hash(git_indexer *idx); +GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx); /** * Free the indexer and its resources diff --git a/include/git2/merge.h b/include/git2/merge.h index 37b1c787d..59493969c 100644 --- a/include/git2/merge.h +++ b/include/git2/merge.h @@ -27,8 +27,13 @@ GIT_BEGIN_DECL * @param repo the repository where the commits exist * @param one one of the commits * @param two the other commit + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. */ -GIT_EXTERN(int) git_merge_base(git_oid *out, git_repository *repo, const git_oid *one, const git_oid *two); +GIT_EXTERN(int) git_merge_base( + git_oid *out, + git_repository *repo, + const git_oid *one, + const git_oid *two); /** * Find a merge base given a list of commits @@ -37,8 +42,13 @@ GIT_EXTERN(int) git_merge_base(git_oid *out, git_repository *repo, const git_oid * @param repo the repository where the commits exist * @param input_array oids of the commits * @param length The number of commits in the provided `input_array` + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. */ -GIT_EXTERN(int) git_merge_base_many(git_oid *out, git_repository *repo, const git_oid input_array[], size_t length); +GIT_EXTERN(int) git_merge_base_many( + git_oid *out, + git_repository *repo, + const git_oid input_array[], + size_t length); /** @} */ GIT_END_DECL diff --git a/include/git2/message.h b/include/git2/message.h index b42cb7677..e89d022a1 100644 --- a/include/git2/message.h +++ b/include/git2/message.h @@ -23,21 +23,27 @@ GIT_BEGIN_DECL * * Optionally, can remove lines starting with a "#". * - * @param message_out The user allocated buffer which will be filled with - * the cleaned up message. Pass NULL if you just want to get the size of the - * prettified message as the output value. + * @param out The user-allocated buffer which will be filled with the + * cleaned up message. Pass NULL if you just want to get the needed + * size of the prettified message as the output value. * - * @param size The size of the allocated buffer message_out. + * @param out_size Size of the `out` buffer in bytes. * * @param message The message to be prettified. * - * @param strip_comments 1 to remove lines starting with a "#", 0 otherwise. + * @param strip_comments Non-zero to remove lines starting with "#", 0 to + * leave them in. * * @return -1 on error, else number of characters in prettified message - * including the trailing NUL byte + * including the trailing NUL byte */ -GIT_EXTERN(int) git_message_prettify(char *message_out, size_t buffer_size, const char *message, int strip_comments); +GIT_EXTERN(int) git_message_prettify( + char *out, + size_t out_size, + const char *message, + int strip_comments); /** @} */ GIT_END_DECL + #endif /* INCLUDE_git_message_h__ */ diff --git a/include/git2/net.h b/include/git2/net.h index c2301b6f1..2543ff8e0 100644 --- a/include/git2/net.h +++ b/include/git2/net.h @@ -4,8 +4,8 @@ * 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_net_h__ -#define INCLUDE_net_h__ +#ifndef INCLUDE_git_net_h__ +#define INCLUDE_git_net_h__ #include "common.h" #include "oid.h" @@ -27,8 +27,10 @@ GIT_BEGIN_DECL * gets called. */ -#define GIT_DIR_FETCH 0 -#define GIT_DIR_PUSH 1 +typedef enum { + GIT_DIRECTION_FETCH = 0, + GIT_DIRECTION_PUSH = 1 +} git_direction; /** @@ -44,7 +46,7 @@ struct git_remote_head { /** * Callback for listing the remote heads */ -typedef int (*git_headlist_cb)(git_remote_head *, void *); +typedef int (*git_headlist_cb)(git_remote_head *rhead, void *payload); /** @} */ GIT_END_DECL diff --git a/include/git2/notes.h b/include/git2/notes.h index af480a408..ae66975cd 100644 --- a/include/git2/notes.h +++ b/include/git2/notes.h @@ -19,20 +19,34 @@ GIT_BEGIN_DECL /** + * Callback for git_note_foreach. + * + * Receives: + * - blob_id: Oid of the blob containing the message + * - annotated_object_id: Oid of the git object being annotated + * - payload: Payload data passed to `git_note_foreach` + */ +typedef int (*git_note_foreach_cb)( + const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); + +/** * Read the note for an object * * The note must be freed manually by the user. * - * @param note pointer to the read note; NULL in case of error + * @param out pointer to the read note; NULL in case of error * @param repo repository where to look up the note - * @param notes_ref canonical name of the reference to use (optional); - * defaults to "refs/notes/commits" + * @param notes_ref canonical name of the reference to use (optional); defaults to + * "refs/notes/commits" * @param oid OID of the git object to read the note from * * @return 0 or an error code */ -GIT_EXTERN(int) git_note_read(git_note **note, git_repository *repo, - const char *notes_ref, const git_oid *oid); +GIT_EXTERN(int) git_note_read( + git_note **out, + git_repository *repo, + const char *notes_ref, + const git_oid *oid); /** * Get the note message @@ -40,7 +54,7 @@ GIT_EXTERN(int) git_note_read(git_note **note, git_repository *repo, * @param note * @return the note message */ -GIT_EXTERN(const char *) git_note_message(git_note *note); +GIT_EXTERN(const char *) git_note_message(const git_note *note); /** @@ -49,7 +63,7 @@ GIT_EXTERN(const char *) git_note_message(git_note *note); * @param note * @return the note object OID */ -GIT_EXTERN(const git_oid *) git_note_oid(git_note *note); +GIT_EXTERN(const git_oid *) git_note_oid(const git_note *note); /** * Add a note for an object @@ -65,10 +79,14 @@ GIT_EXTERN(const git_oid *) git_note_oid(git_note *note); * * @return 0 or an error code */ -GIT_EXTERN(int) git_note_create(git_oid *out, git_repository *repo, - git_signature *author, git_signature *committer, - const char *notes_ref, const git_oid *oid, - const char *note); +GIT_EXTERN(int) git_note_create( + git_oid *out, + git_repository *repo, + const git_signature *author, + const git_signature *committer, + const char *notes_ref, + const git_oid *oid, + const char *note); /** @@ -83,9 +101,12 @@ GIT_EXTERN(int) git_note_create(git_oid *out, git_repository *repo, * * @return 0 or an error code */ -GIT_EXTERN(int) git_note_remove(git_repository *repo, const char *notes_ref, - git_signature *author, git_signature *committer, - const git_oid *oid); +GIT_EXTERN(int) git_note_remove( + git_repository *repo, + const char *notes_ref, + const git_signature *author, + const git_signature *committer, + const git_oid *oid); /** * Free a git_note object @@ -105,17 +126,6 @@ GIT_EXTERN(void) git_note_free(git_note *note); GIT_EXTERN(int) git_note_default_ref(const char **out, git_repository *repo); /** - * Basic components of a note - * - * - Oid of the blob containing the message - * - Oid of the git object being annotated - */ -typedef struct { - git_oid blob_oid; - git_oid annotated_object_oid; -} git_note_data; - -/** * Loop over all the notes within a specified namespace * and issue a callback for each one. * @@ -134,9 +144,8 @@ typedef struct { GIT_EXTERN(int) git_note_foreach( git_repository *repo, const char *notes_ref, - int (*note_cb)(git_note_data *note_data, void *payload), - void *payload -); + git_note_foreach_cb note_cb, + void *payload); /** @} */ GIT_END_DECL diff --git a/include/git2/object.h b/include/git2/object.h index fd6ae95c1..fcc56cb27 100644 --- a/include/git2/object.h +++ b/include/git2/object.h @@ -183,9 +183,9 @@ GIT_EXTERN(size_t) git_object__size(git_otype type); * @return 0 or an error code */ GIT_EXTERN(int) git_object_peel( - git_object **peeled, - git_object *object, - git_otype target_type); + git_object **peeled, + const git_object *object, + git_otype target_type); /** @} */ GIT_END_DECL diff --git a/include/git2/odb.h b/include/git2/odb.h index 4afa3b788..f2633d11c 100644 --- a/include/git2/odb.h +++ b/include/git2/odb.h @@ -136,9 +136,10 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i * @param db database to search for the object in. * @param short_id a prefix of the id of the object to read. * @param len the length of the prefix - * @return 0 if the object was read; - * GIT_ENOTFOUND if the object is not in the database. - * GIT_EAMBIGUOUS if the prefix is ambiguous (several objects match the prefix) + * @return + * - 0 if the object was read; + * - GIT_ENOTFOUND if the object is not in the database. + * - GIT_EAMBIGUOUS if the prefix is ambiguous (several objects match the prefix) */ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len); @@ -152,15 +153,15 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git * of an object, so the whole object will be read and then the * header will be returned. * - * @param len_p pointer where to store the length - * @param type_p pointer where to store the type + * @param len_out pointer where to store the length + * @param type_out pointer where to store the type * @param db database to search for the object in. * @param id identity of the object to read. * @return * - 0 if the object was read; * - GIT_ENOTFOUND if the object is not in the database. */ -GIT_EXTERN(int) git_odb_read_header(size_t *len_p, git_otype *type_p, git_odb *db, const git_oid *id); +GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_otype *type_out, git_odb *db, const git_oid *id); /** * Determine if the given object can be found in the object database. @@ -183,10 +184,10 @@ GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id); * * @param db database to use * @param cb the callback to call for each object - * @param data data to pass to the callback + * @param payload data to pass to the callback * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ -GIT_EXTERN(int) git_odb_foreach(git_odb *db, int (*cb)(git_oid *oid, void *data), void *data); +GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload); /** * Write an object directly into the ODB @@ -199,14 +200,14 @@ GIT_EXTERN(int) git_odb_foreach(git_odb *db, int (*cb)(git_oid *oid, void *data) * This method is provided for compatibility with custom backends * which are not able to support streaming writes * - * @param oid pointer to store the OID result of the write + * @param out pointer to store the OID result of the write * @param odb object database where to store the object * @param data buffer with the data to store * @param len size of the buffer * @param type type of the data to store * @return 0 or an error code */ -GIT_EXTERN(int) git_odb_write(git_oid *oid, git_odb *odb, const void *data, size_t len, git_otype type); +GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size_t len, git_otype type); /** * Open a stream to write an object into the ODB @@ -229,13 +230,13 @@ GIT_EXTERN(int) git_odb_write(git_oid *oid, git_odb *odb, const void *data, size * * @see git_odb_stream * - * @param stream pointer where to store the stream + * @param out pointer where to store the stream * @param db object database where the stream will write * @param size final size of the object that will be written * @param type type of the object that will be written * @return 0 if the stream was created; error code otherwise */ -GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **stream, git_odb *db, size_t size, git_otype type); +GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, size_t size, git_otype type); /** * Open a stream to read an object from the ODB @@ -256,12 +257,12 @@ GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **stream, git_odb *db, size_ * * @see git_odb_stream * - * @param stream pointer where to store the stream + * @param out pointer where to store the stream * @param db object database where the stream will read from * @param oid oid of the object the stream will read from * @return 0 if the stream was created; error code otherwise */ -GIT_EXTERN(int) git_odb_open_rstream(git_odb_stream **stream, git_odb *db, const git_oid *oid); +GIT_EXTERN(int) git_odb_open_rstream(git_odb_stream **out, git_odb *db, const git_oid *oid); /** * Open a stream for writing a pack file to the ODB. @@ -274,14 +275,18 @@ GIT_EXTERN(int) git_odb_open_rstream(git_odb_stream **stream, git_odb *db, const * * @see git_odb_writepack * - * @param writepack pointer to the writepack functions + * @param out pointer to the writepack functions * @param db object database where the stream will read from * @param progress_cb function to call with progress information. * Be aware that this is called inline with network and indexing operations, * so performance may be affected. * @param progress_payload payload for the progress callback */ -GIT_EXTERN(int) git_odb_write_pack(git_odb_writepack **writepack, git_odb *db, git_transfer_progress_callback progress_cb, void *progress_payload); +GIT_EXTERN(int) git_odb_write_pack( + git_odb_writepack **out, + git_odb *db, + git_transfer_progress_callback progress_cb, + void *progress_payload); /** * Determine the object-ID (sha1 hash) of a data buffer @@ -289,13 +294,13 @@ GIT_EXTERN(int) git_odb_write_pack(git_odb_writepack **writepack, git_odb *db, g * The resulting SHA-1 OID will be the identifier for the data * buffer as if the data buffer it were to written to the ODB. * - * @param id the resulting object-ID. + * @param out the resulting object-ID. * @param data data to hash * @param len size of the data * @param type of the data to hash * @return 0 or an error code */ -GIT_EXTERN(int) git_odb_hash(git_oid *id, const void *data, size_t len, git_otype type); +GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_otype type); /** * Read a file from disk and fill a git_oid with the object id diff --git a/include/git2/odb_backend.h b/include/git2/odb_backend.h index 4df48d77e..04658f9b3 100644 --- a/include/git2/odb_backend.h +++ b/include/git2/odb_backend.h @@ -24,7 +24,14 @@ GIT_BEGIN_DECL struct git_odb_stream; struct git_odb_writepack; -/** An instance for a custom backend */ +/** + * Function type for callbacks from git_odb_foreach. + */ +typedef int (*git_odb_foreach_cb)(const git_oid *id, void *payload); + +/** + * An instance for a custom backend + */ struct git_odb_backend { git_odb *odb; @@ -79,8 +86,8 @@ struct git_odb_backend { int (* foreach)( struct git_odb_backend *, - int (*cb)(git_oid *oid, void *data), - void *data); + git_odb_foreach_cb cb, + void *payload); int (* writepack)( struct git_odb_writepack **, @@ -101,7 +108,7 @@ enum { /** A stream to read/write from a backend */ struct git_odb_stream { struct git_odb_backend *backend; - int mode; + unsigned int mode; int (*read)(struct git_odb_stream *stream, char *buffer, size_t len); int (*write)(struct git_odb_stream *stream, const char *buffer, size_t len); @@ -118,12 +125,15 @@ struct git_odb_writepack { void (*free)(struct git_odb_writepack *writepack); }; -GIT_EXTERN(int) git_odb_backend_pack(git_odb_backend **backend_out, const char *objects_dir); -GIT_EXTERN(int) git_odb_backend_loose(git_odb_backend **backend_out, const char *objects_dir, int compression_level, int do_fsync); -GIT_EXTERN(int) git_odb_backend_one_pack(git_odb_backend **backend_out, const char *index_file); - GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); +/** + * Constructors for in-box ODB backends. + */ +GIT_EXTERN(int) git_odb_backend_pack(git_odb_backend **out, const char *objects_dir); +GIT_EXTERN(int) git_odb_backend_loose(git_odb_backend **out, const char *objects_dir, int compression_level, int do_fsync); +GIT_EXTERN(int) git_odb_backend_one_pack(git_odb_backend **out, const char *index_file); + GIT_END_DECL #endif diff --git a/include/git2/oid.h b/include/git2/oid.h index 9e54a9f96..43717ad70 100644 --- a/include/git2/oid.h +++ b/include/git2/oid.h @@ -30,11 +30,10 @@ GIT_BEGIN_DECL #define GIT_OID_MINPREFIXLEN 4 /** Unique identity of any object (commit, tree, blob, tag). */ -typedef struct _git_oid git_oid; -struct _git_oid { +typedef struct git_oid { /** raw binary formatted id */ unsigned char id[GIT_OID_RAWSZ]; -}; +} git_oid; /** * Parse a hex formatted object id into a git_oid. @@ -71,14 +70,14 @@ GIT_EXTERN(void) git_oid_fromraw(git_oid *out, const unsigned char *raw); /** * Format a git_oid into a hex string. * - * @param str output hex string; must be pointing at the start of + * @param out output hex string; must be pointing at the start of * the hex sequence and have at least the number of bytes * needed for an oid encoded in hex (40 bytes). Only the * oid digits are written; a '\\0' terminator must be added * by the caller if it is required. * @param oid oid structure to format. */ -GIT_EXTERN(void) git_oid_fmt(char *str, const git_oid *oid); +GIT_EXTERN(void) git_oid_fmt(char *out, const git_oid *id); /** * Format a git_oid into a loose-object path string. @@ -86,14 +85,14 @@ GIT_EXTERN(void) git_oid_fmt(char *str, const git_oid *oid); * The resulting string is "aa/...", where "aa" is the first two * hex digits of the oid and "..." is the remaining 38 digits. * - * @param str output hex string; must be pointing at the start of + * @param out output hex string; must be pointing at the start of * the hex sequence and have at least the number of bytes * needed for an oid encoded in hex (41 bytes). Only the * oid digits are written; a '\\0' terminator must be added * by the caller if it is required. - * @param oid oid structure to format. + * @param id oid structure to format. */ -GIT_EXTERN(void) git_oid_pathfmt(char *str, const git_oid *oid); +GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id); /** * Format a git_oid into a newly allocated c-string. @@ -102,7 +101,7 @@ GIT_EXTERN(void) git_oid_pathfmt(char *str, const git_oid *oid); * @return the c-string; NULL if memory is exhausted. Caller must * deallocate the string with git__free(). */ -GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *oid); +GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *id); /** * Format a git_oid into a buffer as a hex format c-string. @@ -115,11 +114,11 @@ GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *oid); * * @param out the buffer into which the oid string is output. * @param n the size of the out buffer. - * @param oid the oid structure to format. + * @param id the oid structure to format. * @return the out buffer pointer, assuming no input parameter * errors, otherwise a pointer to an empty string. */ -GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *oid); +GIT_EXTERN(char *) git_oid_tostr(char *out, size_t n, const git_oid *id); /** * Copy an oid from one structure to another. @@ -176,19 +175,19 @@ GIT_EXTERN(int) git_oid_ncmp(const git_oid *a, const git_oid *b, size_t len); /** * Check if an oid equals an hex formatted object id. * - * @param a oid structure. + * @param id oid structure. * @param str input hex string of an object id. * @return GIT_ENOTOID if str is not a valid hex string, * 0 in case of a match, GIT_ERROR otherwise. */ -GIT_EXTERN(int) git_oid_streq(const git_oid *a, const char *str); +GIT_EXTERN(int) git_oid_streq(const git_oid *id, const char *str); /** * Check is an oid is all zeros. * * @return 1 if all zeros, 0 otherwise. */ -GIT_EXTERN(int) git_oid_iszero(const git_oid *a); +GIT_EXTERN(int) git_oid_iszero(const git_oid *id); /** * OID Shortener object @@ -230,12 +229,12 @@ GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length); * GIT_ENOMEM error * * @param os a `git_oid_shorten` instance - * @param text_oid an OID in text form + * @param text_id an OID in text form * @return the minimal length to uniquely identify all OIDs * added so far to the set; or an error code (<0) if an * error occurs. */ -GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_oid); +GIT_EXTERN(int) git_oid_shorten_add(git_oid_shorten *os, const char *text_id); /** * Free an OID shortener instance diff --git a/include/git2/pack.h b/include/git2/pack.h index 94d5fc6a1..585cffef6 100644 --- a/include/git2/pack.h +++ b/include/git2/pack.h @@ -38,8 +38,9 @@ GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo) * * @param pb The packbuilder * @param n Number of threads to spawn + * @return number of actual threads to be used */ -GIT_EXTERN(void) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n); +GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n); /** * Insert a single object @@ -48,12 +49,12 @@ GIT_EXTERN(void) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n * commits followed by trees and blobs. * * @param pb The packbuilder - * @param oid The oid of the commit - * @param oid The name; might be NULL + * @param id The oid of the commit + * @param name The name; might be NULL * * @return 0 or an error code */ -GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *oid, const char *name); +GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name); /** * Insert a root tree object @@ -61,11 +62,11 @@ GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *oid, * This will add the tree as well as all referenced trees and blobs. * * @param pb The packbuilder - * @param oid The oid of the root tree + * @param id The oid of the root tree * * @return 0 or an error code */ -GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *oid); +GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id); /** * Write the new pack and the corresponding index to path @@ -82,15 +83,17 @@ GIT_EXTERN(int) git_packbuilder_write(git_packbuilder *pb, const char *file); * * @param pb the packbuilder * @param cb the callback to call with each packed object's buffer - * @param data the callback's data + * @param payload the callback's data * @return 0 or an error code */ -GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, int (*cb)(void *buf, size_t size, void *data), void *data); +typedef int (*git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload); +GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload); /** * Get the total number of objects the packbuilder will write out * * @param pb the packbuilder + * @return */ GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb); @@ -98,6 +101,7 @@ GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb); * Get the number of objects the packbuilder has already written out * * @param pb the packbuilder + * @return */ GIT_EXTERN(uint32_t) git_packbuilder_written(git_packbuilder *pb); diff --git a/include/git2/reflog.h b/include/git2/reflog.h index 72e1f1753..45dff2165 100644 --- a/include/git2/reflog.h +++ b/include/git2/reflog.h @@ -30,11 +30,11 @@ GIT_BEGIN_DECL * The reflog must be freed manually by using * git_reflog_free(). * - * @param reflog pointer to reflog + * @param out pointer to reflog * @param ref reference to read the reflog for * @return 0 or an error code */ -GIT_EXTERN(int) git_reflog_read(git_reflog **reflog, git_reference *ref); +GIT_EXTERN(int) git_reflog_read(git_reflog **out, const git_reference *ref); /** * Write an existing in-memory reflog object back to disk @@ -51,12 +51,12 @@ GIT_EXTERN(int) git_reflog_write(git_reflog *reflog); * `msg` is optional and can be NULL. * * @param reflog an existing reflog object - * @param new_oid the OID the reference is now pointing to + * @param id the OID the reference is now pointing to * @param committer the signature of the committer * @param msg the reflog message * @return 0 or an error code */ -GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *new_oid, const git_signature *committer, const char *msg); +GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg); /** * Rename the reflog for the given reference @@ -64,10 +64,10 @@ GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *new_oid, co * The reflog to be renamed is expected to already exist * * @param ref the reference - * @param new_name the new name of the reference + * @param name the new name of the reference * @return 0 or an error code */ -GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *new_name); +GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *name); /** * Delete the reflog for the given reference @@ -83,7 +83,7 @@ GIT_EXTERN(int) git_reflog_delete(git_reference *ref); * @param reflog the previously loaded reflog * @return the number of log entries */ -GIT_EXTERN(unsigned int) git_reflog_entrycount(git_reflog *reflog); +GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog); /** * Lookup an entry by its index @@ -126,7 +126,7 @@ GIT_EXTERN(int) git_reflog_drop( * @param entry a reflog entry * @return the old oid */ -GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entry); +GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry); /** * Get the new oid @@ -134,7 +134,7 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entr * @param entry a reflog entry * @return the new oid at this time */ -GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entry); +GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry); /** * Get the committer of this entry @@ -142,15 +142,15 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entr * @param entry a reflog entry * @return the committer */ -GIT_EXTERN(git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); +GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry); /** - * Get the log msg + * Get the log message * * @param entry a reflog entry * @return the log msg */ -GIT_EXTERN(char *) git_reflog_entry_msg(const git_reflog_entry *entry); +GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry); /** * Free the reflog diff --git a/include/git2/refs.h b/include/git2/refs.h index bc3f44482..c92646115 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -29,12 +29,12 @@ GIT_BEGIN_DECL * See `git_reference_create_symbolic()` for documentation about valid * reference names. * - * @param reference_out pointer to the looked-up reference + * @param out pointer to the looked-up reference * @param repo the repository to look up the reference * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) - * @return 0 or an error code + * @return 0 or an error code (ENOTFOUND, EINVALIDSPEC) */ -GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name); +GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name); /** * Lookup a reference by name and resolve immediately to OID. @@ -43,12 +43,13 @@ GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_reposito * through to the object id that it refers to. This avoids having to * allocate or free any `git_reference` objects for simple situations. * - * @param oid Pointer to oid to be filled in + * @param out Pointer to oid to be filled in * @param repo The repository in which to look up the reference * @param name The long name for the reference - * @return 0 on success, -1 if name could not be resolved + * @return 0 on success, -1 if name could not be resolved (EINVALIDSPEC, + * ENOTFOUND, etc) */ -GIT_EXTERN(int) git_reference_name_to_oid( +GIT_EXTERN(int) git_reference_name_to_id( git_oid *out, git_repository *repo, const char *name); /** @@ -73,14 +74,14 @@ GIT_EXTERN(int) git_reference_name_to_oid( * This function will return an error if a reference already exists with the * given name unless `force` is true, in which case it will be overwritten. * - * @param ref_out Pointer to the newly created reference + * @param out Pointer to the newly created reference * @param repo Repository where that reference will live * @param name The name of the reference * @param target The target of the reference * @param force Overwrite existing references - * @return 0 or an error code + * @return 0 or an error code (EEXISTS, EINVALIDSPEC) */ -GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force); +GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force); /** * Create a new direct reference. @@ -105,14 +106,14 @@ GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repos * This function will return an error if a reference already exists with the * given name unless `force` is true, in which case it will be overwritten. * - * @param ref_out Pointer to the newly created reference + * @param out Pointer to the newly created reference * @param repo Repository where that reference will live * @param name The name of the reference * @param id The object id pointed to by the reference. * @param force Overwrite existing references - * @return 0 or an error code + * @return 0 or an error code (EINVALIDSPEC, EEXISTS) */ -GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force); +GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force); /** * Get the OID pointed to by a direct reference. @@ -127,7 +128,7 @@ GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository * @param ref The reference * @return a pointer to the oid if available, NULL otherwise */ -GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref); +GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref); /** * Get full name to the reference pointed to by a symbolic reference. @@ -137,7 +138,7 @@ GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref); * @param ref The reference * @return a pointer to the name if available, NULL otherwise */ -GIT_EXTERN(const char *) git_reference_target(git_reference *ref); +GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref); /** * Get the type of a reference. @@ -147,7 +148,7 @@ GIT_EXTERN(const char *) git_reference_target(git_reference *ref); * @param ref The reference * @return the type */ -GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref); +GIT_EXTERN(git_ref_t) git_reference_type(const git_reference *ref); /** * Get the full name of a reference. @@ -157,7 +158,7 @@ GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref); * @param ref The reference * @return the full name for the ref */ -GIT_EXTERN(const char *) git_reference_name(git_reference *ref); +GIT_EXTERN(const char *) git_reference_name(const git_reference *ref); /** * Resolve a symbolic reference to a direct reference. @@ -175,7 +176,7 @@ GIT_EXTERN(const char *) git_reference_name(git_reference *ref); * @param ref The reference * @return 0 or an error code */ -GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref); +GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref); /** * Get the repository where a reference resides. @@ -183,7 +184,7 @@ GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_referenc * @param ref The reference * @return a pointer to the repo */ -GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref); +GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); /** * Set the symbolic target of a reference. @@ -194,9 +195,9 @@ GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref); * * @param ref The reference * @param target The new target for the reference - * @return 0 or an error code + * @return 0 or an error code (EINVALIDSPEC) */ -GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target); +GIT_EXTERN(int) git_reference_symbolic_set_target(git_reference *ref, const char *target); /** * Set the OID target of a reference. @@ -209,7 +210,7 @@ GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target) * @param id The new target OID for the reference * @return 0 or an error code */ -GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); +GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const git_oid *id); /** * Rename an existing reference. @@ -231,12 +232,12 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); * the reflog if it exists. * * @param ref The reference to rename - * @param new_name The new name for the reference + * @param name The new name for the reference * @param force Overwrite an existing reference - * @return 0 or an error code + * @return 0 or an error code (EINVALIDSPEC, EEXISTS) * */ -GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force); +GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *name, int force); /** * Delete an existing reference. @@ -287,6 +288,8 @@ GIT_EXTERN(int) git_reference_packall(git_repository *repo); */ GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, unsigned int list_flags); +typedef int (*git_reference_foreach_cb)(const char *refname, void *payload); + /** * Perform a callback on each reference in the repository. * @@ -307,7 +310,11 @@ GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, un * @param payload Additional data to pass to the callback * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ -GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload); +GIT_EXTERN(int) git_reference_foreach( + git_repository *repo, + unsigned int list_flags, + git_reference_foreach_cb callback, + void *payload); /** * Check if a reference has been loaded from a packfile. diff --git a/include/git2/remote.h b/include/git2/remote.h index 44390e7a4..6c70d7fbc 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -24,6 +24,7 @@ */ GIT_BEGIN_DECL +typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, void *payload); /* * TODO: This functions still need to be implemented: * - _listcb/_foreach @@ -71,7 +72,7 @@ GIT_EXTERN(int) git_remote_save(const git_remote *remote); * @param remote the remote * @return a pointer to the name */ -GIT_EXTERN(const char *) git_remote_name(git_remote *remote); +GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); /** * Get the remote's url @@ -79,7 +80,7 @@ GIT_EXTERN(const char *) git_remote_name(git_remote *remote); * @param remote the remote * @return a pointer to the url */ -GIT_EXTERN(const char *) git_remote_url(git_remote *remote); +GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); /** * Get the remote's url for pushing @@ -87,7 +88,7 @@ GIT_EXTERN(const char *) git_remote_url(git_remote *remote); * @param remote the remote * @return a pointer to the url or NULL if no special url for pushing is set */ -GIT_EXTERN(const char *) git_remote_pushurl(git_remote *remote); +GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); /** * Set the remote's url @@ -126,7 +127,7 @@ GIT_EXTERN(int) git_remote_set_fetchspec(git_remote *remote, const char *spec); * @param remote the remote * @return a pointer to the fetch refspec or NULL if it doesn't exist */ -GIT_EXTERN(const git_refspec *) git_remote_fetchspec(git_remote *remote); +GIT_EXTERN(const git_refspec *) git_remote_fetchspec(const git_remote *remote); /** * Set the remote's push refspec @@ -144,7 +145,7 @@ GIT_EXTERN(int) git_remote_set_pushspec(git_remote *remote, const char *spec); * @return a pointer to the push refspec or NULL if it doesn't exist */ -GIT_EXTERN(const git_refspec *) git_remote_pushspec(git_remote *remote); +GIT_EXTERN(const git_refspec *) git_remote_pushspec(const git_remote *remote); /** * Open a connection to a remote @@ -157,7 +158,7 @@ GIT_EXTERN(const git_refspec *) git_remote_pushspec(git_remote *remote); * @param direction whether you want to receive or send data * @return 0 or an error code */ -GIT_EXTERN(int) git_remote_connect(git_remote *remote, int direction); +GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction); /** * Get a list of refs at the remote @@ -194,7 +195,7 @@ GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void GIT_EXTERN(int) git_remote_download( git_remote *remote, git_transfer_progress_callback progress_cb, - void *progress_payload); + void *payload); /** * Check whether the remote is connected @@ -266,11 +267,11 @@ GIT_EXTERN(int) git_remote_supported_url(const char* url); * * The string array must be freed by the user. * - * @param remotes_list a string array with the names of the remotes + * @param out a string array which receives the names of the remotes * @param repo the repository to query * @return 0 or an error code */ -GIT_EXTERN(int) git_remote_list(git_strarray *remotes_list, git_repository *repo); +GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); /** * Add a remote with the default fetch refspec to the repository's configuration @@ -340,7 +341,7 @@ struct git_remote_callbacks { void (*progress)(const char *str, int len, void *data); int (*completion)(git_remote_completion_type type, void *data); int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); - void *data; + void *payload; }; /** @@ -359,12 +360,12 @@ GIT_EXTERN(void) git_remote_set_callbacks(git_remote *remote, git_remote_callbac */ GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote); -enum { +typedef enum { GIT_REMOTE_DOWNLOAD_TAGS_UNSET, GIT_REMOTE_DOWNLOAD_TAGS_NONE, GIT_REMOTE_DOWNLOAD_TAGS_AUTO, GIT_REMOTE_DOWNLOAD_TAGS_ALL -}; +} git_remote_autotag_option_t; /** * Retrieve the tag auto-follow setting @@ -372,7 +373,7 @@ enum { * @param remote the remote to query * @return the auto-follow setting */ -GIT_EXTERN(int) git_remote_autotag(git_remote *remote); +GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(git_remote *remote); /** * Set the tag auto-follow setting @@ -380,7 +381,9 @@ GIT_EXTERN(int) git_remote_autotag(git_remote *remote); * @param remote the remote to configure * @param value a GIT_REMOTE_DOWNLOAD_TAGS value */ -GIT_EXTERN(void) git_remote_set_autotag(git_remote *remote, int value); +GIT_EXTERN(void) git_remote_set_autotag( + git_remote *remote, + git_remote_autotag_option_t value); /** * Give the remote a new name @@ -398,7 +401,7 @@ GIT_EXTERN(void) git_remote_set_autotag(git_remote *remote, int value); GIT_EXTERN(int) git_remote_rename( git_remote *remote, const char *new_name, - int (*callback)(const char *problematic_refspec, void *payload), + git_remote_rename_problem_cb callback, void *payload); /** diff --git a/include/git2/repository.h b/include/git2/repository.h index f891e91e9..e91108a33 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -29,11 +29,11 @@ GIT_BEGIN_DECL * The method will automatically detect if 'path' is a normal * or bare repository or fail is 'path' is neither. * - * @param repository pointer to the repo which will be opened + * @param out pointer to the repo which will be opened * @param path the path to the repository * @return 0 or an error code */ -GIT_EXTERN(int) git_repository_open(git_repository **repository, const char *path); +GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); /** * Create a "fake" repository to wrap an object database @@ -42,11 +42,11 @@ GIT_EXTERN(int) git_repository_open(git_repository **repository, const char *pat * with the API when all you have is an object database. This doesn't * have any paths associated with it, so use with care. * - * @param repository pointer to the repo + * @param out pointer to the repo * @param odb the object database to wrap * @return 0 or an error code */ -GIT_EXTERN(int) git_repository_wrap_odb(git_repository **repository, git_odb *odb); +GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb); /** * Look for a git repository and copy its path in the given buffer. @@ -58,10 +58,10 @@ GIT_EXTERN(int) git_repository_wrap_odb(git_repository **repository, git_odb *od * The method will automatically detect if the repository is bare * (if there is a repository). * - * @param repository_path The user allocated buffer which will + * @param path_out The user allocated buffer which will * contain the found path. * - * @param size repository_path size + * @param path_size repository_path size * * @param start_path The base path where the lookup starts. * @@ -77,8 +77,8 @@ GIT_EXTERN(int) git_repository_wrap_odb(git_repository **repository, git_odb *od * @return 0 or an error code */ GIT_EXTERN(int) git_repository_discover( - char *repository_path, - size_t size, + char *path_out, + size_t path_size, const char *start_path, int across_fs, const char *ceiling_dirs); @@ -95,18 +95,18 @@ GIT_EXTERN(int) git_repository_discover( * directory "/home/user/source/" will not return "/.git/" as the found * repo if "/" is a different filesystem than "/home".) */ -enum { +typedef enum { GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), -}; +} git_repository_open_flag_t; /** * Find and open a repository with extended controls. * - * @param repo_out Pointer to the repo which will be opened. This can + * @param out Pointer to the repo which will be opened. This can * actually be NULL if you only want to use the error code to * see if a repo at this path could be opened. - * @param start_path Path to open as git repository. If the flags + * @param path Path to open as git repository. If the flags * permit "searching", then this can be a path to a subdirectory * inside the working directory of the repository. * @param flags A combination of the GIT_REPOSITORY_OPEN flags above. @@ -118,9 +118,9 @@ enum { * (such as repo corruption or system errors). */ GIT_EXTERN(int) git_repository_open_ext( - git_repository **repo, - const char *start_path, - uint32_t flags, + git_repository **out, + const char *path, + unsigned int flags, const char *ceiling_dirs); /** @@ -142,7 +142,7 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo); * TODO: * - Reinit the repository * - * @param repo_out pointer to the repo which will be created or reinitialized + * @param out pointer to the repo which will be created or reinitialized * @param path the path to the repository * @param is_bare if true, a Git repository without a working directory is * created at the pointed path. If false, provided path will be @@ -152,7 +152,7 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo); * @return 0 or an error code */ GIT_EXTERN(int) git_repository_init( - git_repository **repo_out, + git_repository **out, const char *path, unsigned is_bare); @@ -182,14 +182,14 @@ GIT_EXTERN(int) git_repository_init( * `init.templatedir` global config if not, or falling back on * "/usr/share/git-core/templates" if it exists. */ -enum { +typedef enum { GIT_REPOSITORY_INIT_BARE = (1u << 0), GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), GIT_REPOSITORY_INIT_MKDIR = (1u << 3), GIT_REPOSITORY_INIT_MKPATH = (1u << 4), GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), -}; +} git_repository_init_flag_t; /** * Mode options for `git_repository_init_ext`. @@ -204,11 +204,11 @@ enum { * * SHARED_ALL - Use "--shared=all" behavior, adding world readability. * * Anything else - Set to custom value. */ -enum { +typedef enum { GIT_REPOSITORY_INIT_SHARED_UMASK = 0, GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, GIT_REPOSITORY_INIT_SHARED_ALL = 0002777, -}; +} git_repository_init_mode_t; /** * Extended options structure for `git_repository_init_ext`. @@ -256,26 +256,30 @@ typedef struct { * auto-detect the case sensitivity of the file system and if the * file system supports file mode bits correctly. * - * @param repo_out Pointer to the repo which will be created or reinitialized. + * @param out Pointer to the repo which will be created or reinitialized. * @param repo_path The path to the repository. * @param opts Pointer to git_repository_init_options struct. * @return 0 or an error code on failure. */ GIT_EXTERN(int) git_repository_init_ext( - git_repository **repo_out, + git_repository **out, const char *repo_path, git_repository_init_options *opts); /** * Retrieve and resolve the reference pointed at by HEAD. * - * @param head_out pointer to the reference which will be retrieved + * The returned `git_reference` will be owned by caller and + * `git_reference_free()` must be called when done with it to release the + * allocated memory and prevent a leak. + * + * @param out pointer to the reference which will be retrieved * @param repo a repository object * * @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing * branch, GIT_ENOTFOUND when HEAD is missing; an error code otherwise */ -GIT_EXTERN(int) git_repository_head(git_reference **head_out, git_repository *repo); +GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo); /** * Check if a repository's HEAD is detached @@ -468,12 +472,12 @@ GIT_EXTERN(void) git_repository_set_index(git_repository *repo, git_index *index * Use this function to get the contents of this file. Don't forget to * remove the file after you create the commit. * - * @param buffer Buffer to write data into or NULL to just read required size + * @param out Buffer to write data into or NULL to just read required size * @param len Length of buffer in bytes * @param repo Repository to read prepared message from * @return Bytes written to buffer, GIT_ENOTFOUND if no message, or -1 on error */ -GIT_EXTERN(int) git_repository_message(char *buffer, size_t len, git_repository *repo); +GIT_EXTERN(int) git_repository_message(char *out, size_t len, git_repository *repo); /** * Remove git's prepared message. diff --git a/include/git2/reset.h b/include/git2/reset.h index cdcfb7671..b5fc4a6cb 100644 --- a/include/git2/reset.h +++ b/include/git2/reset.h @@ -16,16 +16,26 @@ 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_t; + +/** * Sets the current head to the specified commit oid and optionally * resets the index and working tree to match. * - * When specifying a Soft kind of reset, the head will be moved to the commit. + * SOFT reset means the head will be moved to the commit. * - * Specifying a Mixed kind of reset will trigger a Soft reset and the index will - * be replaced with the content of the commit tree. + * MIXED reset will trigger a SOFT reset, plus the index will be replaced + * with the content of the commit tree. * - * Specifying a Hard kind of reset will trigger a Mixed reset and the working - * directory will be replaced with the content of the index. + * HARD reset will trigger a MIXED reset and the working directory will be + * replaced with the content of the index. (Untracked and ignored files + * will be left alone, however.) * * TODO: Implement remaining kinds of resets. * @@ -38,9 +48,10 @@ GIT_BEGIN_DECL * * @param reset_type Kind of reset operation to perform. * - * @return GIT_SUCCESS or an error code + * @return 0 on success or an error code < 0 */ -GIT_EXTERN(int) git_reset(git_repository *repo, git_object *target, git_reset_type reset_type); +GIT_EXTERN(int) git_reset( + git_repository *repo, git_object *target, git_reset_t reset_type); /** @} */ GIT_END_DECL diff --git a/include/git2/revwalk.h b/include/git2/revwalk.h index 0a85a4c60..893ad2c9d 100644 --- a/include/git2/revwalk.h +++ b/include/git2/revwalk.h @@ -63,11 +63,11 @@ GIT_BEGIN_DECL * it is possible to have several revision walkers in * several different threads walking the same repository. * - * @param walker pointer to the new revision walker + * @param out pointer to the new revision walker * @param repo the repo to walk through * @return 0 or an error code */ -GIT_EXTERN(int) git_revwalk_new(git_revwalk **walker, git_repository *repo); +GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); /** * Reset the revision walker for reuse. @@ -96,10 +96,10 @@ GIT_EXTERN(void) git_revwalk_reset(git_revwalk *walker); * be started. * * @param walk the walker being used for the traversal. - * @param oid the oid of the commit to start from. + * @param id the oid of the commit to start from. * @return 0 or an error code */ -GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *oid); +GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); /** * Push matching references @@ -134,10 +134,10 @@ GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); * output on the revision walk. * * @param walk the walker being used for the traversal. - * @param oid the oid of commit that will be ignored during the traversal + * @param commit_id the oid of commit that will be ignored during the traversal * @return 0 or an error code */ -GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *oid); +GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); /** * Hide matching references. @@ -198,12 +198,12 @@ GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); * * The revision walker is reset when the walk is over. * - * @param oid Pointer where to store the oid of the next commit + * @param out Pointer where to store the oid of the next commit * @param walk the walker to pop the commit from. * @return 0 if the next commit was found; * GIT_ITEROVER if there are no commits left to iterate */ -GIT_EXTERN(int) git_revwalk_next(git_oid *oid, git_revwalk *walk); +GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); /** * Change the sorting mode when iterating through the diff --git a/include/git2/signature.h b/include/git2/signature.h index cdbe67879..7a265bd8e 100644 --- a/include/git2/signature.h +++ b/include/git2/signature.h @@ -20,44 +20,52 @@ GIT_BEGIN_DECL /** - * Create a new action signature. The signature must be freed - * manually or using git_signature_free + * Create a new action signature. + * + * Call `git_signature_free()` to free the data. * * Note: angle brackets ('<' and '>') characters are not allowed * to be used in either the `name` or the `email` parameter. * - * @param sig_out new signature, in case of error NULL + * @param out new signature, in case of error NULL * @param name name of the person * @param email email of the person * @param time time when the action happened * @param offset timezone offset in minutes for the time * @return 0 or an error code */ -GIT_EXTERN(int) git_signature_new(git_signature **sig_out, const char *name, const char *email, git_time_t time, int offset); +GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset); /** - * Create a new action signature with a timestamp of 'now'. The - * signature must be freed manually or using git_signature_free + * Create a new action signature with a timestamp of 'now'. + * + * Call `git_signature_free()` to free the data. * - * @param sig_out new signature, in case of error NULL + * @param out new signature, in case of error NULL * @param name name of the person * @param email email of the person * @return 0 or an error code */ -GIT_EXTERN(int) git_signature_now(git_signature **sig_out, const char *name, const char *email); +GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email); /** - * Create a copy of an existing signature. + * Create a copy of an existing signature. All internal strings are also + * duplicated. + * + * Call `git_signature_free()` to free the data. * - * All internal strings are also duplicated. * @param sig signature to duplicated * @return a copy of sig, NULL on out of memory */ GIT_EXTERN(git_signature *) git_signature_dup(const git_signature *sig); /** - * Free an existing signature + * Free an existing signature. + * + * Because the signature is not an opaque structure, it is legal to free it + * manually, but be sure to free the "name" and "email" strings in addition + * to the structure itself. * * @param sig signature to free */ diff --git a/include/git2/stash.h b/include/git2/stash.h index 3ecd9e88d..b57d47b3a 100644 --- a/include/git2/stash.h +++ b/include/git2/stash.h @@ -18,7 +18,7 @@ */ GIT_BEGIN_DECL -enum { +typedef enum { GIT_STASH_DEFAULT = 0, /* All changes already added to the index @@ -35,7 +35,7 @@ enum { * cleaned up from the working directory */ GIT_STASH_INCLUDE_IGNORED = (1 << 2), -}; +} git_stash_flags; /** * Save the local modifications to a new stash. @@ -49,18 +49,17 @@ enum { * * @param message Optional description along with the stashed state. * - * @param flags Flags to control the stashing process. + * @param flags Flags to control the stashing process. (see GIT_STASH_* above) * * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash, * or error code. */ - GIT_EXTERN(int) git_stash_save( git_oid *out, git_repository *repo, git_signature *stasher, const char *message, - uint32_t flags); + unsigned int flags); /** * When iterating over all the stashed states, callback that will be @@ -71,16 +70,16 @@ GIT_EXTERN(int) git_stash_save( * * @param message The stash message. * - * @param stash_oid The commit oid of the stashed state. + * @param stash_id The commit oid of the stashed state. * * @param payload Extra parameter to callback function. * * @return 0 on success, GIT_EUSER on non-zero callback, or error code */ -typedef int (*stash_cb)( +typedef int (*git_stash_cb)( size_t index, const char* message, - const git_oid *stash_oid, + const git_oid *stash_id, void *payload); /** @@ -99,7 +98,7 @@ typedef int (*stash_cb)( */ GIT_EXTERN(int) git_stash_foreach( git_repository *repo, - stash_cb callback, + git_stash_cb callback, void *payload); /** diff --git a/include/git2/status.h b/include/git2/status.h index 8c59d768d..c6926f343 100644 --- a/include/git2/status.h +++ b/include/git2/status.h @@ -47,6 +47,18 @@ typedef enum { } git_status_t; /** + * Function pointer to receive status on individual files + * + * `path` is the relative path to the file from the root of the repository. + * + * `status_flags` is a combination of `git_status_t` values that apply. + * + * `payload` is the value you passed to the foreach function as payload. + */ +typedef int (*git_status_cb)( + const char *path, unsigned int status_flags, void *payload); + +/** * Gather file statuses and run a callback for each one. * * The callback is passed the path of the file, the status (a combination of @@ -63,7 +75,7 @@ typedef enum { */ GIT_EXTERN(int) git_status_foreach( git_repository *repo, - int (*callback)(const char *, unsigned int, void *), + git_status_cb callback, void *payload); /** @@ -146,9 +158,10 @@ typedef enum { * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags. */ typedef struct { + unsigned int version; git_status_show_t show; - unsigned int flags; - git_strarray pathspec; + unsigned int flags; + git_strarray pathspec; } git_status_options; /** @@ -168,7 +181,7 @@ typedef struct { GIT_EXTERN(int) git_status_foreach_ext( git_repository *repo, const git_status_options *opts, - int (*callback)(const char *, unsigned int, void *), + git_status_cb callback, void *payload); /** diff --git a/include/git2/strarray.h b/include/git2/strarray.h index f6092fa9c..030567978 100644 --- a/include/git2/strarray.h +++ b/include/git2/strarray.h @@ -28,21 +28,28 @@ struct _git_strarray { /** * Close a string array object * - * This method must always be called once a git_strarray is no - * longer needed, otherwise memory will leak. + * This method should be called on `git_strarray` objects where the strings + * array is allocated and contains allocated strings, such as what you + * would get from `git_strarray_copy()`. Not doing so, will result in a + * memory leak. * - * @param array array to close + * This does not free the `git_strarray` 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_strarray from which to free string data */ GIT_EXTERN(void) git_strarray_free(git_strarray *array); /** * Copy a string array object from source to target. - * - * Note: target is overwritten and hence should be empty, + * + * Note: target is overwritten and hence should be empty, * otherwise its contents are leaked. * * @param tgt target * @param src source + * @return 0 on success, < 0 on allocation failure */ GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src); @@ -51,4 +58,4 @@ GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src); GIT_END_DECL #endif - + diff --git a/include/git2/submodule.h b/include/git2/submodule.h index b00fad2d4..90e45cebd 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -318,7 +318,7 @@ GIT_EXTERN(int) git_submodule_set_url(git_submodule *submodule, const char *url) * @param submodule Pointer to submodule object * @return Pointer to git_oid or NULL if submodule is not in index. */ -GIT_EXTERN(const git_oid *) git_submodule_index_oid(git_submodule *submodule); +GIT_EXTERN(const git_oid *) git_submodule_index_id(git_submodule *submodule); /** * Get the OID for the submodule in the current HEAD tree. @@ -326,7 +326,7 @@ GIT_EXTERN(const git_oid *) git_submodule_index_oid(git_submodule *submodule); * @param submodule Pointer to submodule object * @return Pointer to git_oid or NULL if submodule is not in the HEAD. */ -GIT_EXTERN(const git_oid *) git_submodule_head_oid(git_submodule *submodule); +GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); /** * Get the OID for the submodule in the current working directory. @@ -339,7 +339,7 @@ GIT_EXTERN(const git_oid *) git_submodule_head_oid(git_submodule *submodule); * @param submodule Pointer to submodule object * @return Pointer to git_oid or NULL if submodule is not checked out. */ -GIT_EXTERN(const git_oid *) git_submodule_wd_oid(git_submodule *submodule); +GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); /** * Get the ignore rule for the submodule. diff --git a/include/git2/tag.h b/include/git2/tag.h index a1b685f12..f82a6c9f9 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -25,14 +25,16 @@ GIT_BEGIN_DECL /** * Lookup a tag object from the repository. * - * @param tag pointer to the looked up tag + * @param out pointer to the looked up tag * @param repo the repo to use when locating the tag. * @param id identity of the tag to locate. * @return 0 or an error code */ -GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oid *id) +GIT_INLINE(int) git_tag_lookup( + git_tag **out, git_repository *repo, const git_oid *id) { - return git_object_lookup((git_object **)tag, repo, id, (git_otype)GIT_OBJ_TAG); + return git_object_lookup( + (git_object **)out, repo, id, (git_otype)GIT_OBJ_TAG); } /** @@ -41,32 +43,33 @@ GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oi * * @see git_object_lookup_prefix * - * @param tag pointer to the looked up tag + * @param out pointer to the looked up tag * @param repo the repo to use when locating the tag. * @param id identity of the tag to locate. * @param len the length of the short identifier * @return 0 or an error code */ -GIT_INLINE(int) git_tag_lookup_prefix(git_tag **tag, git_repository *repo, const git_oid *id, size_t len) +GIT_INLINE(int) git_tag_lookup_prefix( + git_tag **out, git_repository *repo, const git_oid *id, size_t len) { - return git_object_lookup_prefix((git_object **)tag, repo, id, len, (git_otype)GIT_OBJ_TAG); + return git_object_lookup_prefix( + (git_object **)out, repo, id, len, (git_otype)GIT_OBJ_TAG); } /** * Close an open tag * - * This is a wrapper around git_object_free() + * You can no longer use the git_tag pointer after this call. * - * IMPORTANT: - * It *is* necessary to call this method when you stop - * using a tag. Failure to do so will cause a memory leak. + * IMPORTANT: You MUST call this method when you are through with a tag to + * release memory. Failure to do so will cause a memory leak. * * @param tag the tag to close */ GIT_INLINE(void) git_tag_free(git_tag *tag) { - git_object_free((git_object *) tag); + git_object_free((git_object *)tag); } @@ -76,7 +79,7 @@ GIT_INLINE(void) git_tag_free(git_tag *tag) * @param tag a previously loaded tag. * @return object identity for the tag. */ -GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag); +GIT_EXTERN(const git_oid *) git_tag_id(const git_tag *tag); /** * Get the tagged object of a tag @@ -84,11 +87,11 @@ GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag); * This method performs a repository lookup for the * given object and returns it * - * @param target pointer where to store the target + * @param target_out pointer where to store the target * @param tag a previously loaded tag. * @return 0 or an error code */ -GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag); +GIT_EXTERN(int) git_tag_target(git_object **target_out, const git_tag *tag); /** * Get the OID of the tagged object of a tag @@ -96,7 +99,7 @@ GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag); * @param tag a previously loaded tag. * @return pointer to the OID */ -GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag); +GIT_EXTERN(const git_oid *) git_tag_target_id(const git_tag *tag); /** * Get the type of a tag's tagged object @@ -104,7 +107,7 @@ GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag); * @param tag a previously loaded tag. * @return type of the tagged object */ -GIT_EXTERN(git_otype) git_tag_target_type(git_tag *tag); +GIT_EXTERN(git_otype) git_tag_target_type(const git_tag *tag); /** * Get the name of a tag @@ -112,7 +115,7 @@ GIT_EXTERN(git_otype) git_tag_target_type(git_tag *tag); * @param tag a previously loaded tag. * @return name of the tag */ -GIT_EXTERN(const char *) git_tag_name(git_tag *tag); +GIT_EXTERN(const char *) git_tag_name(const git_tag *tag); /** * Get the tagger (author) of a tag @@ -120,7 +123,7 @@ GIT_EXTERN(const char *) git_tag_name(git_tag *tag); * @param tag a previously loaded tag. * @return reference to the tag's author */ -GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *tag); +GIT_EXTERN(const git_signature *) git_tag_tagger(const git_tag *tag); /** * Get the message of a tag @@ -128,7 +131,7 @@ GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *tag); * @param tag a previously loaded tag. * @return message of the tag */ -GIT_EXTERN(const char *) git_tag_message(git_tag *tag); +GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); /** @@ -167,13 +170,13 @@ GIT_EXTERN(const char *) git_tag_message(git_tag *tag); * is written in the /refs/tags folder, pointing to it */ GIT_EXTERN(int) git_tag_create( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - const git_signature *tagger, - const char *message, - int force); + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + const git_signature *tagger, + const char *message, + int force); /** * Create a new tag in the repository from a buffer @@ -185,10 +188,10 @@ GIT_EXTERN(int) git_tag_create( * @return 0 on success; error code otherwise */ GIT_EXTERN(int) git_tag_create_frombuffer( - git_oid *oid, - git_repository *repo, - const char *buffer, - int force); + git_oid *oid, + git_repository *repo, + const char *buffer, + int force); /** * Create a new lightweight tag pointing at a target object @@ -218,11 +221,11 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * pointing to the provided target object */ GIT_EXTERN(int) git_tag_create_lightweight( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - int force); + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + int force); /** * Delete an existing tag reference. @@ -235,8 +238,8 @@ GIT_EXTERN(int) git_tag_create_lightweight( * @return 0 or an error code */ GIT_EXTERN(int) git_tag_delete( - git_repository *repo, - const char *tag_name); + git_repository *repo, + const char *tag_name); /** * Fill a list with all the tags in the Repository @@ -252,8 +255,8 @@ GIT_EXTERN(int) git_tag_delete( * @return 0 or an error code */ GIT_EXTERN(int) git_tag_list( - git_strarray *tag_names, - git_repository *repo); + git_strarray *tag_names, + git_repository *repo); /** * Fill a list with all the tags in the Repository @@ -274,39 +277,39 @@ GIT_EXTERN(int) git_tag_list( * @return 0 or an error code */ GIT_EXTERN(int) git_tag_list_match( - git_strarray *tag_names, - const char *pattern, - git_repository *repo); + git_strarray *tag_names, + const char *pattern, + git_repository *repo); -typedef int (*git_tag_foreach_cb)(const char *name, git_oid *oid, void *data); +typedef int (*git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload); + /** * Call callback `cb' for each tag in the repository * * @param repo Repository - * @param cb Callback function - * @param cb_data Pointer to callback data (optional) + * @param callback Callback function + * @param payload Pointer to callback data (optional) */ GIT_EXTERN(int) git_tag_foreach( - git_repository *repo, - git_tag_foreach_cb cb, - void *cb_data); + git_repository *repo, + git_tag_foreach_cb callback, + void *payload); /** - * Recursively peel a tag until a non tag git_object - * is met + * Recursively peel a tag until a non tag git_object is found * * The retrieved `tag_target` object is owned by the repository * and should be closed with the `git_object_free` method. * - * @param tag_target Pointer to the peeled git_object + * @param tag_target_out Pointer to the peeled git_object * @param tag The tag to be processed * @return 0 or an error code */ GIT_EXTERN(int) git_tag_peel( - git_object **tag_target, - git_tag *tag); + git_object **tag_target_out, + const git_tag *tag); /** @} */ GIT_END_DECL diff --git a/include/git2/transport.h b/include/git2/transport.h index b2bdaae71..5a27d7f97 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -45,12 +45,12 @@ typedef struct git_cred_userpass_plaintext { /** * Creates a new plain-text username and password credential object. * - * @param cred The newly created credential object. + * @param out The newly created credential object. * @param username The username of the credential. * @param password The password of the credential. */ GIT_EXTERN(int) git_cred_userpass_plaintext_new( - git_cred **cred, + git_cred **out, const char *username, const char *password); @@ -64,7 +64,7 @@ GIT_EXTERN(int) git_cred_userpass_plaintext_new( typedef int (*git_cred_acquire_cb)( git_cred **cred, const char *url, - int allowed_types); + unsigned int allowed_types); /* *** End interface for credentials acquisition *** @@ -144,11 +144,11 @@ typedef struct git_transport { * 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 transport The newly created transport (out) + * @param out The newly created transport (out) * @param url The URL to connect to * @return 0 or an error code */ -GIT_EXTERN(int) git_transport_new(git_transport **transport, const char *url); +GIT_EXTERN(int) git_transport_new(git_transport **out, const char *url); /** * Function which checks to see if a transport could be created for the @@ -161,7 +161,7 @@ GIT_EXTERN(int) git_transport_new(git_transport **transport, const char *url); GIT_EXTERN(int) git_transport_valid_url(const char *url); /* Signature of a function which creates a transport */ -typedef int (*git_transport_cb)(git_transport **transport, void *param); +typedef int (*git_transport_cb)(git_transport **out, void *payload); /* Transports which come with libgit2 (match git_transport_cb). The expected * value for "param" is listed in-line below. */ @@ -170,34 +170,34 @@ typedef int (*git_transport_cb)(git_transport **transport, void *param); * Create an instance of the dummy transport. * * @param transport The newly created transport (out) - * @param param You must pass NULL for this parameter. + * @param payload You must pass NULL for this parameter. * @return 0 or an error code */ GIT_EXTERN(int) git_transport_dummy( git_transport **transport, - /* NULL */ void *param); + /* NULL */ void *payload); /** * Create an instance of the local transport. * * @param transport The newly created transport (out) - * @param param You must pass NULL for this parameter. + * @param payload You must pass NULL for this parameter. * @return 0 or an error code */ GIT_EXTERN(int) git_transport_local( git_transport **transport, - /* NULL */ void *param); + /* NULL */ void *payload); /** * Create an instance of the smart transport. * * @param transport The newly created transport (out) - * @param param A pointer to a git_smart_subtransport_definition + * @param payload A pointer to a git_smart_subtransport_definition * @return 0 or an error code */ GIT_EXTERN(int) git_transport_smart( git_transport **transport, - /* (git_smart_subtransport_definition *) */ void *param); + /* (git_smart_subtransport_definition *) */ void *payload); /* *** End of base transport interface *** diff --git a/include/git2/tree.h b/include/git2/tree.h index 527f81819..2d3534fab 100644 --- a/include/git2/tree.h +++ b/include/git2/tree.h @@ -24,14 +24,15 @@ GIT_BEGIN_DECL /** * Lookup a tree object from the repository. * - * @param tree pointer to the looked up tree - * @param repo the repo to use when locating the tree. - * @param id identity of the tree to locate. + * @param out Pointer to the looked up tree + * @param repo The repo to use when locating the tree. + * @param id Identity of the tree to locate. * @return 0 or an error code */ -GIT_INLINE(int) git_tree_lookup(git_tree **tree, git_repository *repo, const git_oid *id) +GIT_INLINE(int) git_tree_lookup( + git_tree **out, git_repository *repo, const git_oid *id) { - return git_object_lookup((git_object **)tree, repo, id, GIT_OBJ_TREE); + return git_object_lookup((git_object **)out, repo, id, GIT_OBJ_TREE); } /** @@ -47,54 +48,31 @@ GIT_INLINE(int) git_tree_lookup(git_tree **tree, git_repository *repo, const git * @return 0 or an error code */ GIT_INLINE(int) git_tree_lookup_prefix( - git_tree **tree, + git_tree **out, git_repository *repo, const git_oid *id, size_t len) { - return git_object_lookup_prefix((git_object **)tree, repo, id, len, GIT_OBJ_TREE); + return git_object_lookup_prefix( + (git_object **)out, repo, id, len, GIT_OBJ_TREE); } /** * Close an open tree * - * This is a wrapper around git_object_free() + * You can no longer use the git_tree pointer after this call. * - * IMPORTANT: - * It *is* necessary to call this method when you stop - * using a tree. Failure to do so will cause a memory leak. + * IMPORTANT: You MUST call this method when you stop using a tree to + * release memory. Failure to do so will cause a memory leak. * - * @param tree the tree to close + * @param tree The tree to close */ GIT_INLINE(void) git_tree_free(git_tree *tree) { - git_object_free((git_object *) tree); + git_object_free((git_object *)tree); } /** - * Free a tree entry - * - * IMPORTANT: This function is only needed for tree - * entries owned by the user, such as the ones returned - * by `git_tree_entry_dup`. - * - * @param entry The entry to free - */ -GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); - -/** - * Duplicate a tree entry - * - * Create a copy of a tree entry. The returned copy is owned - * by the user, and must be freed manually with - * `git_tree_entry_free`. - * - * @param entry A tree entry to duplicate - * @return a copy of the original entry - */ -GIT_EXTERN(git_tree_entry *) git_tree_entry_dup(const git_tree_entry *entry); - -/** * Get the id of a tree. * * @param tree a previously loaded tree. @@ -108,44 +86,87 @@ GIT_EXTERN(const git_oid *) git_tree_id(const git_tree *tree); * @param tree a previously loaded tree. * @return the number of entries in the tree */ -GIT_EXTERN(unsigned int) git_tree_entrycount(const git_tree *tree); +GIT_EXTERN(size_t) git_tree_entrycount(const git_tree *tree); /** * Lookup a tree entry by its filename * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * * @param tree a previously loaded tree. * @param filename the filename of the desired entry * @return the tree entry; NULL if not found */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *filename); +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( + git_tree *tree, const char *filename); /** * Lookup a tree entry by its position in the tree * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * * @param tree a previously loaded tree. * @param idx the position in the entry list * @return the tree entry; NULL if not found */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex(git_tree *tree, size_t idx); +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( + git_tree *tree, size_t idx); /** * Lookup a tree entry by SHA value. * + * This returns a git_tree_entry that is owned by the git_tree. You don't + * have to free it, but you must not use it after the git_tree is released. + * * Warning: this must examine every entry in the tree, so it is not fast. * * @param tree a previously loaded tree. * @param oid the sha being looked for * @return the tree entry; NULL if not found */ -GIT_EXTERN(const git_tree_entry *) git_tree_entry_byoid(git_tree *tree, const git_oid *oid); +GIT_EXTERN(const git_tree_entry *) git_tree_entry_byoid( + const git_tree *tree, const git_oid *oid); /** - * Get the UNIX file attributes of a tree entry + * Retrieve a tree entry contained in a tree or in any of its subtrees, + * given its relative path. * - * @param entry a tree entry - * @return filemode as an integer + * Unlike the other lookup functions, the returned tree entry is owned by + * the user and must be freed explicitly with `git_tree_entry_free()`. + * + * @param out Pointer where to store the tree entry + * @param root Previously loaded tree which is the root of the relative path + * @param subtree_path Path to the contained entry + * @return 0 on success; GIT_ENOTFOUND if the path does not exist */ -GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); +GIT_EXTERN(int) git_tree_entry_bypath( + git_tree_entry **out, + git_tree *root, + const char *path); + +/** + * Duplicate a tree entry + * + * Create a copy of a tree entry. The returned copy is owned by the user, + * and must be freed explicitly with `git_tree_entry_free()`. + * + * @param entry A tree entry to duplicate + * @return a copy of the original entry or NULL on error (alloc failure) + */ +GIT_EXTERN(git_tree_entry *) git_tree_entry_dup(const git_tree_entry *entry); + +/** + * Free a user-owned tree entry + * + * IMPORTANT: This function is only needed for tree entries owned by the + * user, such as the ones returned by `git_tree_entry_dup()` or + * `git_tree_entry_bypath()`. + * + * @param entry The entry to free + */ +GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); /** * Get the filename of a tree entry @@ -172,8 +193,18 @@ GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); GIT_EXTERN(git_otype) git_tree_entry_type(const git_tree_entry *entry); /** + * Get the UNIX file attributes of a tree entry + * + * @param entry a tree entry + * @return filemode as an integer + */ +GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); + +/** * Convert a tree entry to the git_object it points too. * + * You must call `git_object_free()` on the object when you are done with it. + * * @param object pointer to the converted object * @param repo repository where to lookup the pointed object * @param entry a tree entry @@ -187,21 +218,21 @@ GIT_EXTERN(int) git_tree_entry_to_object( /** * Create a new tree builder. * - * The tree builder can be used to create or modify - * trees in memory and write them as tree objects to the - * database. + * The tree builder can be used to create or modify trees in memory and + * write them as tree objects to the database. * - * If the `source` parameter is not NULL, the tree builder - * will be initialized with the entries of the given tree. + * If the `source` parameter is not NULL, the tree builder will be + * initialized with the entries of the given tree. * - * If the `source` parameter is NULL, the tree builder will - * have no entries and will have to be filled manually. + * If the `source` parameter is NULL, the tree builder will start with no + * entries and will have to be filled manually. * - * @param builder_p Pointer where to store the tree builder + * @param out Pointer where to store the tree builder * @param source Source tree to initialize the builder (optional) * @return 0 on success; error code otherwise */ -GIT_EXTERN(int) git_treebuilder_create(git_treebuilder **builder_p, const git_tree *source); +GIT_EXTERN(int) git_treebuilder_create( + git_treebuilder **out, const git_tree *source); /** * Clear all the entires in the builder @@ -231,7 +262,8 @@ GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); * @param filename Name of the entry * @return pointer to the entry; NULL if not found */ -GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, const char *filename); +GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( + git_treebuilder *bld, const char *filename); /** * Add or update an entry to the builder @@ -239,17 +271,17 @@ GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, con * Insert a new entry for `filename` in the builder with the * given attributes. * - * if an entry named `filename` already exists, its attributes + * If an entry named `filename` already exists, its attributes * will be updated with the given ones. * - * The optional pointer `entry_out` can be used to retrieve a - * pointer to the newly created/updated entry. + * 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. * * No attempt is being made to ensure that the provided oid points * to an existing git object in the object database, nor that the * attributes make sense regarding the type of the pointed at object. * - * @param entry_out Pointer to store the entry (optional) + * @param out Pointer to store the entry (optional) * @param bld Tree builder * @param filename Filename of the entry * @param id SHA1 oid of the entry @@ -259,7 +291,7 @@ GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, con * @return 0 or an error code */ GIT_EXTERN(int) git_treebuilder_insert( - const git_tree_entry **entry_out, + const git_tree_entry **out, git_treebuilder *bld, const char *filename, const git_oid *id, @@ -271,85 +303,75 @@ GIT_EXTERN(int) git_treebuilder_insert( * @param bld Tree builder * @param filename Filename of the entry to remove */ -GIT_EXTERN(int) git_treebuilder_remove(git_treebuilder *bld, const char *filename); +GIT_EXTERN(int) git_treebuilder_remove( + git_treebuilder *bld, const char *filename); + +typedef int (*git_treebuilder_filter_cb)( + const git_tree_entry *entry, void *payload); /** * Filter the entries in the tree * - * The `filter` callback will be called for each entry - * in the tree with a pointer to the entry and the - * provided `payload`: if the callback returns 1, the - * entry will be filtered (removed from the builder). + * The `filter` callback will be called for each entry in the tree with a + * pointer to the entry and the provided `payload`; if the callback returns + * non-zero, the entry will be filtered (removed from the builder). * * @param bld Tree builder * @param filter Callback to filter entries + * @param payload Extra data to pass to filter */ GIT_EXTERN(void) git_treebuilder_filter( git_treebuilder *bld, - int (*filter)(const git_tree_entry *, void *), + git_treebuilder_filter_cb filter, void *payload); /** * Write the contents of the tree builder as a tree object * - * The tree builder will be written to the given `repo`, and - * it's identifying SHA1 hash will be stored in the `oid` - * pointer. + * The tree builder will be written to the given `repo`, and its + * identifying SHA1 hash will be stored in the `id` pointer. * - * @param oid Pointer where to store the written OID - * @param repo Repository where to store the object + * @param id Pointer to store the OID of the newly written tree + * @param repo Repository in which to store the object * @param bld Tree builder to write * @return 0 or an error code */ -GIT_EXTERN(int) git_treebuilder_write(git_oid *oid, git_repository *repo, git_treebuilder *bld); +GIT_EXTERN(int) git_treebuilder_write( + git_oid *id, git_repository *repo, git_treebuilder *bld); -/** - * Retrieve a tree entry contained in a tree or in any - * of its subtrees, given its relative path. - * - * The returned tree entry is owned by the user and must - * be freed manually with `git_tree_entry_free`. - * - * @param entry Pointer where to store the tree entry - * @param root A previously loaded tree which will be the root of the relative path - * @param subtree_path Path to the contained entry - * @return 0 on success; GIT_ENOTFOUND if the path does not exist - */ -GIT_EXTERN(int) git_tree_entry_bypath( - git_tree_entry **entry, - git_tree *root, - const char *path); /** Callback for the tree traversal method */ -typedef int (*git_treewalk_cb)(const char *root, const git_tree_entry *entry, void *payload); +typedef int (*git_treewalk_cb)( + const char *root, const git_tree_entry *entry, void *payload); /** Tree traversal modes */ -enum git_treewalk_mode { +typedef enum { GIT_TREEWALK_PRE = 0, /* Pre-order */ GIT_TREEWALK_POST = 1, /* Post-order */ -}; +} git_treewalk_mode; /** - * Traverse the entries in a tree and its subtrees in - * post or pre order + * Traverse the entries in a tree and its subtrees in post or pre order. * - * The entries will be traversed in the specified order, - * children subtrees will be automatically loaded as required, - * and the `callback` will be called once per entry with - * the current (relative) root for the entry and the entry - * data itself. + * The entries will be traversed in the specified order, children subtrees + * will be automatically loaded as required, and the `callback` will be + * called once per entry with the current (relative) root for the entry and + * the entry data itself. * * If the callback returns a positive value, the passed entry will be - * skipped on the traversal (in pre mode). A negative value stops the - * walk. + * skipped on the traversal (in pre mode). A negative value stops the walk. * * @param tree The tree to walk - * @param callback Function to call on each tree entry * @param mode Traversal mode (pre or post-order) + * @param callback Function to call on each tree entry * @param payload Opaque pointer to be passed on each callback * @return 0 or an error code */ -GIT_EXTERN(int) git_tree_walk(git_tree *tree, git_treewalk_cb callback, int mode, void *payload); +GIT_EXTERN(int) git_tree_walk( + const git_tree *tree, + git_treewalk_mode mode, + git_treewalk_cb callback, + void *payload); /** @} */ diff --git a/include/git2/types.h b/include/git2/types.h index 58cbaecc5..11bcf270f 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -129,7 +129,7 @@ typedef struct git_index git_index; typedef struct git_config git_config; /** Interface to access a configuration file */ -typedef struct git_config_file git_config_file; +typedef struct git_config_backend git_config_backend; /** Representation of a reference log entry */ typedef struct git_reflog_entry git_reflog_entry; @@ -175,13 +175,6 @@ typedef enum { GIT_BRANCH_REMOTE = 2, } git_branch_t; -/** Kinds of reset operation. */ -typedef enum { - GIT_RESET_SOFT = 1, - GIT_RESET_MIXED = 2, - GIT_RESET_HARD = 3, -} git_reset_type; - /** Valid modes for index and tree entries. */ typedef enum { GIT_FILEMODE_NEW = 0000000, |