From d2ce27dd494b65f54b2d110b4defd69aea976115 Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 24 Jun 2013 23:16:06 -0700 Subject: Add public API for pathspec matching This adds a new public API for compiling pathspecs and matching them against the working directory, the index, or a tree from the repository. This also reworks the pathspec internals to allow the sharing of code between the existing internal usage of pathspec matching and the new external API. While this is working and the new API is ready for discussion, I think there is still an incorrect behavior in which patterns are always matched against the full path of an entry without taking the subdirectories into account (so "s*" will match "subdir/file" even though it wouldn't with core Git). Further enhancements are coming, but this was a good place to take a functional snapshot. --- include/git2/pathspec.h | 202 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 include/git2/pathspec.h (limited to 'include/git2/pathspec.h') diff --git a/include/git2/pathspec.h b/include/git2/pathspec.h new file mode 100644 index 000000000..8122d9927 --- /dev/null +++ b/include/git2/pathspec.h @@ -0,0 +1,202 @@ +/* + * 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" + +/** + * 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 + * - GIT_PATHSPEC_USE_CASE forces case sensitive match; otherwise + * match will use native case sensitivity of platform + * - GIT_PATHSPEC_NO_GLOB disables glob patterns and just uses simple + * string comparison for matching + * - GIT_PATHSPEC_NO_MATCH_ERROR means the match function will return + * GIT_ENOTFOUND if no matches are found; otherwise it will return 0 + * for success and `git_pathspec_match_list_entrycount` will be 0. + * - GIT_PATHSPEC_FIND_FAILURES only applies to a git_pathspec_match_list; + * it means to check file names against all unmatched patterns so that + * at the end of a match we can identify patterns that did not match any + * files. + * - GIT_PATHSPEC_FAILURES_ONLY only applies to a git_pathspec_match_list; + * it means to only check for mismatches and not record matched paths. + */ +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 flags Combination of git_pathspec_flag_t values + * @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 Match flags to influence matching behavior + * @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 returns a `git_patchspec_match` object that contains the list of + * all files matching the given pathspec in the working directory of the + * repository. This handles git ignores (i.e. ignored files will not be + * considered to match the `pathspec` unless the file is tracked in the + * index). + * + * @param out Object with list of matching items + * @param repo The repository in which to match; bare repo is an error + * @param flags Options to control matching behavior + * @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_workdir( + git_pathspec_match_list **out, + git_repository *repo, + uint32_t flags, + git_pathspec *ps); + +/** + * Match a pathspec against entries in an index. + * + * This returns a `git_patchspec_match` object that contains the list of + * all files matching the given pathspec in the 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. + * + * @param out Object with list of matching items + * @param inex The index in which to match + * @param flags Options to control matching behavior + * @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 returns a `git_patchspec_match` object that contains the list of + * all files matching the given pathspec in the given tree. + * + * @param out Object with list of matching items + * @param inex The index in which to match + * @param flags Options to control matching behavior + * @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); + +/** + * 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. + * + * @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 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); + +#endif -- cgit v1.2.1 From 3e96ecf219bd9b84c3a7faec61e818766f60e0d9 Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 8 Jul 2013 09:53:24 -0700 Subject: Improve include/git2/pathspec.h docs --- include/git2/pathspec.h | 75 ++++++++++++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 29 deletions(-) (limited to 'include/git2/pathspec.h') diff --git a/include/git2/pathspec.h b/include/git2/pathspec.h index 8122d9927..6d97bb326 100644 --- a/include/git2/pathspec.h +++ b/include/git2/pathspec.h @@ -25,20 +25,22 @@ 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 + * 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 + * 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 function will return - * GIT_ENOTFOUND if no matches are found; otherwise it will return 0 - * for success and `git_pathspec_match_list_entrycount` will be 0. - * - GIT_PATHSPEC_FIND_FAILURES only applies to a git_pathspec_match_list; - * it means to check file names against all unmatched patterns so that - * at the end of a match we can identify patterns that did not match any - * files. - * - GIT_PATHSPEC_FAILURES_ONLY only applies to a git_pathspec_match_list; - * it means to only check for mismatches and not record matched paths. + * - 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, @@ -54,7 +56,6 @@ typedef enum { * Compile a pathspec * * @param out Output of the compiled pathspec - * @param flags Combination of git_pathspec_flag_t values * @param pathspec A git_strarray of the paths to match * @return 0 on success, <0 on failure */ @@ -77,7 +78,7 @@ GIT_EXTERN(void) git_pathspec_free(git_pathspec *ps); * fall back on being case sensitive. * * @param ps The compiled pathspec - * @param flags Match flags to influence matching behavior + * @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 */ @@ -87,18 +88,24 @@ GIT_EXTERN(int) git_pathspec_matches_path( /** * Match a pathspec against the working directory of a repository. * - * This returns a `git_patchspec_match` object that contains the list of - * all files matching the given pathspec in the working directory of the - * repository. This handles git ignores (i.e. ignored files will not be + * 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). * - * @param out Object with list of matching items + * 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 Options to control matching behavior + * @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 + * the GIT_PATHSPEC_NO_MATCH_ERROR flag was given */ GIT_EXTERN(int) git_pathspec_match_workdir( git_pathspec_match_list **out, @@ -109,17 +116,22 @@ GIT_EXTERN(int) git_pathspec_match_workdir( /** * Match a pathspec against entries in an index. * - * This returns a `git_patchspec_match` object that contains the list of - * all files matching the given pathspec in the 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. * - * @param out Object with list of matching items - * @param inex The index in which to match - * @param flags Options to control matching behavior + * 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 @@ -133,12 +145,17 @@ GIT_EXTERN(int) git_pathspec_match_index( /** * Match a pathspec against files in a tree. * - * This returns a `git_patchspec_match` object that contains the list of - * all files matching the given pathspec in the given 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 Object with list of matching items - * @param inex The index in which to match - * @param flags Options to control matching behavior + * @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 -- cgit v1.2.1 From 2b672d5b646edf94ae315a9f968611ff65508c90 Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 8 Jul 2013 22:46:36 -0700 Subject: Add git_pathspec_match_diff API This adds an additional pathspec API that will match a pathspec against a diff object. This is convenient if you want to handle renames (so you need the whole diff and can't use the pathspec constraint built into the diff API) but still want to tell if the diff had any files that matched the pathspec. When the pathspec is matched against a diff, instead of keeping a list of filenames that matched, instead the API keeps the list of git_diff_deltas that matched and they can be retrieved via a new API git_pathspec_match_list_diff_entry. There are a couple of other minor API extensions here that were mostly for the sake of convenience and to reduce dependencies on knowing the internal data structure between files inside the library. --- include/git2/pathspec.h | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'include/git2/pathspec.h') diff --git a/include/git2/pathspec.h b/include/git2/pathspec.h index 6d97bb326..a835f8e52 100644 --- a/include/git2/pathspec.h +++ b/include/git2/pathspec.h @@ -10,6 +10,7 @@ #include "common.h" #include "types.h" #include "strarray.h" +#include "diff.h" /** * Compiled pathspec @@ -166,6 +167,30 @@ GIT_EXTERN(int) git_pathspec_match_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_list *diff, + uint32_t flags, + git_pathspec *ps); + /** * Free memory associates with a git_pathspec_match_list * @@ -185,6 +210,9 @@ GIT_EXTERN(size_t) git_pathspec_match_list_entrycount( /** * 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 @@ -192,6 +220,19 @@ GIT_EXTERN(size_t) git_pathspec_match_list_entrycount( 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. * -- cgit v1.2.1