include/git2/pathspec.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_pathspec_h__
0008 #define INCLUDE_git_pathspec_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "strarray.h"
0013 #include "diff.h"
0014
0015 GIT_BEGIN_DECL
0016
0017 /**
0018  * Compiled pathspec
0019  */
0020 typedef struct git_pathspec git_pathspec;
0021
0022 /**
0023  * List of filenames matching a pathspec
0024  */
0025 typedef struct git_pathspec_match_list git_pathspec_match_list;
0026
0027 /**
0028  * Options controlling how pathspec match should be executed
0029  */
0030 typedef enum {
0031     GIT_PATHSPEC_DEFAULT        = 0,
0032
0033     /**
0034      * GIT_PATHSPEC_IGNORE_CASE forces match to ignore case; otherwise
0035      * match will use native case sensitivity of platform filesystem
0036      */
0037     GIT_PATHSPEC_IGNORE_CASE    = (1u << 0),
0038
0039     /**
0040      * GIT_PATHSPEC_USE_CASE forces case sensitive match; otherwise
0041      * match will use native case sensitivity of platform filesystem
0042      */
0043     GIT_PATHSPEC_USE_CASE       = (1u << 1),
0044
0045     /**
0046      * GIT_PATHSPEC_NO_GLOB disables glob patterns and just uses simple
0047      * string comparison for matching
0048      */
0049     GIT_PATHSPEC_NO_GLOB        = (1u << 2),
0050
0051     /**
0052      * GIT_PATHSPEC_NO_MATCH_ERROR means the match functions return error
0053      * code GIT_ENOTFOUND if no matches are found; otherwise no matches is
0054      * still success (return 0) but `git_pathspec_match_list_entrycount`
0055      * will indicate 0 matches.
0056      */
0057     GIT_PATHSPEC_NO_MATCH_ERROR = (1u << 3),
0058
0059     /**
0060      * GIT_PATHSPEC_FIND_FAILURES means that the `git_pathspec_match_list`
0061      * should track which patterns matched which files so that at the end of
0062      * the match we can identify patterns that did not match any files.
0063      */
0064     GIT_PATHSPEC_FIND_FAILURES  = (1u << 4),
0065
0066     /**
0067      * GIT_PATHSPEC_FAILURES_ONLY means that the `git_pathspec_match_list`
0068      * does not need to keep the actual matching filenames.  Use this to
0069      * just test if there were any matches at all or in combination with
0070      * GIT_PATHSPEC_FIND_FAILURES to validate a pathspec.
0071      */
0072     GIT_PATHSPEC_FAILURES_ONLY  = (1u << 5)
0073 } git_pathspec_flag_t;
0074
0075 /**
0076  * Compile a pathspec
0077  *
0078  * @param out Output of the compiled pathspec
0079  * @param pathspec A git_strarray of the paths to match
0080  * @return 0 on success, <0 on failure
0081  */
0082 GIT_EXTERN(int) git_pathspec_new(
0083     git_pathspec **out, const git_strarray *pathspec);
0084
0085 /**
0086  * Free a pathspec
0087  *
0088  * @param ps The compiled pathspec
0089  */
0090 GIT_EXTERN(void) git_pathspec_free(git_pathspec *ps);
0091
0092 /**
0093  * Try to match a path against a pathspec
0094  *
0095  * Unlike most of the other pathspec matching functions, this will not
0096  * fall back on the native case-sensitivity for your platform.  You must
0097  * explicitly pass flags to control case sensitivity or else this will
0098  * fall back on being case sensitive.
0099  *
0100  * @param ps The compiled pathspec
0101  * @param flags Combination of git_pathspec_flag_t options to control match
0102  * @param path The pathname to attempt to match
0103  * @return 1 is path matches spec, 0 if it does not
0104  */
0105 GIT_EXTERN(int) git_pathspec_matches_path(
0106     const git_pathspec *ps, uint32_t flags, const char *path);
0107
0108 /**
0109  * Match a pathspec against the working directory of a repository.
0110  *
0111  * This matches the pathspec against the current files in the working
0112  * directory of the repository.  It is an error to invoke this on a bare
0113  * repo.  This handles git ignores (i.e. ignored files will not be
0114  * considered to match the `pathspec` unless the file is tracked in the
0115  * index).
0116  *
0117  * If `out` is not NULL, this returns a `git_patchspec_match_list`.  That
0118  * contains the list of all matched filenames (unless you pass the
0119  * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of
0120  * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
0121  * flag).  You must call `git_pathspec_match_list_free()` on this object.
0122  *
0123  * @param out Output list of matches; pass NULL to just get return value
0124  * @param repo The repository in which to match; bare repo is an error
0125  * @param flags Combination of git_pathspec_flag_t options to control match
0126  * @param ps Pathspec to be matched
0127  * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and
0128  *         the GIT_PATHSPEC_NO_MATCH_ERROR flag was given
0129  */
0130 GIT_EXTERN(int) git_pathspec_match_workdir(
0131     git_pathspec_match_list **out,
0132     git_repository *repo,
0133     uint32_t flags,
0134     git_pathspec *ps);
0135
0136 /**
0137  * Match a pathspec against entries in an index.
0138  *
0139  * This matches the pathspec against the files in the repository index.
0140  *
0141  * NOTE: At the moment, the case sensitivity of this match is controlled
0142  * by the current case-sensitivity of the index object itself and the
0143  * USE_CASE and IGNORE_CASE flags will have no effect.  This behavior will
0144  * be corrected in a future release.
0145  *
0146  * If `out` is not NULL, this returns a `git_patchspec_match_list`.  That
0147  * contains the list of all matched filenames (unless you pass the
0148  * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of
0149  * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
0150  * flag).  You must call `git_pathspec_match_list_free()` on this object.
0151  *
0152  * @param out Output list of matches; pass NULL to just get return value
0153  * @param index The index to match against
0154  * @param flags Combination of git_pathspec_flag_t options to control match
0155  * @param ps Pathspec to be matched
0156  * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and
0157  *         the GIT_PATHSPEC_NO_MATCH_ERROR flag is used
0158  */
0159 GIT_EXTERN(int) git_pathspec_match_index(
0160     git_pathspec_match_list **out,
0161     git_index *index,
0162     uint32_t flags,
0163     git_pathspec *ps);
0164
0165 /**
0166  * Match a pathspec against files in a tree.
0167  *
0168  * This matches the pathspec against the files in the given tree.
0169  *
0170  * If `out` is not NULL, this returns a `git_patchspec_match_list`.  That
0171  * contains the list of all matched filenames (unless you pass the
0172  * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of
0173  * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
0174  * flag).  You must call `git_pathspec_match_list_free()` on this object.
0175  *
0176  * @param out Output list of matches; pass NULL to just get return value
0177  * @param tree The root-level tree to match against
0178  * @param flags Combination of git_pathspec_flag_t options to control match
0179  * @param ps Pathspec to be matched
0180  * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and
0181  *         the GIT_PATHSPEC_NO_MATCH_ERROR flag is used
0182  */
0183 GIT_EXTERN(int) git_pathspec_match_tree(
0184     git_pathspec_match_list **out,
0185     git_tree *tree,
0186     uint32_t flags,
0187     git_pathspec *ps);
0188
0189 /**
0190  * Match a pathspec against files in a diff list.
0191  *
0192  * This matches the pathspec against the files in the given diff list.
0193  *
0194  * If `out` is not NULL, this returns a `git_patchspec_match_list`.  That
0195  * contains the list of all matched filenames (unless you pass the
0196  * `GIT_PATHSPEC_FAILURES_ONLY` flag) and may also contain the list of
0197  * pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
0198  * flag).  You must call `git_pathspec_match_list_free()` on this object.
0199  *
0200  * @param out Output list of matches; pass NULL to just get return value
0201  * @param diff A generated diff list
0202  * @param flags Combination of git_pathspec_flag_t options to control match
0203  * @param ps Pathspec to be matched
0204  * @return 0 on success, -1 on error, GIT_ENOTFOUND if no matches and
0205  *         the GIT_PATHSPEC_NO_MATCH_ERROR flag is used
0206  */
0207 GIT_EXTERN(int) git_pathspec_match_diff(
0208     git_pathspec_match_list **out,
0209     git_diff *diff,
0210     uint32_t flags,
0211     git_pathspec *ps);
0212
0213 /**
0214  * Free memory associates with a git_pathspec_match_list
0215  *
0216  * @param m The git_pathspec_match_list to be freed
0217  */
0218 GIT_EXTERN(void) git_pathspec_match_list_free(git_pathspec_match_list *m);
0219
0220 /**
0221  * Get the number of items in a match list.
0222  *
0223  * @param m The git_pathspec_match_list object
0224  * @return Number of items in match list
0225  */
0226 GIT_EXTERN(size_t) git_pathspec_match_list_entrycount(
0227     const git_pathspec_match_list *m);
0228
0229 /**
0230  * Get a matching filename by position.
0231  *
0232  * This routine cannot be used if the match list was generated by
0233  * `git_pathspec_match_diff`.  If so, it will always return NULL.
0234  *
0235  * @param m The git_pathspec_match_list object
0236  * @param pos The index into the list
0237  * @return The filename of the match
0238  */
0239 GIT_EXTERN(const char *) git_pathspec_match_list_entry(
0240     const git_pathspec_match_list *m, size_t pos);
0241
0242 /**
0243  * Get a matching diff delta by position.
0244  *
0245  * This routine can only be used if the match list was generated by
0246  * `git_pathspec_match_diff`.  Otherwise it will always return NULL.
0247  *
0248  * @param m The git_pathspec_match_list object
0249  * @param pos The index into the list
0250  * @return The filename of the match
0251  */
0252 GIT_EXTERN(const git_diff_delta *) git_pathspec_match_list_diff_entry(
0253     const git_pathspec_match_list *m, size_t pos);
0254
0255 /**
0256  * Get the number of pathspec items that did not match.
0257  *
0258  * This will be zero unless you passed GIT_PATHSPEC_FIND_FAILURES when
0259  * generating the git_pathspec_match_list.
0260  *
0261  * @param m The git_pathspec_match_list object
0262  * @return Number of items in original pathspec that had no matches
0263  */
0264 GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount(
0265     const git_pathspec_match_list *m);
0266
0267 /**
0268  * Get an original pathspec string that had no matches.
0269  *
0270  * This will be return NULL for positions out of range.
0271  *
0272  * @param m The git_pathspec_match_list object
0273  * @param pos The index into the failed items
0274  * @return The pathspec pattern that didn't match anything
0275  */
0276 GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry(
0277     const git_pathspec_match_list *m, size_t pos);
0278
0279 GIT_END_DECL
0280 #endif