diff options
Diffstat (limited to '')
| -rw-r--r-- | include/git2/status.h | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/include/git2/status.h b/include/git2/status.h new file mode 100644 index 0000000..bb28e87 --- /dev/null +++ b/include/git2/status.h @@ -0,0 +1,452 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_status_h__ +#define INCLUDE_git_status_h__ + +#include "common.h" +#include "types.h" +#include "strarray.h" +#include "diff.h" + +/** + * @file git2/status.h + * @brief Git file status routines + * @defgroup git_status Git file status routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Status flags for a single file. + * + * A combination of these values will be returned to indicate the status of + * a file. Status compares the working directory, the index, and the + * current HEAD of the repository. The `GIT_STATUS_INDEX` set of flags + * represents the status of file in the index relative to the HEAD, and the + * `GIT_STATUS_WT` set of flags represent the status of the file in the + * working directory relative to the index. + */ +typedef enum { + GIT_STATUS_CURRENT = 0, + + GIT_STATUS_INDEX_NEW = (1u << 0), + GIT_STATUS_INDEX_MODIFIED = (1u << 1), + GIT_STATUS_INDEX_DELETED = (1u << 2), + GIT_STATUS_INDEX_RENAMED = (1u << 3), + GIT_STATUS_INDEX_TYPECHANGE = (1u << 4), + + GIT_STATUS_WT_NEW = (1u << 7), + GIT_STATUS_WT_MODIFIED = (1u << 8), + GIT_STATUS_WT_DELETED = (1u << 9), + GIT_STATUS_WT_TYPECHANGE = (1u << 10), + GIT_STATUS_WT_RENAMED = (1u << 11), + GIT_STATUS_WT_UNREADABLE = (1u << 12), + + GIT_STATUS_IGNORED = (1u << 14), + GIT_STATUS_CONFLICTED = (1u << 15) +} git_status_t; + +/** + * Function pointer to receive status on individual files + * + * `path` is the relative path to the file from the root of the repository. + * + * `status_flags` is a combination of `git_status_t` values that apply. + * + * `payload` is the value you passed to the foreach function as payload. + */ +typedef int GIT_CALLBACK(git_status_cb)( + const char *path, unsigned int status_flags, void *payload); + +/** + * Select the files on which to report status. + * + * 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. + */ +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 + * + * 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; + +#define GIT_STATUS_OPT_DEFAULTS \ + (GIT_STATUS_OPT_INCLUDE_IGNORED | \ + GIT_STATUS_OPT_INCLUDE_UNTRACKED | \ + GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS) + +/** + * Options to control how `git_status_foreach_ext()` will issue callbacks. + * + * Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can + * use `git_status_options_init`. + * + */ +typedef struct { + /** + * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. + */ + unsigned int version; + + /** + * The `show` value is one of the `git_status_show_t` constants that + * control which files to scan and in what order. The default is + * `GIT_STATUS_SHOW_INDEX_AND_WORKDIR`. + */ + git_status_show_t show; + + /** + * The `flags` value is an OR'ed combination of the + * `git_status_opt_t` values above. The default is + * `GIT_STATUS_OPT_DEFAULTS`, which matches git's default + * behavior. + */ + 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. + */ + git_strarray pathspec; + + /** + * The `baseline` is the tree to be used for comparison to the + * working directory and index; defaults to HEAD. + */ + git_tree *baseline; + + /** + * Threshold above which similar files will be considered renames. + * This is equivalent to the -M option. Defaults to 50. + */ + uint16_t rename_threshold; +} git_status_options; + +#define GIT_STATUS_OPTIONS_VERSION 1 +#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION} + +/** + * Initialize git_status_options structure + * + * Initializes a `git_status_options` with default values. Equivalent to + * creating an instance with `GIT_STATUS_OPTIONS_INIT`. + * + * @param opts The `git_status_options` struct to initialize. + * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_status_options_init( + git_status_options *opts, + unsigned int version); + +/** + * A status entry, providing the differences between the file as it exists + * in HEAD and the index, and providing the differences between the index + * and the working directory. + * + * The `status` value provides the status flags for this file. + * + * The `head_to_index` value provides detailed information about the + * differences between the file in HEAD and the file in the index. + * + * The `index_to_workdir` value provides detailed information about the + * differences between the file in the index and the file in the + * working directory. + */ +typedef struct { + git_status_t status; + git_diff_delta *head_to_index; + git_diff_delta *index_to_workdir; +} git_status_entry; + + +/** + * Gather file statuses and run a callback for each one. + * + * The callback is passed the path of the file, the status (a combination of + * the `git_status_t` values above) and the `payload` data pointer passed + * into this function. + * + * If the callback returns a non-zero value, this function will stop looping + * and return that value to caller. + * + * @param repo A repository object + * @param callback The function to call on each file + * @param payload Pointer to pass through to callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_status_foreach( + git_repository *repo, + git_status_cb callback, + void *payload); + +/** + * Gather file status information and run callbacks as requested. + * + * This is an extended version of the `git_status_foreach()` API that + * allows for more granular control over which paths will be processed and + * in what order. See the `git_status_options` structure for details + * about the additional controls that this makes available. + * + * Note that if a `pathspec` is given in the `git_status_options` to filter + * the status, then the results from rename detection (if you enable it) may + * not be accurate. To do rename detection properly, this must be called + * with no `pathspec` so that all files can be considered. + * + * @param repo Repository object + * @param opts Status options structure + * @param callback The function to call on each file + * @param payload Pointer to pass through to callback function + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_status_foreach_ext( + git_repository *repo, + const git_status_options *opts, + git_status_cb callback, + void *payload); + +/** + * Get file status for a single file. + * + * This tries to get status for the filename that you give. If no files + * match that name (in either the HEAD, index, or working directory), this + * returns GIT_ENOTFOUND. + * + * If the name matches multiple files (for example, if the `path` names a + * directory or if running on a case- insensitive filesystem and yet the + * HEAD has two entries that both match the path), then this returns + * GIT_EAMBIGUOUS because it cannot give correct results. + * + * This does not do any sort of rename detection. Renames require a set of + * targets and because of the path filtering, there is not enough + * information to check renames correctly. To check file status with rename + * detection, there is no choice but to do a full `git_status_list_new` and + * scan through looking for the path that you are interested in. + * + * @param status_flags Output combination of git_status_t values for file + * @param repo A repository object + * @param path The exact path to retrieve status for relative to the + * repository working directory + * @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD, + * index, and work tree, GIT_EAMBIGUOUS if `path` matches multiple files + * or if it refers to a folder, and -1 on other errors. + */ +GIT_EXTERN(int) git_status_file( + unsigned int *status_flags, + git_repository *repo, + const char *path); + +/** + * Gather file status information and populate the `git_status_list`. + * + * Note that if a `pathspec` is given in the `git_status_options` to filter + * the status, then the results from rename detection (if you enable it) may + * not be accurate. To do rename detection properly, this must be called + * with no `pathspec` so that all files can be considered. + * + * @param out Pointer to store the status results in + * @param repo Repository object + * @param opts Status options structure + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_status_list_new( + git_status_list **out, + git_repository *repo, + const git_status_options *opts); + +/** + * Gets the count of status entries in this list. + * + * If there are no changes in status (at least according the options given + * when the status list was created), this can return 0. + * + * @param statuslist Existing status list object + * @return the number of status entries + */ +GIT_EXTERN(size_t) git_status_list_entrycount( + git_status_list *statuslist); + +/** + * Get a pointer to one of the entries in the status list. + * + * The entry is not modifiable and should not be freed. + * + * @param statuslist Existing status list object + * @param idx Position of the entry + * @return Pointer to the entry; NULL if out of bounds + */ +GIT_EXTERN(const git_status_entry *) git_status_byindex( + git_status_list *statuslist, + size_t idx); + +/** + * Free an existing status list + * + * @param statuslist Existing status list object + */ +GIT_EXTERN(void) git_status_list_free( + git_status_list *statuslist); + +/** + * Test if the ignore rules apply to a given file. + * + * This function checks the ignore rules to see if they would apply to the + * given file. This indicates if the file would be ignored regardless of + * whether the file is already in the index or committed to the repository. + * + * One way to think of this is if you were to do "git add ." on the + * directory containing the file, would it be added or not? + * + * @param ignored Boolean returning 0 if the file is not ignored, 1 if it is + * @param repo A repository object + * @param path The file to check ignores for, rooted at the repo's workdir. + * @return 0 if ignore rules could be processed for the file (regardless + * of whether it exists or not), or an error < 0 if they could not. + */ +GIT_EXTERN(int) git_status_should_ignore( + int *ignored, + git_repository *repo, + const char *path); + +/** @} */ +GIT_END_DECL +#endif |