diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2021-07-30 08:52:37 -0400 |
---|---|---|
committer | Edward Thomson <ethomson@edwardthomson.com> | 2021-07-30 08:52:37 -0400 |
commit | 47dd9f47972f0885b288a950714568c98f16a79e (patch) | |
tree | cf58b845b824eb62461efd0d98ba623935d18aee | |
parent | 708d9336bb677320e975936e251c7eacf5661510 (diff) | |
parent | 346f15ba8987b7ed24990d1d70f2724e4424500b (diff) | |
download | libgit2-47dd9f47972f0885b288a950714568c98f16a79e.tar.gz |
Merge branch 'pr/5940'
-rw-r--r-- | include/git2/blame.h | 135 | ||||
-rw-r--r-- | include/git2/checkout.h | 34 | ||||
-rw-r--r-- | include/git2/diff.h | 49 | ||||
-rw-r--r-- | include/git2/remote.h | 5 | ||||
-rw-r--r-- | include/git2/status.h | 174 | ||||
-rw-r--r-- | include/git2/worktree.h | 1 |
6 files changed, 265 insertions, 133 deletions
diff --git a/include/git2/blame.h b/include/git2/blame.h index f42c81552..d193ce14e 100644 --- a/include/git2/blame.h +++ b/include/git2/blame.h @@ -26,27 +26,52 @@ 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; @@ -63,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. @@ -108,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/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/diff.h b/include/git2/diff.h index c63d93dc8..9497793c3 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -241,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; diff --git a/include/git2/remote.h b/include/git2/remote.h index b82bd250b..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 * @@ -944,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/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/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; |