diff options
| author | Edward Thomson <ethomson@edwardthomson.com> | 2021-08-29 21:29:14 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-08-29 21:29:14 -0400 |
| commit | 9937967efd8a1567727f1d716c1a2efb3085006c (patch) | |
| tree | 7d6c807e0fe6e0c594e2459a51f7ccd13f579339 /include/git2 | |
| parent | 216165ecfa6bdea6a000a1b69617b54f48203f87 (diff) | |
| parent | 0a79012e9df33db31046c653ab04c69eaeed200a (diff) | |
| download | libgit2-9937967efd8a1567727f1d716c1a2efb3085006c.tar.gz | |
Merge branch 'main' into http-use-eauth
Diffstat (limited to 'include/git2')
36 files changed, 1108 insertions, 304 deletions
diff --git a/include/git2/annotated_commit.h b/include/git2/annotated_commit.h index fa795bfc4..3b7103f20 100644 --- a/include/git2/annotated_commit.h +++ b/include/git2/annotated_commit.h @@ -78,7 +78,7 @@ GIT_EXTERN(int) git_annotated_commit_lookup( const git_oid *id); /** - * Creates a `git_annotated_comit` from a revision string. + * Creates a `git_annotated_commit` from a revision string. * * See `man gitrevisions`, or * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for diff --git a/include/git2/apply.h b/include/git2/apply.h index b248eaafe..bc637df1c 100644 --- a/include/git2/apply.h +++ b/include/git2/apply.h @@ -100,6 +100,7 @@ GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int ver * @param preimage the tree to apply the diff to * @param diff the diff to apply * @param options the options for the apply (or null for defaults) + * @return 0 or an error code */ GIT_EXTERN(int) git_apply_to_tree( git_index **out, @@ -137,6 +138,7 @@ typedef enum { * @param diff the diff to apply * @param location the location to apply (workdir, index or both) * @param options the options for the apply (or null for defaults) + * @return 0 or an error code */ GIT_EXTERN(int) git_apply( git_repository *repo, diff --git a/include/git2/attr.h b/include/git2/attr.h index a3ab5a7a2..62c2ed6e7 100644 --- a/include/git2/attr.h +++ b/include/git2/attr.h @@ -130,9 +130,32 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); * * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes * from a `.gitattributes` file in the repository at the HEAD revision. + * + * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes + * from a `.gitattributes` file in a specific commit. */ #define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) #define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3) +#define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4) + +/** +* An options structure for querying attributes. +*/ +typedef struct { + unsigned int version; + + /** A combination of GIT_ATTR_CHECK flags */ + unsigned int flags; + + /** + * The commit to load attributes from, when + * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified. + */ + git_oid *commit_id; +} git_attr_options; + +#define GIT_ATTR_OPTIONS_VERSION 1 +#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION} /** * Look up the value of one git attribute for path. @@ -157,6 +180,28 @@ GIT_EXTERN(int) git_attr_get( const char *name); /** + * Look up the value of one git attribute for path with extended options. + * + * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... + * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just + * use the string value for attributes set to a value. You + * should NOT modify or free this value. + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path The path to check for attributes. Relative paths are + * interpreted relative to the repo root. The file does + * not have to exist, but if it does not, then it will be + * treated as a plain file (not a directory). + * @param name The name of the attribute to look up. + */ +GIT_EXTERN(int) git_attr_get_ext( + const char **value_out, + git_repository *repo, + git_attr_options *opts, + const char *path, + const char *name); + +/** * Look up a list of git attributes for path. * * Use this if you have a known list of attributes that you want to @@ -194,6 +239,30 @@ GIT_EXTERN(int) git_attr_get_many( const char **names); /** + * Look up a list of git attributes for path with extended options. + * + * @param values_out An array of num_attr entries that will have string + * pointers written into it for the values of the attributes. + * You should not modify or free the values that are written + * into this array (although of course, you should free the + * array itself if you allocated it). + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path The path inside the repo to check attributes. This + * does not have to exist, but if it does not, then + * it will be treated as a plain file (i.e. not a directory). + * @param num_attr The number of attributes being looked up + * @param names An array of num_attr strings containing attribute names. + */ +GIT_EXTERN(int) git_attr_get_many_ext( + const char **values_out, + git_repository *repo, + git_attr_options *opts, + const char *path, + size_t num_attr, + const char **names); + +/** * The callback used with git_attr_foreach. * * This callback will be invoked only once per attribute name, even if there @@ -232,6 +301,26 @@ GIT_EXTERN(int) git_attr_foreach( void *payload); /** + * Loop over all the git attributes for a path with extended options. + * + * @param repo The repository containing the path. + * @param opts The `git_attr_options` to use when querying these attributes. + * @param path Path inside the repo to check attributes. This does not have + * to exist, but if it does not, then it will be treated as a + * plain file (i.e. not a directory). + * @param callback Function to invoke on each attribute name and value. + * See git_attr_foreach_cb. + * @param payload Passed on as extra parameter to callback function. + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_attr_foreach_ext( + git_repository *repo, + git_attr_options *opts, + const char *path, + git_attr_foreach_cb callback, + void *payload); + +/** * Flush the gitattributes cache. * * Call this if you have reason to believe that the attributes files on diff --git a/include/git2/blame.h b/include/git2/blame.h index 73f6cf979..d193ce14e 100644 --- a/include/git2/blame.h +++ b/include/git2/blame.h @@ -26,27 +26,54 @@ GIT_BEGIN_DECL typedef enum { /** Normal blame, the default */ GIT_BLAME_NORMAL = 0, - /** Track lines that have moved within a file (like `git blame -M`). - * NOT IMPLEMENTED. */ + + /** + * Track lines that have moved within a file (like `git blame -M`). + * + * This is not yet implemented and reserved for future use. + */ GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0), - /** Track lines that have moved across files in the same commit (like `git blame -C`). - * NOT IMPLEMENTED. */ + + /** + * Track lines that have moved across files in the same commit + * (like `git blame -C`). + * + * This is not yet implemented and reserved for future use. + */ GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1), - /** Track lines that have been copied from another file that exists in the - * same commit (like `git blame -CC`). Implies SAME_FILE. - * NOT IMPLEMENTED. */ + + /** + * Track lines that have been copied from another file that exists + * in the same commit (like `git blame -CC`). Implies SAME_FILE. + * + * This is not yet implemented and reserved for future use. + */ GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2), - /** Track lines that have been copied from another file that exists in *any* - * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES. - * NOT IMPLEMENTED. */ + + /** + * Track lines that have been copied from another file that exists in + * *any* commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES. + * + * This is not yet implemented and reserved for future use. + */ GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3), - /** Restrict the search of commits to those reachable following only the - * first parents. */ + + /** + * Restrict the search of commits to those reachable following only + * the first parents. + */ GIT_BLAME_FIRST_PARENT = (1<<4), - /** Use mailmap file to map author and committer names and email addresses - * to canonical real names and email addresses. The mailmap will be read - * from the working directory, or HEAD in a bare repository. */ + + /** + * Use mailmap file to map author and committer names and email + * addresses to canonical real names and email addresses. The + * mailmap will be read from the working directory, or HEAD in a + * bare repository. + */ GIT_BLAME_USE_MAILMAP = (1<<5), + + /** Ignore whitespace differences */ + GIT_BLAME_IGNORE_WHITESPACE = (1<<6), } git_blame_flag_t; /** @@ -61,25 +88,33 @@ typedef struct git_blame_options { /** A combination of `git_blame_flag_t` */ uint32_t flags; - /** The lower bound on the number of alphanumeric - * characters that must be detected as moving/copying within a file for it to - * associate those lines with the parent commit. The default value is 20. - * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*` - * flags are specified. + + /** + * The lower bound on the number of alphanumeric characters that + * must be detected as moving/copying within a file for it to + * associate those lines with the parent commit. The default value + * is 20. + * + * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*` + * flags are specified. */ uint16_t min_match_characters; + /** The id of the newest commit to consider. The default is HEAD. */ git_oid newest_commit; + /** * The id of the oldest commit to consider. * The default is the first commit encountered with a NULL parent. */ git_oid oldest_commit; + /** * The first line in the file to blame. * The default is 1 (line numbers start with 1). */ size_t min_line; + /** * The last line in the file to blame. * The default is the last line of the file. @@ -106,41 +141,59 @@ GIT_EXTERN(int) git_blame_options_init( /** * Structure that represents a blame hunk. - * - * - `lines_in_hunk` is the number of lines in this hunk - * - `final_commit_id` is the OID of the commit where this line was last - * changed. - * - `final_start_line_number` is the 1-based line number where this hunk - * begins, in the final version of the file - * - `final_signature` is the author of `final_commit_id`. If - * `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical - * real name and email address. - * - `orig_commit_id` is the OID of the commit where this hunk was found. This - * will usually be the same as `final_commit_id`, except when - * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified. - * - `orig_path` is the path to the file where this hunk originated, as of the - * commit specified by `orig_commit_id`. - * - `orig_start_line_number` is the 1-based line number where this hunk begins - * in the file named by `orig_path` in the commit specified by - * `orig_commit_id`. - * - `orig_signature` is the author of `orig_commit_id`. If - * `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical - * real name and email address. - * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the - * root, or the commit specified in git_blame_options.oldest_commit) */ typedef struct git_blame_hunk { + /** + * The number of lines in this hunk. + */ size_t lines_in_hunk; + /** + * The OID of the commit where this line was last changed. + */ git_oid final_commit_id; + + /** + * The 1-based line number where this hunk begins, in the final version + * of the file. + */ size_t final_start_line_number; + + /** + * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been + * specified, it will contain the canonical real name and email address. + */ git_signature *final_signature; + /** + * The OID of the commit where this hunk was found. + * This will usually be the same as `final_commit_id`, except when + * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified. + */ git_oid orig_commit_id; + + /** + * The path to the file where this hunk originated, as of the commit + * specified by `orig_commit_id`. + */ const char *orig_path; + + /** + * The 1-based line number where this hunk begins in the file named by + * `orig_path` in the commit specified by `orig_commit_id`. + */ size_t orig_start_line_number; + + /** + * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been + * specified, it will contain the canonical real name and email address. + */ git_signature *orig_signature; + /** + * The 1 iff the hunk has been tracked to a boundary commit (the root, + * or the commit specified in git_blame_options.oldest_commit) + */ char boundary; } git_blame_hunk; diff --git a/include/git2/blob.h b/include/git2/blob.h index 7e2a745d1..fceb5c771 100644 --- a/include/git2/blob.h +++ b/include/git2/blob.h @@ -84,7 +84,7 @@ GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob); * time. * * @param blob pointer to the blob - * @return the pointer + * @return the pointer, or NULL on error */ GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob); @@ -113,23 +113,51 @@ typedef enum { * When set, filters will be loaded from a `.gitattributes` file * in the HEAD commit. */ - GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD = (1 << 2), + GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD = (1 << 2), + + /** + * When set, filters will be loaded from a `.gitattributes` file + * in the specified commit. + */ + GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT = (1 << 3), } git_blob_filter_flag_t; /** * The options used when applying filter options to a file. + * + * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can + * use `git_blob_filter_options_init`. + * */ typedef struct { int version; /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ uint32_t flags; + + /** + * The commit to load attributes from, when + * `GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. + */ + git_oid *commit_id; } git_blob_filter_options; #define GIT_BLOB_FILTER_OPTIONS_VERSION 1 #define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} /** + * Initialize git_blob_filter_options structure + * + * Initializes a `git_blob_filter_options` with default values. Equivalent + * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`. + * + * @param opts The `git_blob_filter_options` struct to initialize. + * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version); + +/** * Get a buffer with the filtered content of a blob. * * This applies filters as if the blob was being checked out to the @@ -229,7 +257,7 @@ GIT_EXTERN(int) git_blob_create_from_stream_commit( * Write an in-memory buffer to the ODB as a blob * * @param id return the id of the written blob - * @param repo repository where to blob will be written + * @param repo repository where the blob will be written * @param buffer data to be written into the blob * @param len length of the data * @return 0 or an error code diff --git a/include/git2/branch.h b/include/git2/branch.h index ba6235900..24ea7f7d0 100644 --- a/include/git2/branch.h +++ b/include/git2/branch.h @@ -304,6 +304,31 @@ GIT_EXTERN(int) git_branch_remote_name( */ GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname); +/** + * Retrieve the upstream merge of a local branch + * + * This will return the currently configured "branch.*.merge" for a given + * branch. This branch must be local. + * + * @param buf the buffer into which to write the name + * @param repo the repository in which to look + * @param refname the full name of the branch + * @return 0 or an error code + */ + GIT_EXTERN(int) git_branch_upstream_merge(git_buf *buf, git_repository *repo, const char *refname); + +/** + * Determine whether a branch name is valid, meaning that (when prefixed + * with `refs/heads/`) that it is a valid reference name, and that any + * additional branch name restrictions are imposed (eg, it cannot start + * with a `-`). + * + * @param valid output pointer to set with validity of given branch name + * @param name a branch name to test + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_branch_name_is_valid(int *valid, const char *name); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/cert.h b/include/git2/cert.h index e8cd2d180..0ed38ffcd 100644 --- a/include/git2/cert.h +++ b/include/git2/cert.h @@ -8,6 +8,7 @@ #define INCLUDE_git_cert_h__ #include "common.h" +#include "types.h" /** * @file git2/cert.h @@ -80,8 +81,27 @@ typedef enum { GIT_CERT_SSH_SHA1 = (1 << 1), /** SHA-256 is available */ GIT_CERT_SSH_SHA256 = (1 << 2), + /** Raw hostkey is available */ + GIT_CERT_SSH_RAW = (1 << 3), } git_cert_ssh_t; +typedef enum { + /** The raw key is of an unknown type. */ + GIT_CERT_SSH_RAW_TYPE_UNKNOWN = 0, + /** The raw key is an RSA key. */ + GIT_CERT_SSH_RAW_TYPE_RSA = 1, + /** The raw key is a DSS key. */ + GIT_CERT_SSH_RAW_TYPE_DSS = 2, + /** The raw key is a ECDSA 256 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_256 = 3, + /** The raw key is a ECDSA 384 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_384 = 4, + /** The raw key is a ECDSA 521 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ECDSA_521 = 5, + /** The raw key is a ED25519 key. */ + GIT_CERT_SSH_RAW_TYPE_KEY_ED25519 = 6 +} git_cert_ssh_raw_type_t; + /** * Hostkey information taken from libssh2 */ @@ -89,28 +109,45 @@ typedef struct { git_cert parent; /**< The parent cert */ /** - * A hostkey type from libssh2, either - * `GIT_CERT_SSH_MD5` or `GIT_CERT_SSH_SHA1` + * A bitmask containing the available fields. */ git_cert_ssh_t type; /** - * Hostkey hash. If type has `GIT_CERT_SSH_MD5` set, this will + * Hostkey hash. If `type` has `GIT_CERT_SSH_MD5` set, this will * have the MD5 hash of the hostkey. */ unsigned char hash_md5[16]; /** - * Hostkey hash. If type has `GIT_CERT_SSH_SHA1` set, this will + * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA1` set, this will * have the SHA-1 hash of the hostkey. */ unsigned char hash_sha1[20]; /** - * Hostkey hash. If type has `GIT_CERT_SSH_SHA256` set, this will + * Hostkey hash. If `type` has `GIT_CERT_SSH_SHA256` set, this will * have the SHA-256 hash of the hostkey. */ unsigned char hash_sha256[32]; + + /** + * Raw hostkey type. If `type` has `GIT_CERT_SSH_RAW` set, this will + * have the type of the raw hostkey. + */ + git_cert_ssh_raw_type_t raw_type; + + /** + * Pointer to the raw hostkey. If `type` has `GIT_CERT_SSH_RAW` set, + * this will have the raw contents of the hostkey. + */ + const char *hostkey; + + /** + * Raw hostkey length. If `type` has `GIT_CERT_SSH_RAW` set, this will + * have the length of the raw contents of the hostkey. + */ + size_t hostkey_len; } git_cert_hostkey; /** diff --git a/include/git2/checkout.h b/include/git2/checkout.h index 3c87001bf..ca6f17aa6 100644 --- a/include/git2/checkout.h +++ b/include/git2/checkout.h @@ -194,18 +194,6 @@ typedef enum { * Checkout will invoke an options notification callback (`notify_cb`) for * certain cases - you pick which ones via `notify_flags`: * - * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths. - * - * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that - * do not need an update but no longer match the baseline. Core git - * displays these files when checkout runs, but won't stop the checkout. - * - * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed. - * - * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files. - * - * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files. - * * Returning a non-zero value from this callback will cancel the checkout. * The non-zero return value will be propagated back and returned by the * git_checkout_... call. @@ -216,10 +204,32 @@ typedef enum { */ typedef enum { GIT_CHECKOUT_NOTIFY_NONE = 0, + + /** + * Invokes checkout on conflicting paths. + */ GIT_CHECKOUT_NOTIFY_CONFLICT = (1u << 0), + + /** + * Notifies about "dirty" files, i.e. those that do not need an update + * but no longer match the baseline. Core git displays these files when + * checkout runs, but won't stop the checkout. + */ GIT_CHECKOUT_NOTIFY_DIRTY = (1u << 1), + + /** + * Sends notification for any file changed. + */ GIT_CHECKOUT_NOTIFY_UPDATED = (1u << 2), + + /** + * Notifies about untracked files. + */ GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3), + + /** + * Notifies about ignored files. + */ GIT_CHECKOUT_NOTIFY_IGNORED = (1u << 4), GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu diff --git a/include/git2/common.h b/include/git2/common.h index d6696061d..d278c01b6 100644 --- a/include/git2/common.h +++ b/include/git2/common.h @@ -91,10 +91,10 @@ GIT_BEGIN_DECL /** * The separator used in path list strings (ie like in the PATH - * environment variable). A semi-colon ";" is used on Windows, and - * a colon ":" for all other systems. + * environment variable). A semi-colon ";" is used on Windows and + * AmigaOS, and a colon ":" for all other systems. */ -#ifdef GIT_WIN32 +#if defined(GIT_WIN32) || defined(AMIGA) #define GIT_PATH_LIST_SEPARATOR ';' #else #define GIT_PATH_LIST_SEPARATOR ':' @@ -205,7 +205,11 @@ typedef enum { GIT_OPT_GET_PACK_MAX_OBJECTS, GIT_OPT_SET_PACK_MAX_OBJECTS, GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, - GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE + GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, + GIT_OPT_GET_MWINDOW_FILE_LIMIT, + GIT_OPT_SET_MWINDOW_FILE_LIMIT, + GIT_OPT_SET_ODB_PACKED_PRIORITY, + GIT_OPT_SET_ODB_LOOSE_PRIORITY } git_libgit2_opt_t; /** @@ -227,8 +231,18 @@ typedef enum { * * * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t): * - * >Set the maximum amount of memory that can be mapped at any time - * by the library + * > Set the maximum amount of memory that can be mapped at any time + * > by the library + * + * * opts(GIT_OPT_GET_MWINDOW_FILE_LIMIT, size_t *): + * + * > Get the maximum number of files that will be mapped at any time by the + * > library + * + * * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t): + * + * > Set the maximum number of files that can be mapped at any time + * > by the library. The default (0) is unlimited. * * * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf) * @@ -344,6 +358,11 @@ typedef enum { * > * > - `ciphers` is the list of ciphers that are eanbled. * + * * opts(GIT_OPT_GET_USER_AGENT, git_buf *out) + * + * > Get the value of the User-Agent header. + * > The User-Agent is written to the `out` buffer. + * * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) * * > Enable or disable the use of "offset deltas" when creating packfiles, @@ -404,6 +423,14 @@ typedef enum { * > authentication, use expect/continue when POSTing data. * > This option is not available on Windows. * + * opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority) + * > Override the default priority of the packed ODB backend which + * > is added when default backends are assigned to a repository + * + * opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority) + * > Override the default priority of the loose ODB backend which + * > is added when default backends are assigned to a repository + * * @param option Option key * @param ... value to set the option * @return 0 on success, <0 on failure diff --git a/include/git2/config.h b/include/git2/config.h index abf5bbbd0..7c8e388b2 100644 --- a/include/git2/config.h +++ b/include/git2/config.h @@ -263,7 +263,7 @@ GIT_EXTERN(int) git_config_open_level( * * Git allows you to store your global configuration at * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards - * compatability, the XDG file shouldn't be used unless the use has + * compatibility, the XDG file shouldn't be used unless the use has * created it explicitly. With this function you'll open the correct * one to write to. * diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h index 61d0115fd..ac60488ac 100644 --- a/include/git2/deprecated.h +++ b/include/git2/deprecated.h @@ -18,6 +18,7 @@ #include "describe.h" #include "diff.h" #include "errors.h" +#include "filter.h" #include "index.h" #include "indexer.h" #include "merge.h" @@ -29,6 +30,7 @@ #include "trace.h" #include "repository.h" #include "revert.h" +#include "revparse.h" #include "stash.h" #include "status.h" #include "submodule.h" @@ -41,6 +43,13 @@ */ #ifndef GIT_DEPRECATE_HARD +/* + * The credential structures are now opaque by default, and their + * definition has moved into the `sys/credential.h` header; include + * them here for backward compatibility. + */ +#include "sys/credential.h" + /** * @file git2/deprecated.h * @brief libgit2 deprecated functions and values @@ -73,16 +82,19 @@ typedef git_attr_value_t git_attr_t; /**@}*/ -/** @name Deprecated Blob Functions +/** @name Deprecated Blob Functions and Constants * - * These functions are retained for backward compatibility. The newer - * versions of these functions should be preferred in all new code. + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these functions and values + * should be preferred in all new code. * * There is no plan to remove these backward compatibility values at * this time. */ /**@{*/ +#define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD + GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path); GIT_EXTERN(int) git_blob_create_fromdisk(git_oid *id, git_repository *repo, const char *path); GIT_EXTERN(int) git_blob_create_fromstream( @@ -95,7 +107,11 @@ GIT_EXTERN(int) git_blob_create_fromstream_commit( GIT_EXTERN(int) git_blob_create_frombuffer( git_oid *id, git_repository *repo, const void *buffer, size_t len); -/** Deprecated in favor of @see git_blob_filter */ +/** Deprecated in favor of `git_blob_filter`. + * + * @deprecated Use git_blob_filter + * @see git_blob_filter + */ GIT_EXTERN(int) git_blob_filtered_content( git_buf *out, git_blob *blob, @@ -104,6 +120,66 @@ GIT_EXTERN(int) git_blob_filtered_content( /**@}*/ +/** @name Deprecated Filter Functions + * + * These functions are retained for backward compatibility. The + * newer versions of these functions should be preferred in all + * new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** Deprecated in favor of `git_filter_list_stream_buffer`. + * + * @deprecated Use git_filter_list_stream_buffer + * @see Use git_filter_list_stream_buffer + */ +GIT_EXTERN(int) git_filter_list_stream_data( + git_filter_list *filters, + git_buf *data, + git_writestream *target); + +/** Deprecated in favor of `git_filter_list_apply_to_buffer`. + * + * @deprecated Use git_filter_list_apply_to_buffer + * @see Use git_filter_list_apply_to_buffer + */ +GIT_EXTERN(int) git_filter_list_apply_to_data( + git_buf *out, + git_filter_list *filters, + git_buf *in); + +/**@}*/ + +/** @name Deprecated Tree Functions + * + * These functions are retained for backward compatibility. The + * newer versions of these functions and values should be preferred + * in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Write the contents of the tree builder as a tree object. + * This is an alias of `git_treebuilder_write` and is preserved + * for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_treebuilder_write + * @see git_treebuilder_write + */ +GIT_EXTERN(int) git_treebuilder_write_with_buffer( + git_oid *oid, git_treebuilder *bld, git_buf *tree); + +/**@}*/ + /** @name Deprecated Buffer Functions * * These functions and enumeration values are retained for backward @@ -226,7 +302,7 @@ GIT_EXTERN(void) giterr_clear(void); GIT_EXTERN(void) giterr_set_str(int error_class, const char *string); /** - * Indicates that an out-of-memory situation occured. This is an alias + * Indicates that an out-of-memory situation occurred. This is an alias * of `git_error_set_oom` and is preserved for backward compatibility. * * This function is deprecated, but there is no plan to remove this @@ -329,10 +405,32 @@ GIT_EXTERN(size_t) git_object__size(git_object_t type); /**@}*/ -/** @name Deprecated Reference Constants +/** @name Deprecated Remote Functions * - * These enumeration values are retained for backward compatibility. The - * newer versions of these values should be preferred in all new code. + * These functions are retained for backward compatibility. The newer + * versions of these functions should be preferred in all new code. + * + * There is no plan to remove these backward compatibility functions at + * this time. + */ +/**@{*/ + +/** + * Ensure the remote name is well-formed. + * + * @deprecated Use git_remote_name_is_valid + * @param remote_name name to be checked. + * @return 1 if the reference name is acceptable; 0 if it isn't + */ +GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); + +/**@}*/ + +/** @name Deprecated Reference Functions and Constants + * + * These functions and enumeration values are retained for backward + * compatibility. The newer versions of these values should be + * preferred in all new code. * * There is no plan to remove these backward compatibility values at * this time. @@ -353,6 +451,23 @@ GIT_EXTERN(size_t) git_object__size(git_object_t type); #define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN #define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND +/** + * Ensure the reference name is well-formed. + * + * Valid reference names must follow one of two patterns: + * + * 1. Top-level names must contain only capital letters and underscores, + * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). + * 2. Names prefixed with "refs/" can be almost anything. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * + * @deprecated Use git_reference_name_is_valid + * @param refname name to be checked. + * @return 1 if the reference name is acceptable; 0 if it isn't + */ +GIT_EXTERN(int) git_reference_is_valid_name(const char *refname); + GIT_EXTERN(int) git_tag_create_frombuffer( git_oid *oid, git_repository *repo, @@ -361,6 +476,25 @@ GIT_EXTERN(int) git_tag_create_frombuffer( /**@}*/ +/** @name Deprecated Revspec Constants + * + * These enumeration values are retained for backward compatibility. + * The newer versions of these values should be preferred in all new + * code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +typedef git_revspec_t git_revparse_mode_t; + +#define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE +#define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE +#define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE + +/**@}*/ + /** @name Deprecated Credential Types * * These types are retained for backward compatibility. The newer @@ -369,6 +503,7 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * There is no plan to remove these backward compatibility values at * this time. */ +/**@{*/ typedef git_credential git_cred; typedef git_credential_userpass_plaintext git_cred_userpass_plaintext; @@ -517,6 +652,42 @@ typedef int GIT_CALLBACK(git_headlist_cb)(git_remote_head *rhead, void *payload) /**@}*/ +/** @name Deprecated String Array Functions + * + * These types are retained for backward compatibility. The newer + * versions of these values should be preferred in all new code. + * + * There is no plan to remove these backward compatibility values at + * this time. + */ +/**@{*/ + +/** + * Copy a string array object from source to target. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @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); + +/** + * Free the memory referred to by the git_strarray. This is an alias of + * `git_strarray_dispose` and is preserved for backward compatibility. + * + * This function is deprecated, but there is no plan to remove this + * function at this time. + * + * @deprecated Use git_strarray_dispose + * @see git_strarray_dispose + */ +GIT_EXTERN(void) git_strarray_free(git_strarray *array); + +/**@}*/ + /** @name Deprecated Options Initialization Functions * * These functions are retained for backward compatibility. The newer diff --git a/include/git2/diff.h b/include/git2/diff.h index 3976ab1b9..9497793c3 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -168,6 +168,10 @@ typedef enum { * can apply given diff information to binary files. */ GIT_DIFF_SHOW_BINARY = (1u << 30), + + /** Ignore blank lines */ + GIT_DIFF_IGNORE_BLANK_LINES = (1u << 31), + } git_diff_option_t; /** @@ -237,32 +241,43 @@ typedef enum { * Although this is called a "file", it could represent a file, a symbolic * link, a submodule commit id, or even a tree (although that only if you * are tracking type changes or ignored/untracked directories). - * - * The `id` is the `git_oid` of the item. If the entry represents an - * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), - * then the oid will be zeroes. - * - * `path` is the NUL-terminated path to the entry relative to the working - * directory of the repository. - * - * `size` is the size of the entry in bytes. - * - * `flags` is a combination of the `git_diff_flag_t` types - * - * `mode` is, roughly, the stat() `st_mode` value for the item. This will - * be restricted to one of the `git_filemode_t` values. - * - * The `id_abbrev` represents the known length of the `id` field, when - * converted to a hex string. It is generally `GIT_OID_HEXSZ`, unless this - * delta was created from reading a patch file, in which case it may be - * abbreviated to something reasonable, like 7 characters. */ typedef struct { + /** + * The `git_oid` of the item. If the entry represents an + * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), + * then the oid will be zeroes. + */ git_oid id; + + /** + * The NUL-terminated path to the entry relative to the working + * directory of the repository. + */ const char *path; + + /** + * The size of the entry in bytes. + */ git_object_size_t size; + + /** + * A combination of the `git_diff_flag_t` types + */ uint32_t flags; + + /** + * Roughly, the stat() `st_mode` value for the item. This will + * be restricted to one of the `git_filemode_t` values. + */ uint16_t mode; + + /** + * Represents the known length of the `id` field, when + * converted to a hex string. It is generally `GIT_OID_HEXSZ`, unless this + * delta was created from reading a patch file, in which case it may be + * abbreviated to something reasonable, like 7 characters. + */ uint16_t id_abbrev; } git_diff_file; @@ -998,7 +1013,7 @@ GIT_EXTERN(size_t) git_diff_num_deltas(const git_diff *diff); /** * Query how many diff deltas are there in a diff filtered by type. * - * This works just like `git_diff_entrycount()` with an extra parameter + * This works just like `git_diff_num_deltas()` with an extra parameter * that is a `git_delta_t` and returns just the count of how many deltas * match that particular type. * diff --git a/include/git2/errors.h b/include/git2/errors.h index b4cb87f7a..de51582d5 100644 --- a/include/git2/errors.h +++ b/include/git2/errors.h @@ -107,7 +107,8 @@ typedef enum { GIT_ERROR_PATCH, GIT_ERROR_WORKTREE, GIT_ERROR_SHA1, - GIT_ERROR_HTTP + GIT_ERROR_HTTP, + GIT_ERROR_INTERNAL } git_error_t; /** diff --git a/include/git2/filter.h b/include/git2/filter.h index 886059051..044c3b870 100644 --- a/include/git2/filter.h +++ b/include/git2/filter.h @@ -49,9 +49,34 @@ typedef enum { /** Load attributes from `.gitattributes` in the root of HEAD */ GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2), + + /** + * Load attributes from `.gitattributes` in a given commit. + * This can only be specified in a `git_filter_options`. + */ + GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3), } git_filter_flag_t; /** + * Filtering options + */ +typedef struct { + unsigned int version; + + /** See `git_filter_flag_t` above */ + uint32_t flags; + + /** + * The commit to load attributes from, when + * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. + */ + git_oid *commit_id; +} git_filter_options; + + #define GIT_FILTER_OPTIONS_VERSION 1 + #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} + +/** * A filter that can transform file data * * This represents a filter that can be used to transform or even replace @@ -104,6 +129,29 @@ GIT_EXTERN(int) git_filter_list_load( uint32_t flags); /** + * Load the filter list for a given path. + * + * This will return 0 (success) but set the output git_filter_list to NULL + * if no filters are requested for the given file. + * + * @param filters Output newly created git_filter_list (or NULL) + * @param repo Repository object that contains `path` + * @param blob The blob to which the filter will be applied (if known) + * @param path Relative path of the file to be filtered + * @param mode Filtering direction (WT->ODB or ODB->WT) + * @param opts The `git_filter_options` to use when loading filters + * @return 0 on success (which could still return NULL if no filters are + * needed for the requested file), <0 on error + */ +GIT_EXTERN(int) git_filter_list_load_ext( + git_filter_list **filters, + git_repository *repo, + git_blob *blob, + const char *path, + git_filter_mode_t mode, + git_filter_options *opts); + +/** * Query the filter list to see if a given filter (by name) will run. * The built-in filters "crlf" and "ident" can be queried, otherwise this * is the name of the filter specified by the filter attribute. @@ -122,27 +170,17 @@ GIT_EXTERN(int) git_filter_list_contains( /** * Apply filter list to a data buffer. * - * See `git2/buffer.h` for background on `git_buf` objects. - * - * If the `in` buffer holds data allocated by libgit2 (i.e. `in->asize` is - * not zero), then it will be overwritten when applying the filters. If - * not, then it will be left untouched. - * - * If there are no filters to apply (or `filters` is NULL), then the `out` - * buffer will reference the `in` buffer data (with `asize` set to zero) - * instead of allocating data. This keeps allocations to a minimum, but - * it means you have to be careful about freeing the `in` data since `out` - * may be pointing to it! - * * @param out Buffer to store the result of the filtering * @param filters A loaded git_filter_list (or NULL) * @param in Buffer containing the data to filter + * @param in_len The length of the input buffer * @return 0 on success, an error code otherwise */ -GIT_EXTERN(int) git_filter_list_apply_to_data( +GIT_EXTERN(int) git_filter_list_apply_to_buffer( git_buf *out, git_filter_list *filters, - git_buf *in); + const char *in, + size_t in_len); /** * Apply a filter list to the contents of a file on disk @@ -175,12 +213,14 @@ GIT_EXTERN(int) git_filter_list_apply_to_blob( * Apply a filter list to an arbitrary buffer as a stream * * @param filters the list of filters to apply - * @param data the buffer to filter + * @param buffer the buffer to filter + * @param len the size of the buffer * @param target the stream into which the data will be written */ -GIT_EXTERN(int) git_filter_list_stream_data( +GIT_EXTERN(int) git_filter_list_stream_buffer( git_filter_list *filters, - git_buf *data, + const char *buffer, + size_t len, git_writestream *target); /** diff --git a/include/git2/graph.h b/include/git2/graph.h index 213ae9777..712ae474a 100644 --- a/include/git2/graph.h +++ b/include/git2/graph.h @@ -43,8 +43,9 @@ GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_reposi * Note that a commit is not considered a descendant of itself, in contrast * to `git merge-base --is-ancestor`. * - * @param commit a previously loaded commit. - * @param ancestor a potential ancestor commit. + * @param repo the repository where the commits exist + * @param commit a previously loaded commit + * @param ancestor a potential ancestor commit * @return 1 if the given commit is a descendant of the potential ancestor, * 0 if not, error code otherwise. */ @@ -53,6 +54,23 @@ GIT_EXTERN(int) git_graph_descendant_of( const git_oid *commit, const git_oid *ancestor); +/** + * Determine if a commit is reachable from any of a list of commits by + * following parent edges. + * + * @param repo the repository where the commits exist + * @param commit a previously loaded commit + * @param length the number of commits in the provided `descendant_array` + * @param descendant_array oids of the commits + * @return 1 if the given commit is an ancestor of any of the given potential + * descendants, 0 if not, error code otherwise. + */ +GIT_EXTERN(int) git_graph_reachable_from_any( + git_repository *repo, + const git_oid *commit, + const git_oid descendant_array[], + size_t length); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/index.h b/include/git2/index.h index 8723aa636..532a52091 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -349,7 +349,7 @@ GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index); * * The index must not contain any file in conflict. * - * @param out Pointer where to store OID of the the written tree + * @param out Pointer where to store OID of 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 @@ -555,8 +555,7 @@ GIT_EXTERN(int) git_index_add_bypath(git_index *index, const char *path); * * If a previous index entry exists that has the same path as the * given 'entry', it will be replaced. Otherwise, the 'entry' will be - * added. The `id` and the `file_size` of the 'entry' are updated with the - * real value of the blob. + * added. * * This forces the file to be added to the index, not looking * at gitignore rules. Those rules can be evaluated through @@ -703,7 +702,7 @@ GIT_EXTERN(int) git_index_update_all( * @param at_pos the address to which the position of the index entry is written (optional) * @param index an existing index object * @param path path to search - * @return a zero-based position in the index if found; GIT_ENOTFOUND otherwise + * @return 0 or an error code */ GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path); @@ -714,7 +713,7 @@ GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *pat * @param at_pos the address to which the position of the index entry is written (optional) * @param index an existing index object * @param prefix the prefix to search for - * @return 0 with valid value in at_pos; an error code otherwise + * @return 0 or an error code */ GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix); diff --git a/include/git2/indexer.h b/include/git2/indexer.h index 8059e4db3..a434d243f 100644 --- a/include/git2/indexer.h +++ b/include/git2/indexer.h @@ -51,7 +51,7 @@ typedef struct git_indexer_progress { * Type for progress callbacks during indexing. Return a value less * than zero to cancel the indexing or download. * - * @param stats Structure containing information about the state of the tran sfer + * @param stats Structure containing information about the state of the transfer * @param payload Payload provided by caller */ typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload); @@ -64,6 +64,7 @@ typedef struct git_indexer_options { /** progress_cb function to call with progress information */ git_indexer_progress_cb progress_cb; + /** progress_cb_payload payload for the progress callback */ void *progress_cb_payload; diff --git a/include/git2/odb.h b/include/git2/odb.h index c4bfa5290..702e1bd30 100644 --- a/include/git2/odb.h +++ b/include/git2/odb.h @@ -70,7 +70,7 @@ GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir); * * @param odb database to add the backend to * @param path path to the objects folder for the alternate - * @return 0 on success; error code otherwise + * @return 0 on success, error code otherwise */ GIT_EXTERN(int) git_odb_add_disk_alternate(git_odb *odb, const char *path); @@ -94,9 +94,8 @@ GIT_EXTERN(void) git_odb_free(git_odb *db); * @param out pointer where to store the read object * @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. + * @return 0 if the object was read, GIT_ENOTFOUND if the object is + * not in the database. */ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id); @@ -122,10 +121,9 @@ 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); @@ -143,9 +141,8 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git * @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. + * @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_out, git_object_t *type_out, git_odb *db, const git_oid *id); @@ -154,9 +151,7 @@ GIT_EXTERN(int) git_odb_read_header(size_t *len_out, git_object_t *type_out, git * * @param db database to be searched for the given object. * @param id the object to search for. - * @return - * - 1, if the object was found - * - 0, otherwise + * @return 1 if the object was found, 0 otherwise */ GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id); @@ -305,7 +300,7 @@ GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, git_obje * @param stream the stream * @param buffer the data to write * @param len the buffer's length - * @return 0 if the write succeeded; error code otherwise + * @return 0 if the write succeeded, error code otherwise */ GIT_EXTERN(int) git_odb_stream_write(git_odb_stream *stream, const char *buffer, size_t len); @@ -320,7 +315,7 @@ GIT_EXTERN(int) git_odb_stream_write(git_odb_stream *stream, const char *buffer, * * @param out pointer to store the resulting object's id * @param stream the stream - * @return 0 on success; an error code otherwise + * @return 0 on success, an error code otherwise */ GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stream); @@ -362,7 +357,7 @@ GIT_EXTERN(void) git_odb_stream_free(git_odb_stream *stream); * @param type pointer where to store the type of the object * @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 + * @return 0 if the stream was created, error code otherwise */ GIT_EXTERN(int) git_odb_open_rstream( git_odb_stream **out, @@ -501,7 +496,7 @@ GIT_EXTERN(git_object_t) git_odb_object_type(git_odb_object *object); * @param odb database to add the backend to * @param backend pointer to a git_odb_backend instance * @param priority Value for ordering the backends queue - * @return 0 on success; error code otherwise + * @return 0 on success, error code otherwise */ GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int priority); @@ -522,7 +517,7 @@ GIT_EXTERN(int) git_odb_add_backend(git_odb *odb, git_odb_backend *backend, int * @param odb database to add the backend to * @param backend pointer to a git_odb_backend instance * @param priority Value for ordering the backends queue - * @return 0 on success; error code otherwise + * @return 0 on success, error code otherwise */ GIT_EXTERN(int) git_odb_add_alternate(git_odb *odb, git_odb_backend *backend, int priority); @@ -540,10 +535,25 @@ GIT_EXTERN(size_t) git_odb_num_backends(git_odb *odb); * @param out output pointer to ODB backend at pos * @param odb object database * @param pos index into object database backend list - * @return 0 on success; GIT_ENOTFOUND if pos is invalid; other errors < 0 + * @return 0 on success, GIT_ENOTFOUND if pos is invalid, other errors < 0 */ GIT_EXTERN(int) git_odb_get_backend(git_odb_backend **out, git_odb *odb, size_t pos); +/** + * Set the git commit-graph for the ODB. + * + * After a successfull call, the ownership of the cgraph parameter will be + * transferred to libgit2, and the caller should not free it. + * + * The commit-graph can also be unset by explicitly passing NULL as the cgraph + * parameter. + * + * @param odb object database + * @param cgraph the git commit-graph + * @return 0 on success; error code otherwise + */ +GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/pack.h b/include/git2/pack.h index 922a3cd9d..3b9beb665 100644 --- a/include/git2/pack.h +++ b/include/git2/pack.h @@ -155,7 +155,7 @@ GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb); * Write the new pack and corresponding index file to path. * * @param pb The packbuilder - * @param path to the directory where the packfile and index should be stored + * @param path Path to the directory where the packfile and index should be stored, or NULL for default location * @param mode permissions to use creating a packfile or 0 for defaults * @param progress_cb function to call with progress information from the indexer (optional) * @param progress_cb_payload payload for the progress callback (optional) diff --git a/include/git2/patch.h b/include/git2/patch.h index b177798e6..fde9659e7 100644 --- a/include/git2/patch.h +++ b/include/git2/patch.h @@ -29,6 +29,14 @@ GIT_BEGIN_DECL typedef struct git_patch git_patch; /** + * Get the repository associated with this patch. May be NULL. + * + * @param patch the patch + * @return a pointer to the repository + */ +GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch); + +/** * Return a patch for an entry in the diff list. * * The `git_patch` is a newly created object contains the text diffs diff --git a/include/git2/refs.h b/include/git2/refs.h index c9cce2212..7ebb209b2 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -97,6 +97,9 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co * of updating does not match the one passed through `current_value` * (i.e. if the ref has changed since the user read it). * + * If `current_value` is all zeros, this function will return GIT_EMODIFIED + * if the ref already exists. + * * @param out Pointer to the newly created reference * @param repo Repository where that reference will live * @param name The name of the reference @@ -169,7 +172,7 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor * * The message for the reflog will be ignored if the reference does * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and and it does not have a reflog. + * branches) and it does not have a reflog. * * @param out Pointer to the newly created reference * @param repo Repository where that reference will live @@ -206,7 +209,7 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, * * The message for the reflog will be ignored if the reference does * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and and it does not have a reflog. + * branches) and it does not have a reflog. * * It will return GIT_EMODIFIED if the reference's value at the time * of updating does not match the one passed through `current_id` @@ -318,7 +321,7 @@ GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); * * The message for the reflog will be ignored if the reference does * not belong in the standard set (HEAD, branches and remote-tracking - * branches) and and it does not have a reflog. + * branches) and it does not have a reflog. * * @param out Pointer to the newly created reference * @param ref The reference @@ -743,10 +746,11 @@ GIT_EXTERN(int) git_reference_peel( * the characters '~', '^', ':', '\\', '?', '[', and '*', and the * sequences ".." and "@{" which have special meaning to revparse. * + * @param valid output pointer to set with validity of given reference name * @param refname name to be checked. - * @return 1 if the reference name is acceptable; 0 if it isn't + * @return 0 on success or an error code */ -GIT_EXTERN(int) git_reference_is_valid_name(const char *refname); +GIT_EXTERN(int) git_reference_name_is_valid(int *valid, const char *refname); /** * Get the reference's short name diff --git a/include/git2/remote.h b/include/git2/remote.h index 51d9c7235..5d7a5367d 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -253,6 +253,7 @@ GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, con * @param repo the repository in which to perform the change * @param remote the remote's name * @param url the url to set + * @return 0, or an error code */ GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char* url); @@ -876,8 +877,10 @@ GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *rem * @param repo the repository in which to make the change * @param remote the name of the remote * @param value the new value to take. + * @return 0, or an error code. */ GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); + /** * Retrieve the ref-prune setting * @@ -915,10 +918,11 @@ GIT_EXTERN(int) git_remote_rename( /** * Ensure the remote name is well-formed. * + * @param valid output pointer to set with validity of given remote name * @param remote_name name to be checked. - * @return 1 if the reference name is acceptable; 0 if it isn't + * @return 0 on success or an error code */ -GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); +int git_remote_name_is_valid(int *valid, const char *remote_name); /** * Delete an existing persisted remote. @@ -943,7 +947,7 @@ GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); * * This function must only be called after connecting. * - * @param out the buffern in which to store the reference name + * @param out the buffer in which to store the reference name * @param remote the remote * @return 0, GIT_ENOTFOUND if the remote does not have any references * or none of them point to HEAD's commit, or an error message. diff --git a/include/git2/repository.h b/include/git2/repository.h index 45d7962b2..45becc73d 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -219,36 +219,54 @@ GIT_EXTERN(int) git_repository_init( * * These flags configure extra behaviors to `git_repository_init_ext`. * In every case, the default behavior is the zero value (i.e. flag is - * not set). Just OR the flag values together for the `flags` parameter - * when initializing a new repo. Details of individual values are: - * - * * BARE - Create a bare repository with no working directory. - * * NO_REINIT - Return an GIT_EEXISTS error if the repo_path appears to - * already be an git repository. - * * NO_DOTGIT_DIR - Normally a "/.git/" will be appended to the repo - * path for non-bare repos (if it is not already there), but - * passing this flag prevents that behavior. - * * MKDIR - Make the repo_path (and workdir_path) as needed. Init is - * always willing to create the ".git" directory even without this - * flag. This flag tells init to create the trailing component of - * the repo and workdir paths as needed. - * * MKPATH - Recursively make all components of the repo and workdir - * paths as necessary. - * * EXTERNAL_TEMPLATE - libgit2 normally uses internal templates to - * initialize a new repo. This flags enables external templates, - * looking the "template_path" from the options if set, or the - * `init.templatedir` global config if not, or falling back on - * "/usr/share/git-core/templates" if it exists. - * * GIT_REPOSITORY_INIT_RELATIVE_GITLINK - If an alternate workdir is - * specified, use relative paths for the gitdir and core.worktree. + * not set). Just OR the flag values together for the `flags` parameter + * when initializing a new repo. */ typedef enum { + /** + * Create a bare repository with no working directory. + */ GIT_REPOSITORY_INIT_BARE = (1u << 0), + + /** + * Return an GIT_EEXISTS error if the repo_path appears to already be + * an git repository. + */ GIT_REPOSITORY_INIT_NO_REINIT = (1u << 1), + + /** + * Normally a "/.git/" will be appended to the repo path for + * non-bare repos (if it is not already there), but passing this flag + * prevents that behavior. + */ GIT_REPOSITORY_INIT_NO_DOTGIT_DIR = (1u << 2), + + /** + * Make the repo_path (and workdir_path) as needed. Init is always willing + * to create the ".git" directory even without this flag. This flag tells + * init to create the trailing component of the repo and workdir paths + * as needed. + */ GIT_REPOSITORY_INIT_MKDIR = (1u << 3), + + /** + * Recursively make all components of the repo and workdir paths as + * necessary. + */ GIT_REPOSITORY_INIT_MKPATH = (1u << 4), + + /** + * libgit2 normally uses internal templates to initialize a new repo. + * This flags enables external templates, looking the "template_path" from + * the options if set, or the `init.templatedir` global config if not, + * or falling back on "/usr/share/git-core/templates" if it exists. + */ GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE = (1u << 5), + + /** + * If an alternate workdir is specified, use relative paths for the gitdir + * and core.worktree. + */ GIT_REPOSITORY_INIT_RELATIVE_GITLINK = (1u << 6), } git_repository_init_flag_t; @@ -257,17 +275,23 @@ typedef enum { * * Set the mode field of the `git_repository_init_options` structure * either to the custom mode that you would like, or to one of the - * following modes: - * - * * SHARED_UMASK - Use permissions configured by umask - the default. - * * SHARED_GROUP - Use "--shared=group" behavior, chmod'ing the new repo - * to be group writable and "g+sx" for sticky group assignment. - * * SHARED_ALL - Use "--shared=all" behavior, adding world readability. - * * Anything else - Set to custom value. + * defined modes. */ typedef enum { + /** + * Use permissions configured by umask - the default. + */ GIT_REPOSITORY_INIT_SHARED_UMASK = 0, + + /** + * Use "--shared=group" behavior, chmod'ing the new repo to be group + * writable and "g+sx" for sticky group assignment. + */ GIT_REPOSITORY_INIT_SHARED_GROUP = 0002775, + + /** + * Use "--shared=all" behavior, adding world readability. + */ GIT_REPOSITORY_INIT_SHARED_ALL = 0002777, } git_repository_init_mode_t; @@ -275,38 +299,57 @@ typedef enum { * Extended options structure for `git_repository_init_ext`. * * This contains extra options for `git_repository_init_ext` that enable - * additional initialization features. The fields are: - * - * * flags - Combination of GIT_REPOSITORY_INIT flags above. - * * mode - Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... - * constants above, or to a custom value that you would like. - * * workdir_path - The path to the working dir or NULL for default (i.e. - * repo_path parent on non-bare repos). IF THIS IS RELATIVE PATH, - * IT WILL BE EVALUATED RELATIVE TO THE REPO_PATH. If this is not - * the "natural" working directory, a .git gitlink file will be - * created here linking to the repo_path. - * * description - If set, this will be used to initialize the "description" - * file in the repository, instead of using the template content. - * * template_path - When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, - * this contains the path to use for the template directory. If - * this is NULL, the config or default directory options will be - * used instead. - * * initial_head - The name of the head to point HEAD at. If NULL, then - * this will be treated as "master" and the HEAD ref will be set - * to "refs/heads/master". If this begins with "refs/" it will be - * used verbatim; otherwise "refs/heads/" will be prefixed. - * * origin_url - If this is non-NULL, then after the rest of the - * repository initialization is completed, an "origin" remote - * will be added pointing to this URL. + * additional initialization features. */ typedef struct { unsigned int version; + + /** + * Combination of GIT_REPOSITORY_INIT flags above. + */ uint32_t flags; + + /** + * Set to one of the standard GIT_REPOSITORY_INIT_SHARED_... constants + * above, or to a custom value that you would like. + */ uint32_t mode; + + /** + * The path to the working dir or NULL for default (i.e. repo_path parent + * on non-bare repos). IF THIS IS RELATIVE PATH, IT WILL BE EVALUATED + * RELATIVE TO THE REPO_PATH. If this is not the "natural" working + * directory, a .git gitlink file will be created here linking to the + * repo_path. + */ const char *workdir_path; + + /** + * If set, this will be used to initialize the "description" file in the + * repository, instead of using the template content. + */ const char *description; + + /** + * When GIT_REPOSITORY_INIT_EXTERNAL_TEMPLATE is set, this contains + * the path to use for the template directory. If this is NULL, the config + * or default directory options will be used instead. + */ const char *template_path; + + /** + * The name of the head to point HEAD at. If NULL, then this will be + * treated as "master" and the HEAD ref will be set to "refs/heads/master". + * If this begins with "refs/" it will be used verbatim; + * otherwise "refs/heads/" will be prefixed. + */ const char *initial_head; + + /** + * If this is non-NULL, then after the rest of the repository + * initialization is completed, an "origin" remote will be added + * pointing to this URL. + */ const char *origin_url; } git_repository_init_options; @@ -481,10 +524,11 @@ GIT_EXTERN(const char *) git_repository_path(const git_repository *repo); GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo); /** - * Get the path of the shared common directory for this repository - * - * If the repository is bare is not a worktree, the git directory - * path is returned. + * Get the path of the shared common directory for this repository. + * + * If the repository is bare, it is the root directory for the repository. + * If the repository is a worktree, it is the parent repo's gitdir. + * Otherwise, it is the gitdir. * * @param repo A repository object * @return the path to the common dir diff --git a/include/git2/revparse.h b/include/git2/revparse.h index d170e1621..e14ddee96 100644 --- a/include/git2/revparse.h +++ b/include/git2/revparse.h @@ -70,12 +70,12 @@ GIT_EXTERN(int) git_revparse_ext( */ typedef enum { /** The spec targeted a single object. */ - GIT_REVPARSE_SINGLE = 1 << 0, + GIT_REVSPEC_SINGLE = 1 << 0, /** The spec targeted a range of commits. */ - GIT_REVPARSE_RANGE = 1 << 1, + GIT_REVSPEC_RANGE = 1 << 1, /** The spec used the '...' operator, which invokes special semantics. */ - GIT_REVPARSE_MERGE_BASE = 1 << 2, -} git_revparse_mode_t; + GIT_REVSPEC_MERGE_BASE = 1 << 2, +} git_revspec_t; /** * Git Revision Spec: output of a `git_revparse` operation @@ -85,7 +85,7 @@ typedef struct { git_object *from; /** The right element of the revspec; must be freed by the user */ git_object *to; - /** The intent of the revspec (i.e. `git_revparse_mode_t` flags) */ + /** The intent of the revspec (i.e. `git_revspec_mode_t` flags) */ unsigned int flags; } git_revspec; diff --git a/include/git2/status.h b/include/git2/status.h index 9693cc478..543e3faa8 100644 --- a/include/git2/status.h +++ b/include/git2/status.h @@ -69,89 +69,141 @@ typedef int GIT_CALLBACK(git_status_cb)( * With `git_status_foreach_ext`, this will control which changes get * callbacks. With `git_status_list_new`, these will control which * changes are included in the list. - * - * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default. This roughly - * matches `git status --porcelain` regarding which files are - * included and in what order. - * - GIT_STATUS_SHOW_INDEX_ONLY only gives status based on HEAD to index - * comparison, not looking at working directory changes. - * - GIT_STATUS_SHOW_WORKDIR_ONLY only gives status based on index to - * working directory comparison, not comparing the index to the HEAD. */ typedef enum { + /** + * The default. This roughly matches `git status --porcelain` regarding + * which files are included and in what order. + */ GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0, + + /** + * Only gives status based on HEAD to index comparison, not looking at + * working directory changes. + */ GIT_STATUS_SHOW_INDEX_ONLY = 1, + + /** + * Only gives status based on index to working directory comparison, + * not comparing the index to the HEAD. + */ GIT_STATUS_SHOW_WORKDIR_ONLY = 2, } git_status_show_t; /** * Flags to control status callbacks * - * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made - * on untracked files. These will only be made if the workdir files are - * included in the status "show" option. - * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files get callbacks. - * Again, these callbacks will only be made if the workdir files are - * included in the status "show" option. - * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be - * made even on unmodified files. - * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that submodules should be - * skipped. This only applies if there are no pending typechanges to - * the submodule (either from or to another type). - * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that all files in - * untracked directories should be included. Normally if an entire - * directory is new, then just the top-level directory is included (with - * a trailing slash on the entry name). This flag says to include all - * of the individual files in the directory instead. - * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path - * should be treated as a literal path, and not as a pathspec pattern. - * - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS indicates that the contents of - * ignored directories should be included in the status. This is like - * doing `git ls-files -o -i --exclude-standard` with core git. - * - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX indicates that rename detection - * should be processed between the head and the index and enables - * the GIT_STATUS_INDEX_RENAMED as a possible status flag. - * - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR indicates that rename - * detection should be run between the index and the working directory - * and enabled GIT_STATUS_WT_RENAMED as a possible status flag. - * - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY overrides the native case - * sensitivity for the file system and forces the output to be in - * case-sensitive order - * - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY overrides the native case - * sensitivity for the file system and forces the output to be in - * case-insensitive order - * - GIT_STATUS_OPT_RENAMES_FROM_REWRITES indicates that rename detection - * should include rewritten files - * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of - * doing a "soft" index reload (i.e. reloading the index data if the - * file on disk has been modified outside libgit2). - * - GIT_STATUS_OPT_UPDATE_INDEX tells libgit2 to refresh the stat cache - * in the index for files that are unchanged but have out of date stat - * information in the index. It will result in less work being done on - * subsequent calls to get status. This is mutually exclusive with the - * NO_REFRESH option. - * * Calling `git_status_foreach()` is like calling the extended version * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED, * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS. Those options are bundled * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline. */ typedef enum { + /** + * Says that callbacks should be made on untracked files. + * These will only be made if the workdir files are included in the status + * "show" option. + */ GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0), + + /** + * Says that ignored files get callbacks. + * Again, these callbacks will only be made if the workdir files are + * included in the status "show" option. + */ GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1), + + /** + * Indicates that callback should be made even on unmodified files. + */ GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2), + + /** + * Indicates that submodules should be skipped. + * This only applies if there are no pending typechanges to the submodule + * (either from or to another type). + */ GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3), + + /** + * Indicates that all files in untracked directories should be included. + * Normally if an entire directory is new, then just the top-level + * directory is included (with a trailing slash on the entry name). + * This flag says to include all of the individual files in the directory + * instead. + */ GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4), + + /** + * Indicates that the given path should be treated as a literal path, + * and not as a pathspec pattern. + */ GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5), + + /** + * Indicates that the contents of ignored directories should be included + * in the status. This is like doing `git ls-files -o -i --exclude-standard` + * with core git. + */ GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6), + + /** + * Indicates that rename detection should be processed between the head and + * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status + * flag. + */ GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7), + + /** + * Indicates that rename detection should be run between the index and the + * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status + * flag. + */ GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8), + + /** + * Overrides the native case sensitivity for the file system and forces + * the output to be in case-sensitive order. + */ GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9), + + /** + * Overrides the native case sensitivity for the file system and forces + * the output to be in case-insensitive order. + */ GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10), + + /** + * Iindicates that rename detection should include rewritten files. + */ GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11), + + /** + * Bypasses the default status behavior of doing a "soft" index reload + * (i.e. reloading the index data if the file on disk has been modified + * outside libgit2). + */ GIT_STATUS_OPT_NO_REFRESH = (1u << 12), + + /** + * Tells libgit2 to refresh the stat cache in the index for files that are + * unchanged but have out of date stat einformation in the index. + * It will result in less work being done on subsequent calls to get status. + * This is mutually exclusive with the NO_REFRESH option. + */ GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13), + + /** + * Normally files that cannot be opened or read are ignored as + * these are often transient files; this option will return + * unreadable files as `GIT_STATUS_WT_UNREADABLE`. + */ GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14), + + /** + * Unreadable files will be detected and given the status + * untracked instead of unreadable. + */ GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15), } git_status_opt_t; @@ -168,7 +220,10 @@ typedef enum { * */ typedef struct { - unsigned int version; /**< The version */ + /** + * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. + */ + unsigned int version; /** * The `show` value is one of the `git_status_show_t` constants that @@ -177,21 +232,22 @@ typedef struct { git_status_show_t show; /** - * The `flags` value is an OR'ed combination of the `git_status_opt_t` - * values above. + * The `flags` value is an OR'ed combination of the + * `git_status_opt_t` values above. */ unsigned int flags; /** * The `pathspec` is an array of path patterns to match (using - * fnmatch-style matching), or just an array of paths to match exactly if - * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags. + * fnmatch-style matching), or just an array of paths to match + * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified + * in the flags. */ git_strarray pathspec; /** - * The `baseline` is the tree to be used for comparison to the working directory - * and index; defaults to HEAD. + * The `baseline` is the tree to be used for comparison to the + * working directory and index; defaults to HEAD. */ git_tree *baseline; } git_status_options; diff --git a/include/git2/strarray.h b/include/git2/strarray.h index 86fa25f3f..0f657e6c5 100644 --- a/include/git2/strarray.h +++ b/include/git2/strarray.h @@ -25,20 +25,16 @@ typedef struct git_strarray { } git_strarray; /** - * Close a string array object - * - * 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. + * Free the strings contained in a string array. This method should + * be called on `git_strarray` objects that were provided by the + * library. Not doing so, will result in a memory leak. * * 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). + * never allocate that object directly itself. * - * @param array git_strarray from which to free string data + * @param array The git_strarray that contains strings to free */ -GIT_EXTERN(void) git_strarray_free(git_strarray *array); +GIT_EXTERN(void) git_strarray_dispose(git_strarray *array); /** * Copy a string array object from source to target. diff --git a/include/git2/submodule.h b/include/git2/submodule.h index bedd76d6a..29d8bc1ce 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -224,6 +224,15 @@ GIT_EXTERN(int) git_submodule_lookup( const char *name); /** + * Create an in-memory copy of a submodule. The copy must be explicitly + * free'd or it will leak. + * + * @param out Pointer to store the copy of the submodule. + * @param source Original submodule to copy. + */ +GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source); + +/** * Release a submodule * * @param submodule Submodule object diff --git a/include/git2/sys/commit_graph.h b/include/git2/sys/commit_graph.h new file mode 100644 index 000000000..038c9b739 --- /dev/null +++ b/include/git2/sys/commit_graph.h @@ -0,0 +1,45 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_sys_git_commit_graph_h__ +#define INCLUDE_sys_git_commit_graph_h__ + +#include "git2/common.h" +#include "git2/types.h" + +/** + * @file git2/sys/commit_graph.h + * @brief Git commit-graph + * @defgroup git_commit_graph Git commit-graph APIs + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Opens a `git_commit_graph` from a path to an objects directory. + * + * This finds, opens, and validates the `commit-graph` file. + * + * @param cgraph_out the `git_commit_graph` struct to initialize. + * @param objects_dir the path to a git objects directory. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_commit_graph_open(git_commit_graph **cgraph_out, const char *objects_dir); + +/** + * Frees commit-graph data. This should only be called when memory allocated + * using `git_commit_graph_open` is not returned to libgit2 because it was not + * associated with the ODB through a successful call to + * `git_odb_set_commit_graph`. + * + * @param cgraph the commit-graph object to free. If NULL, no action is taken. + */ +GIT_EXTERN(void) git_commit_graph_free(git_commit_graph *cgraph); + +GIT_END_DECL + +#endif diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h index 8e22c4f02..c31e26d95 100644 --- a/include/git2/sys/refdb_backend.h +++ b/include/git2/sys/refdb_backend.h @@ -64,6 +64,12 @@ struct git_refdb_backend { * Queries the refdb backend for the existence of a reference. * * A refdb implementation must provide this function. + * + * @arg exists The implementation shall set this to `0` if a ref does + * not exist, otherwise to `1`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, a negative error value code. */ int GIT_CALLBACK(exists)( int *exists, @@ -74,6 +80,13 @@ struct git_refdb_backend { * Queries the refdb backend for a given reference. * * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference, if it could be found, otherwise to `NULL`. + * @arg ref_name The reference's name that should be checked for + * existence. + * @return `0` on success, `GIT_ENOTFOUND` if the reference does + * exist, otherwise a negative error code. */ int GIT_CALLBACK(lookup)( git_reference **out, @@ -84,6 +97,16 @@ struct git_refdb_backend { * Allocate an iterator object for the backend. * * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the allocated + * reference iterator. A custom structure may be used with an + * embedded `git_reference_iterator` structure. Both `next` + * and `next_name` functions of `git_reference_iterator` need + * to be populated. + * @arg glob A pattern to filter references by. If given, the iterator + * shall only return references that match the glob when + * passed to `wildmatch`. + * @return `0` on success, otherwise a negative error code. */ int GIT_CALLBACK(iterator)( git_reference_iterator **iter, @@ -94,6 +117,27 @@ struct git_refdb_backend { * Writes the given reference to the refdb. * * A refdb implementation must provide this function. + * + * @arg ref The reference to persist. May either be a symbolic or + * direct reference. + * @arg force Whether to write the reference if a reference with the + * same name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @arg old If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. If both `old` + * and `old_target` are `NULL`, then the reference should not + * exist at the point of writing. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. If both `old` and + * `old_target` are `NULL`, then the reference should + * not exist at the point of writing. + * @return `0` on success, otherwise a negative error code. */ int GIT_CALLBACK(write)(git_refdb_backend *backend, const git_reference *ref, int force, @@ -104,6 +148,18 @@ struct git_refdb_backend { * Rename a reference in the refdb. * * A refdb implementation must provide this function. + * + * @arg out The implementation shall set this to the newly created + * reference or `NULL` on error. + * @arg old_name The current name of the reference that is to be renamed. + * @arg new_name The new name that the old reference shall be renamed to. + * @arg force Whether to write the reference if a reference with the + * target name already exists. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry. + * @return `0` on success, otherwise a negative error code. */ int GIT_CALLBACK(rename)( git_reference **out, git_refdb_backend *backend, @@ -116,6 +172,16 @@ struct git_refdb_backend { * If it exists, its reflog should be deleted as well. * * A refdb implementation must provide this function. + * + * @arg ref_name The name of the reference name that shall be deleted. + * @arg old_id If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the reference is currently at + * the given OID before writing the new value. + * @arg old_target If not `NULL` and `force` is not set, then the + * implementation needs to ensure that the symbolic + * reference is currently at the given target before + * writing the new value. + * @return `0` on success, otherwise a negative error code. */ int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target); @@ -127,13 +193,21 @@ struct git_refdb_backend { * * A refdb implementation may provide this function; if it is not * provided, nothing will be done. + * + * @return `0` on success a negative error code otherwise */ int GIT_CALLBACK(compress)(git_refdb_backend *backend); /** * Query whether a particular reference has a log (may be empty) * + * Shall return 1 if it has a reflog, 0 it it doesn't and negative in + * case an error occurred. + * * A refdb implementation must provide this function. + * + * @return `0` on success, `1` if the reflog for the given reference + * exists, a negative error code otherwise */ int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname); @@ -142,6 +216,8 @@ struct git_refdb_backend { * will be appended to on writes. * * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname); @@ -157,6 +233,8 @@ struct git_refdb_backend { * Read the reflog for the given reference name. * * A refdb implementation must provide this function. + * + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name); @@ -164,6 +242,11 @@ struct git_refdb_backend { * Write a reflog to disk. * * A refdb implementation must provide this function. + * + * @arg reflog The complete reference log for a given reference. Note + * that this may contain entries that have already been + * written to disk. + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog); @@ -171,6 +254,10 @@ struct git_refdb_backend { * Rename a reflog. * * A refdb implementation must provide this function. + * + * @arg old_name The name of old reference whose reflog shall be renamed from. + * @arg new_name The name of new reference whose reflog shall be renamed to. + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name); @@ -178,16 +265,22 @@ struct git_refdb_backend { * Remove a reflog. * * A refdb implementation must provide this function. + * + * @arg name The name of the reference whose reflog shall be deleted. + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name); /** * Lock a reference. * - * The opaque parameter will be passed to the unlock function. - * * A refdb implementation may provide this function; if it is not * provided, the transaction API will fail to work. + * + * @arg payload_out Opaque parameter that will be passed verbosely to + * `unlock`. + * @arg refname Reference that shall be locked. + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname); @@ -200,6 +293,20 @@ struct git_refdb_backend { * * A refdb implementation must provide this function if a `lock` * implementation is provided. + * + * @arg payload The payload returned by `lock`. + * @arg success `1` if a reference should be updated, `2` if + * a reference should be deleted, `0` if the lock must be + * discarded. + * @arg update_reflog `1` in case the reflog should be updated, `0` + * otherwise. + * @arg ref The reference which should be unlocked. + * @arg who The person updating the reference. Shall be used to create + * a reflog entry in case `update_reflog` is set. + * @arg message The message detailing what kind of reference update is + * performed. Shall be used to create a reflog entry in + * case `update_reflog` is set. + * @return `0` on success, a negative error code otherwise */ int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog, const git_reference *ref, const git_signature *sig, const char *message); diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h index 6cee42f54..fee34544f 100644 --- a/include/git2/sys/transport.h +++ b/include/git2/sys/transport.h @@ -9,6 +9,7 @@ #define INCLUDE_sys_git_transport_h #include "git2/net.h" +#include "git2/transport.h" #include "git2/types.h" #include "git2/strarray.h" #include "git2/proxy.h" diff --git a/include/git2/tag.h b/include/git2/tag.h index 4e5fe1db1..a3921369d 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -365,6 +365,18 @@ GIT_EXTERN(int) git_tag_peel( */ GIT_EXTERN(int) git_tag_dup(git_tag **out, git_tag *source); +/** + * Determine whether a tag name is valid, meaning that (when prefixed + * with `refs/tags/`) that it is a valid reference name, and that any + * additional tag name restrictions are imposed (eg, it cannot start + * with a `-`). + * + * @param valid output pointer to set with validity of given tag name + * @param name a tag name to test + * @return 0 on success or an error code + */ +GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name); + /** @} */ GIT_END_DECL #endif diff --git a/include/git2/transport.h b/include/git2/transport.h index fc99ce8f3..5a27de9a8 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -23,7 +23,7 @@ GIT_BEGIN_DECL /** - * Callback for messages recieved by the transport. + * Callback for messages received by the transport. * * Return a negative value to cancel the network operation. * diff --git a/include/git2/tree.h b/include/git2/tree.h index 1a8e155fc..f2289fc7e 100644 --- a/include/git2/tree.h +++ b/include/git2/tree.h @@ -334,6 +334,7 @@ GIT_EXTERN(int) git_treebuilder_insert( * * @param bld Tree builder * @param filename Filename of the entry to remove + * @return 0 or an error code */ GIT_EXTERN(int) git_treebuilder_remove( git_treebuilder *bld, const char *filename); @@ -378,20 +379,6 @@ GIT_EXTERN(int) git_treebuilder_filter( GIT_EXTERN(int) git_treebuilder_write( git_oid *id, git_treebuilder *bld); -/** - * Write the contents of the tree builder as a tree object - * using a shared git_buf. - * - * @see git_treebuilder_write - * - * @param oid Pointer to store the OID of the newly written tree - * @param bld Tree builder to write - * @param tree Shared buffer for writing the tree. Will be grown as necessary. - * @return 0 or an error code - */ -GIT_EXTERN(int) git_treebuilder_write_with_buffer( - git_oid *oid, git_treebuilder *bld, git_buf *tree); - /** Callback for the tree traversal method */ typedef int GIT_CALLBACK(git_treewalk_cb)( const char *root, const git_tree_entry *entry, void *payload); @@ -477,6 +464,7 @@ typedef struct { * @param baseline the tree to base these changes on * @param nupdates the number of elements in the update list * @param updates the list of updates to perform + * @return 0 or an error code */ GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); diff --git a/include/git2/types.h b/include/git2/types.h index ade0c7d32..562eb8e5f 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -102,6 +102,9 @@ typedef struct git_refdb git_refdb; /** A custom backend for refs */ typedef struct git_refdb_backend git_refdb_backend; +/** A git commit-graph */ +typedef struct git_commit_graph git_commit_graph; + /** * Representation of an existing git repository, * including all its object contents diff --git a/include/git2/version.h b/include/git2/version.h index 148808ca0..c1020bbea 100644 --- a/include/git2/version.h +++ b/include/git2/version.h @@ -7,12 +7,12 @@ #ifndef INCLUDE_git_version_h__ #define INCLUDE_git_version_h__ -#define LIBGIT2_VERSION "0.28.0" -#define LIBGIT2_VER_MAJOR 0 -#define LIBGIT2_VER_MINOR 28 +#define LIBGIT2_VERSION "1.1.0" +#define LIBGIT2_VER_MAJOR 1 +#define LIBGIT2_VER_MINOR 1 #define LIBGIT2_VER_REVISION 0 #define LIBGIT2_VER_PATCH 0 -#define LIBGIT2_SOVERSION 28 +#define LIBGIT2_SOVERSION "1.1" #endif diff --git a/include/git2/worktree.h b/include/git2/worktree.h index 049511da1..23084d8cd 100644 --- a/include/git2/worktree.h +++ b/include/git2/worktree.h @@ -198,6 +198,7 @@ typedef enum { typedef struct git_worktree_prune_options { unsigned int version; + /** A combination of `git_worktree_prune_t` */ uint32_t flags; } git_worktree_prune_options; |