dir.h

   1 #ifndef DIR_H
   2 #define DIR_H
   3
   4 #include "cache.h"
   5 #include "strbuf.h"
   6
   7 /**
   8  * The directory listing API is used to enumerate paths in the work tree,
   9  * optionally taking `.git/info/exclude` and `.gitignore` files per directory
  10  * into account.
  11  */
  12
  13 /**
  14  * Calling sequence
  15  * ----------------
  16  *
  17  * Note: The index may be checked for .gitignore files that are
  18  * CE_SKIP_WORKTREE marked. If you want to exclude files, make sure you have
  19  * loaded the index first.
  20  *
  21  * - Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
  22  * sizeof(dir))`.
  23  *
  24  * - To add single exclude pattern, call `add_pattern_list()` and then
  25  *   `add_pattern()`.
  26  *
  27  * - To add patterns from a file (e.g. `.git/info/exclude`), call
  28  *   `add_patterns_from_file()` , and/or set `dir.exclude_per_dir`.  A
  29  *   short-hand function `setup_standard_excludes()` can be used to set
  30  *   up the standard set of exclude settings.
  31  *
  32  * - Set options described in the Data Structure section above.
  33  *
  34  * - Call `read_directory()`.
  35  *
  36  * - Use `dir.entries[]`.
  37  *
  38  * - Call `clear_directory()` when none of the contained elements are no longer in use.
  39  *
  40  */
  41
  42 struct dir_entry {
  43         unsigned int len;
  44         char name[FLEX_ARRAY]; /* more */
  45 };
  46
  47 #define PATTERN_FLAG_NODIR 1
  48 #define PATTERN_FLAG_ENDSWITH 4
  49 #define PATTERN_FLAG_MUSTBEDIR 8
  50 #define PATTERN_FLAG_NEGATIVE 16
  51
  52 struct path_pattern {
  53         /*
  54          * This allows callers of last_matching_pattern() etc.
  55          * to determine the origin of the matching pattern.
  56          */
  57         struct pattern_list *pl;
  58
  59         const char *pattern;
  60         int patternlen;
  61         int nowildcardlen;
  62         const char *base;
  63         int baselen;
  64         unsigned flags;         /* PATTERN_FLAG_* */
  65
  66         /*
  67          * Counting starts from 1 for line numbers in ignore files,
  68          * and from -1 decrementing for patterns from CLI args.
  69          */
  70         int srcpos;
  71 };
  72
  73 /*
  74  * Each excludes file will be parsed into a fresh exclude_list which
  75  * is appended to the relevant exclude_list_group (either EXC_DIRS or
  76  * EXC_FILE).  An exclude_list within the EXC_CMDL exclude_list_group
  77  * can also be used to represent the list of --exclude values passed
  78  * via CLI args.
  79  */
  80 struct pattern_list {
  81         int nr;
  82         int alloc;
  83
  84         /* remember pointer to exclude file contents so we can free() */
  85         char *filebuf;
  86
  87         /* origin of list, e.g. path to filename, or descriptive string */
  88         const char *src;
  89
  90         struct path_pattern **patterns;
  91 };
  92
  93 /*
  94  * The contents of the per-directory exclude files are lazily read on
  95  * demand and then cached in memory, one per exclude_stack struct, in
  96  * order to avoid opening and parsing each one every time that
  97  * directory is traversed.
  98  */
  99 struct exclude_stack {
 100         struct exclude_stack *prev; /* the struct exclude_stack for the parent directory */
 101         int baselen;
 102         int exclude_ix; /* index of exclude_list within EXC_DIRS exclude_list_group */
 103         struct untracked_cache_dir *ucd;
 104 };
 105
 106 struct exclude_list_group {
 107         int nr, alloc;
 108         struct pattern_list *pl;
 109 };
 110
 111 struct oid_stat {
 112         struct stat_data stat;
 113         struct object_id oid;
 114         int valid;
 115 };
 116
 117 /*
 118  *  Untracked cache
 119  *
 120  *  The following inputs are sufficient to determine what files in a
 121  *  directory are excluded:
 122  *
 123  *   - The list of files and directories of the directory in question
 124  *   - The $GIT_DIR/index
 125  *   - dir_struct flags
 126  *   - The content of $GIT_DIR/info/exclude
 127  *   - The content of core.excludesfile
 128  *   - The content (or the lack) of .gitignore of all parent directories
 129  *     from $GIT_WORK_TREE
 130  *   - The check_only flag in read_directory_recursive (for
 131  *     DIR_HIDE_EMPTY_DIRECTORIES)
 132  *
 133  *  The first input can be checked using directory mtime. In many
 134  *  filesystems, directory mtime (stat_data field) is updated when its
 135  *  files or direct subdirs are added or removed.
 136  *
 137  *  The second one can be hooked from cache_tree_invalidate_path().
 138  *  Whenever a file (or a submodule) is added or removed from a
 139  *  directory, we invalidate that directory.
 140  *
 141  *  The remaining inputs are easy, their SHA-1 could be used to verify
 142  *  their contents (exclude_sha1[], info_exclude_sha1[] and
 143  *  excludes_file_sha1[])
 144  */
 145 struct untracked_cache_dir {
 146         struct untracked_cache_dir **dirs;
 147         char **untracked;
 148         struct stat_data stat_data;
 149         unsigned int untracked_alloc, dirs_nr, dirs_alloc;
 150         unsigned int untracked_nr;
 151         unsigned int check_only : 1;
 152         /* all data except 'dirs' in this struct are good */
 153         unsigned int valid : 1;
 154         unsigned int recurse : 1;
 155         /* null object ID means this directory does not have .gitignore */
 156         struct object_id exclude_oid;
 157         char name[FLEX_ARRAY];
 158 };
 159
 160 struct untracked_cache {
 161         struct oid_stat ss_info_exclude;
 162         struct oid_stat ss_excludes_file;
 163         const char *exclude_per_dir;
 164         struct strbuf ident;
 165         /*
 166          * dir_struct#flags must match dir_flags or the untracked
 167          * cache is ignored.
 168          */
 169         unsigned dir_flags;
 170         struct untracked_cache_dir *root;
 171         /* Statistics */
 172         int dir_created;
 173         int gitignore_invalidated;
 174         int dir_invalidated;
 175         int dir_opened;
 176         /* fsmonitor invalidation data */
 177         unsigned int use_fsmonitor : 1;
 178 };
 179
 180 /**
 181  * structure is used to pass directory traversal options to the library and to
 182  * record the paths discovered. A single `struct dir_struct` is used regardless
 183  * of whether or not the traversal recursively descends into subdirectories.
 184  */
 185 struct dir_struct {
 186
 187         /* The number of members in `entries[]` array. */
 188         int nr;
 189
 190         /* Internal use; keeps track of allocation of `entries[]` array.*/
 191         int alloc;
 192
 193         /* The number of members in `ignored[]` array. */
 194         int ignored_nr;
 195
 196         int ignored_alloc;
 197
 198         /* bit-field of options */
 199         enum {
 200
 201                 /**
 202                  * Return just ignored files in `entries[]`, not untracked files.
 203                  * This flag is mutually exclusive with `DIR_SHOW_IGNORED_TOO`.
 204                  */
 205                 DIR_SHOW_IGNORED = 1<<0,
 206
 207                 /* Include a directory that is not tracked. */
 208                 DIR_SHOW_OTHER_DIRECTORIES = 1<<1,
 209
 210                 /* Do not include a directory that is not tracked and is empty. */
 211                 DIR_HIDE_EMPTY_DIRECTORIES = 1<<2,
 212
 213                 /**
 214                  * If set, recurse into a directory that looks like a Git directory.
 215                  * Otherwise it is shown as a directory.
 216                  */
 217                 DIR_NO_GITLINKS = 1<<3,
 218
 219                 /**
 220                  * Special mode for git-add. Return ignored files in `ignored[]` and
 221                  * untracked files in `entries[]`. Only returns ignored files that match
 222                  * pathspec exactly (no wildcards). Does not recurse into ignored
 223                  * directories.
 224                  */
 225                 DIR_COLLECT_IGNORED = 1<<4,
 226
 227                 /**
 228                  * Similar to `DIR_SHOW_IGNORED`, but return ignored files in
 229                  * `ignored[]` in addition to untracked files in `entries[]`.
 230                  * This flag is mutually exclusive with `DIR_SHOW_IGNORED`.
 231                  */
 232                 DIR_SHOW_IGNORED_TOO = 1<<5,
 233
 234                 DIR_COLLECT_KILLED_ONLY = 1<<6,
 235
 236                 /**
 237                  * Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is
 238                  * set, the untracked contents of untracked directories are also
 239                  * returned in `entries[]`.
 240                  */
 241                 DIR_KEEP_UNTRACKED_CONTENTS = 1<<7,
 242
 243                 /**
 244                  * Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is
 245                  * set, returns ignored files and directories that match an exclude
 246                  * pattern. If a directory matches an exclude pattern, then the
 247                  * directory is returned and the contained paths are not. A directory
 248                  * that does not match an exclude pattern will not be returned even if
 249                  * all of its contents are ignored. In this case, the contents are
 250                  * returned as individual entries.
 251                  *
 252                  * If this is set, files and directories that explicitly match an ignore
 253                  * pattern are reported. Implicitly ignored directories (directories that
 254                  * do not match an ignore pattern, but whose contents are all ignored)
 255                  * are not reported, instead all of the contents are reported.
 256                  */
 257                 DIR_SHOW_IGNORED_TOO_MODE_MATCHING = 1<<8,
 258
 259                 DIR_SKIP_NESTED_GIT = 1<<9
 260         } flags;
 261
 262         /* An array of `struct dir_entry`, each element of which describes a path. */
 263         struct dir_entry **entries;
 264
 265         /**
 266          * used for ignored paths with the `DIR_SHOW_IGNORED_TOO` and
 267          * `DIR_COLLECT_IGNORED` flags.
 268          */
 269         struct dir_entry **ignored;
 270
 271         /**
 272          * The name of the file to be read in each directory for excluded files
 273          * (typically `.gitignore`).
 274          */
 275         const char *exclude_per_dir;
 276
 277         /*
 278          * We maintain three groups of exclude pattern lists:
 279          *
 280          * EXC_CMDL lists patterns explicitly given on the command line.
 281          * EXC_DIRS lists patterns obtained from per-directory ignore files.
 282          * EXC_FILE lists patterns from fallback ignore files, e.g.
 283          *   - .git/info/exclude
 284          *   - core.excludesfile
 285          *
 286          * Each group contains multiple exclude lists, a single list
 287          * per source.
 288          */
 289 #define EXC_CMDL 0
 290 #define EXC_DIRS 1
 291 #define EXC_FILE 2
 292         struct exclude_list_group exclude_list_group[3];
 293
 294         /*
 295          * Temporary variables which are used during loading of the
 296          * per-directory exclude lists.
 297          *
 298          * exclude_stack points to the top of the exclude_stack, and
 299          * basebuf contains the full path to the current
 300          * (sub)directory in the traversal. Exclude points to the
 301          * matching exclude struct if the directory is excluded.
 302          */
 303         struct exclude_stack *exclude_stack;
 304         struct path_pattern *pattern;
 305         struct strbuf basebuf;
 306
 307         /* Enable untracked file cache if set */
 308         struct untracked_cache *untracked;
 309         struct oid_stat ss_info_exclude;
 310         struct oid_stat ss_excludes_file;
 311         unsigned unmanaged_exclude_files;
 312 };
 313
 314 /*Count the number of slashes for string s*/
 315 int count_slashes(const char *s);
 316
 317 /*
 318  * The ordering of these constants is significant, with
 319  * higher-numbered match types signifying "closer" (i.e. more
 320  * specific) matches which will override lower-numbered match types
 321  * when populating the seen[] array.
 322  */
 323 #define MATCHED_RECURSIVELY 1
 324 #define MATCHED_RECURSIVELY_LEADING_PATHSPEC 2
 325 #define MATCHED_FNMATCH 3
 326 #define MATCHED_EXACTLY 4
 327 int simple_length(const char *match);
 328 int no_wildcard(const char *string);
 329 char *common_prefix(const struct pathspec *pathspec);
 330 int match_pathspec(const struct index_state *istate,
 331                    const struct pathspec *pathspec,
 332                    const char *name, int namelen,
 333                    int prefix, char *seen, int is_dir);
 334 int report_path_error(const char *ps_matched, const struct pathspec *pathspec);
 335 int within_depth(const char *name, int namelen, int depth, int max_depth);
 336
 337 int fill_directory(struct dir_struct *dir,
 338                    struct index_state *istate,
 339                    const struct pathspec *pathspec);
 340 int read_directory(struct dir_struct *, struct index_state *istate,
 341                    const char *path, int len,
 342                    const struct pathspec *pathspec);
 343
 344 enum pattern_match_result {
 345         UNDECIDED = -1,
 346         NOT_MATCHED = 0,
 347         MATCHED = 1,
 348 };
 349
 350 /*
 351  * Scan the list of patterns to determine if the ordered list
 352  * of patterns matches on 'pathname'.
 353  *
 354  * Return 1 for a match, 0 for not matched and -1 for undecided.
 355  */
 356 enum pattern_match_result path_matches_pattern_list(const char *pathname,
 357                                 int pathlen,
 358                                 const char *basename, int *dtype,
 359                                 struct pattern_list *pl,
 360                                 struct index_state *istate);
 361 struct dir_entry *dir_add_ignored(struct dir_struct *dir,
 362                                   struct index_state *istate,
 363                                   const char *pathname, int len);
 364
 365 /*
 366  * these implement the matching logic for dir.c:excluded_from_list and
 367  * attr.c:path_matches()
 368  */
 369 int match_basename(const char *, int,
 370                    const char *, int, int, unsigned);
 371 int match_pathname(const char *, int,
 372                    const char *, int,
 373                    const char *, int, int, unsigned);
 374
 375 struct path_pattern *last_matching_pattern(struct dir_struct *dir,
 376                                            struct index_state *istate,
 377                                            const char *name, int *dtype);
 378
 379 int is_excluded(struct dir_struct *dir,
 380                 struct index_state *istate,
 381                 const char *name, int *dtype);
 382
 383 struct pattern_list *add_pattern_list(struct dir_struct *dir,
 384                                       int group_type, const char *src);
 385 int add_patterns_from_file_to_list(const char *fname, const char *base, int baselen,
 386                                    struct pattern_list *pl, struct  index_state *istate);
 387 void add_patterns_from_file(struct dir_struct *, const char *fname);
 388 int add_patterns_from_blob_to_list(struct object_id *oid,
 389                                    const char *base, int baselen,
 390                                    struct pattern_list *pl);
 391 void parse_path_pattern(const char **string, int *patternlen, unsigned *flags, int *nowildcardlen);
 392 void add_pattern(const char *string, const char *base,
 393                  int baselen, struct pattern_list *pl, int srcpos);
 394 void clear_pattern_list(struct pattern_list *pl);
 395 void clear_directory(struct dir_struct *dir);
 396
 397 int repo_file_exists(struct repository *repo, const char *path);
 398 int file_exists(const char *);
 399
 400 int is_inside_dir(const char *dir);
 401 int dir_inside_of(const char *subdir, const char *dir);
 402
 403 static inline int is_dot_or_dotdot(const char *name)
 404 {
 405         return (name[0] == '.' &&
 406                 (name[1] == '\0' ||
 407                  (name[1] == '.' && name[2] == '\0')));
 408 }
 409
 410 int is_empty_dir(const char *dir);
 411
 412 void setup_standard_excludes(struct dir_struct *dir);
 413
 414
 415 /* Constants for remove_dir_recursively: */
 416
 417 /*
 418  * If a non-directory is found within path, stop and return an error.
 419  * (In this case some empty directories might already have been
 420  * removed.)
 421  */
 422 #define REMOVE_DIR_EMPTY_ONLY 01
 423
 424 /*
 425  * If any Git work trees are found within path, skip them without
 426  * considering it an error.
 427  */
 428 #define REMOVE_DIR_KEEP_NESTED_GIT 02
 429
 430 /* Remove the contents of path, but leave path itself. */
 431 #define REMOVE_DIR_KEEP_TOPLEVEL 04
 432
 433 /*
 434  * Remove path and its contents, recursively. flags is a combination
 435  * of the above REMOVE_DIR_* constants. Return 0 on success.
 436  *
 437  * This function uses path as temporary scratch space, but restores it
 438  * before returning.
 439  */
 440 int remove_dir_recursively(struct strbuf *path, int flag);
 441
 442 /* tries to remove the path with empty directories along it, ignores ENOENT */
 443 int remove_path(const char *path);
 444
 445 int fspathcmp(const char *a, const char *b);
 446 int fspathncmp(const char *a, const char *b, size_t count);
 447
 448 /*
 449  * The prefix part of pattern must not contains wildcards.
 450  */
 451 struct pathspec_item;
 452 int git_fnmatch(const struct pathspec_item *item,
 453                 const char *pattern, const char *string,
 454                 int prefix);
 455
 456 int submodule_path_match(const struct index_state *istate,
 457                          const struct pathspec *ps,
 458                          const char *submodule_name,
 459                          char *seen);
 460
 461 static inline int ce_path_match(const struct index_state *istate,
 462                                 const struct cache_entry *ce,
 463                                 const struct pathspec *pathspec,
 464                                 char *seen)
 465 {
 466         return match_pathspec(istate, pathspec, ce->name, ce_namelen(ce), 0, seen,
 467                               S_ISDIR(ce->ce_mode) || S_ISGITLINK(ce->ce_mode));
 468 }
 469
 470 static inline int dir_path_match(const struct index_state *istate,
 471                                  const struct dir_entry *ent,
 472                                  const struct pathspec *pathspec,
 473                                  int prefix, char *seen)
 474 {
 475         int has_trailing_dir = ent->len && ent->name[ent->len - 1] == '/';
 476         int len = has_trailing_dir ? ent->len - 1 : ent->len;
 477         return match_pathspec(istate, pathspec, ent->name, len, prefix, seen,
 478                               has_trailing_dir);
 479 }
 480
 481 int cmp_dir_entry(const void *p1, const void *p2);
 482 int check_dir_entry_contains(const struct dir_entry *out, const struct dir_entry *in);
 483
 484 void untracked_cache_invalidate_path(struct index_state *, const char *, int safe_path);
 485 void untracked_cache_remove_from_index(struct index_state *, const char *);
 486 void untracked_cache_add_to_index(struct index_state *, const char *);
 487
 488 void free_untracked_cache(struct untracked_cache *);
 489 struct untracked_cache *read_untracked_extension(const void *data, unsigned long sz);
 490 void write_untracked_extension(struct strbuf *out, struct untracked_cache *untracked);
 491 void add_untracked_cache(struct index_state *istate);
 492 void remove_untracked_cache(struct index_state *istate);
 493
 494 /*
 495  * Connect a worktree to a git directory by creating (or overwriting) a
 496  * '.git' file containing the location of the git directory. In the git
 497  * directory set the core.worktree setting to indicate where the worktree is.
 498  * When `recurse_into_nested` is set, recurse into any nested submodules,
 499  * connecting them as well.
 500  */
 501 void connect_work_tree_and_git_dir(const char *work_tree,
 502                                    const char *git_dir,
 503                                    int recurse_into_nested);
 504 void relocate_gitdir(const char *path,
 505                      const char *old_git_dir,
 506                      const char *new_git_dir);
 507 #endif