| /* |
| * 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_pathspec_h__ |
| #define INCLUDE_git_pathspec_h__ |
| |
| #include "common.h" |
| #include "types.h" |
| #include "strarray.h" |
| #include "diff.h" |
| |
| GIT_BEGIN_DECL |
| |
| /** |
| * Compiled pathspec |
| */ |
| typedef struct git_pathspec git_pathspec; |
| |
| /** |
| * List of filenames matching a pathspec |
| */ |
| typedef struct git_pathspec_match_list git_pathspec_match_list; |
| |
| /** |
| * Options controlling how pathspec match should be executed |
| * |
| * - GIT_PATHSPEC_IGNORE_CASE forces match to ignore case; otherwise |
| * match will use native case sensitivity of platform filesystem |
| * - GIT_PATHSPEC_USE_CASE forces case sensitive match; otherwise |
| * match will use native case sensitivity of platform filesystem |
| * - GIT_PATHSPEC_NO_GLOB disables glob patterns and just uses simple |
| * string comparison for matching |
| * - GIT_PATHSPEC_NO_MATCH_ERROR means the match functions return error |
| * code GIT_ENOTFOUND if no matches are found; otherwise no matches is |
| * still success (return 0) but `git_pathspec_match_list_entrycount` |
| * will indicate 0 matches. |
| * - GIT_PATHSPEC_FIND_FAILURES means that the `git_pathspec_match_list` |
| * should track which patterns matched which files so that at the end of |
| * the match we can identify patterns that did not match any files. |
| * - GIT_PATHSPEC_FAILURES_ONLY means that the `git_pathspec_match_list` |
| * does not need to keep the actual matching filenames. Use this to |
| * just test if there were any matches at all or in combination with |
| * GIT_PATHSPEC_FIND_FAILURES to validate a pathspec. |
| */ |
| typedef enum { |
| GIT_PATHSPEC_DEFAULT = 0, |
| GIT_PATHSPEC_IGNORE_CASE = (1u << 0), |
| GIT_PATHSPEC_USE_CASE = (1u << 1), |
| GIT_PATHSPEC_NO_GLOB = (1u << 2), |
| GIT_PATHSPEC_NO_MATCH_ERROR = (1u << 3), |
| GIT_PATHSPEC_FIND_FAILURES = (1u << 4), |
| GIT_PATHSPEC_FAILURES_ONLY = (1u << 5), |
| } git_pathspec_flag_t; |
| |
| /** |
| * Compile a pathspec |
| * |
| * @param out Output of the compiled pathspec |
| * @param pathspec A git_strarray of the paths to match |
| * @return 0 on success, <0 on failure |
| */ |
| GIT_EXTERN(int) git_pathspec_new( |
| git_pathspec **out, const git_strarray *pathspec); |
| |
| /** |
| * Free a pathspec |
| * |
| * @param ps The compiled pathspec |
| */ |
| GIT_EXTERN(void) git_pathspec_free(git_pathspec *ps); |
| |
| /** |
| * Try to match a path against a pathspec |
| * |
| * Unlike most of the other pathspec matching functions, this will not |
| * fall back on the native case-sensitivity for your platform. You must |
| * explicitly pass flags to control case sensitivity or else this will |
| * fall back on being case sensitive. |
| * |
| * @param ps The compiled pathspec |
| * @param flags Combination of git_pathspec_flag_t options to control match |
| * @param path The pathname to attempt to match |
| * @return 1 is path matches spec, 0 if it does not |
| */ |
| GIT_EXTERN(int) git_pathspec_matches_path( |
| const git_pathspec *ps, uint32_t flags, const char *path); |
| |
| /** |
| * Match a pathspec against the working directory of a repository. |
| * |
| * This matches the pathspec against the current files in the working |
| * directory of the repository. It is an error to invoke this on a bare |
| * repo. This handles git ignores (i.e. ignored files will not be |
| * considered to match the `pathspec` unless the file is tracked in the |
| * index). |
| * |
| * If `out` is not NULL, this returns a `git_patchspec_match_list`. That |
| * contains the list of all matched filenames (unless you pass the |
| * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of |
| * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` |
| * flag). You must call `git_pathspec_match_list_free()` on this object. |
| * |
| * @param out Output list of matches; pass NULL to just get return value |
| * @param repo The repository in which to match; bare repo is an error |
| * @param flags Combination of git_pathspec_flag_t options to control match |
| * @param ps Pathspec to be matched |
| * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and |
| * the GIT_PATHSPEC_NO_MATCH_ERROR flag was given |
| */ |
| GIT_EXTERN(int) git_pathspec_match_workdir( |
| git_pathspec_match_list **out, |
| git_repository *repo, |
| uint32_t flags, |
| git_pathspec *ps); |
| |
| /** |
| * Match a pathspec against entries in an index. |
| * |
| * This matches the pathspec against the files in the repository index. |
| * |
| * NOTE: At the moment, the case sensitivity of this match is controlled |
| * by the current case-sensitivity of the index object itself and the |
| * USE_CASE and IGNORE_CASE flags will have no effect. This behavior will |
| * be corrected in a future release. |
| * |
| * If `out` is not NULL, this returns a `git_patchspec_match_list`. That |
| * contains the list of all matched filenames (unless you pass the |
| * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of |
| * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` |
| * flag). You must call `git_pathspec_match_list_free()` on this object. |
| * |
| * @param out Output list of matches; pass NULL to just get return value |
| * @param index The index to match against |
| * @param flags Combination of git_pathspec_flag_t options to control match |
| * @param ps Pathspec to be matched |
| * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and |
| * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used |
| */ |
| GIT_EXTERN(int) git_pathspec_match_index( |
| git_pathspec_match_list **out, |
| git_index *index, |
| uint32_t flags, |
| git_pathspec *ps); |
| |
| /** |
| * Match a pathspec against files in a tree. |
| * |
| * This matches the pathspec against the files in the given tree. |
| * |
| * If `out` is not NULL, this returns a `git_patchspec_match_list`. That |
| * contains the list of all matched filenames (unless you pass the |
| * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of |
| * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` |
| * flag). You must call `git_pathspec_match_list_free()` on this object. |
| * |
| * @param out Output list of matches; pass NULL to just get return value |
| * @param tree The root-level tree to match against |
| * @param flags Combination of git_pathspec_flag_t options to control match |
| * @param ps Pathspec to be matched |
| * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and |
| * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used |
| */ |
| GIT_EXTERN(int) git_pathspec_match_tree( |
| git_pathspec_match_list **out, |
| git_tree *tree, |
| uint32_t flags, |
| git_pathspec *ps); |
| |
| /** |
| * Match a pathspec against files in a diff list. |
| * |
| * This matches the pathspec against the files in the given diff list. |
| * |
| * If `out` is not NULL, this returns a `git_patchspec_match_list`. That |
| * contains the list of all matched filenames (unless you pass the |
| * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of |
| * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES` |
| * flag). You must call `git_pathspec_match_list_free()` on this object. |
| * |
| * @param out Output list of matches; pass NULL to just get return value |
| * @param diff A generated diff list |
| * @param flags Combination of git_pathspec_flag_t options to control match |
| * @param ps Pathspec to be matched |
| * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and |
| * the GIT_PATHSPEC_NO_MATCH_ERROR flag is used |
| */ |
| GIT_EXTERN(int) git_pathspec_match_diff( |
| git_pathspec_match_list **out, |
| git_diff *diff, |
| uint32_t flags, |
| git_pathspec *ps); |
| |
| /** |
| * Free memory associates with a git_pathspec_match_list |
| * |
| * @param m The git_pathspec_match_list to be freed |
| */ |
| GIT_EXTERN(void) git_pathspec_match_list_free(git_pathspec_match_list *m); |
| |
| /** |
| * Get the number of items in a match list. |
| * |
| * @param m The git_pathspec_match_list object |
| * @return Number of items in match list |
| */ |
| GIT_EXTERN(size_t) git_pathspec_match_list_entrycount( |
| const git_pathspec_match_list *m); |
| |
| /** |
| * Get a matching filename by position. |
| * |
| * This routine cannot be used if the match list was generated by |
| * `git_pathspec_match_diff`. If so, it will always return NULL. |
| * |
| * @param m The git_pathspec_match_list object |
| * @param pos The index into the list |
| * @return The filename of the match |
| */ |
| GIT_EXTERN(const char *) git_pathspec_match_list_entry( |
| const git_pathspec_match_list *m, size_t pos); |
| |
| /** |
| * Get a matching diff delta by position. |
| * |
| * This routine can only be used if the match list was generated by |
| * `git_pathspec_match_diff`. Otherwise it will always return NULL. |
| * |
| * @param m The git_pathspec_match_list object |
| * @param pos The index into the list |
| * @return The filename of the match |
| */ |
| GIT_EXTERN(const git_diff_delta *) git_pathspec_match_list_diff_entry( |
| const git_pathspec_match_list *m, size_t pos); |
| |
| /** |
| * Get the number of pathspec items that did not match. |
| * |
| * This will be zero unless you passed GIT_PATHSPEC_FIND_FAILURES when |
| * generating the git_pathspec_match_list. |
| * |
| * @param m The git_pathspec_match_list object |
| * @return Number of items in original pathspec that had no matches |
| */ |
| GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount( |
| const git_pathspec_match_list *m); |
| |
| /** |
| * Get an original pathspec string that had no matches. |
| * |
| * This will be return NULL for positions out of range. |
| * |
| * @param m The git_pathspec_match_list object |
| * @param pos The index into the failed items |
| * @return The pathspec pattern that didn't match anything |
| */ |
| GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry( |
| const git_pathspec_match_list *m, size_t pos); |
| |
| GIT_END_DECL |
| #endif |