submodule-config.h

   1 #ifndef SUBMODULE_CONFIG_CACHE_H
   2 #define SUBMODULE_CONFIG_CACHE_H
   3
   4 #include "config.h"
   5 #include "submodule.h"
   6 #include "tree-walk.h"
   7
   8 /**
   9  * The submodule config cache API allows to read submodule
  10  * configurations/information from specified revisions. Internally
  11  * information is lazily read into a cache that is used to avoid
  12  * unnecessary parsing of the same .gitmodules files. Lookups can be done by
  13  * submodule path or name.
  14  *
  15  * Usage
  16  * -----
  17  *
  18  * The caller can look up information about submodules by using the
  19  * `submodule_from_path()` or `submodule_from_name()` functions. They return
  20  * a `struct submodule` which contains the values. The API automatically
  21  * initializes and allocates the needed infrastructure on-demand. If the
  22  * caller does only want to lookup values from revisions the initialization
  23  * can be skipped.
  24  *
  25  * If the internal cache might grow too big or when the caller is done with
  26  * the API, all internally cached values can be freed with submodule_free().
  27  *
  28  */
  29
  30 /*
  31  * Submodule entry containing the information about a certain submodule
  32  * in a certain revision. It is returned by the lookup functions.
  33  */
  34 struct submodule {
  35         const char *path;
  36         const char *name;
  37         const char *url;
  38         enum submodule_recurse_mode fetch_recurse;
  39         const char *ignore;
  40         const char *branch;
  41         struct submodule_update_strategy update_strategy;
  42         /* the object id of the responsible .gitmodules file */
  43         struct object_id gitmodules_oid;
  44         int recommend_shallow;
  45 };
  46 struct submodule_cache;
  47 struct repository;
  48
  49 void submodule_cache_free(struct submodule_cache *cache);
  50
  51 int parse_submodule_fetchjobs(const char *var, const char *value,
  52                               const struct key_value_info *kvi);
  53 int parse_fetch_recurse_submodules_arg(const char *opt, const char *arg);
  54 struct option;
  55 int option_fetch_parse_recurse_submodules(const struct option *opt,
  56                                           const char *arg, int unset);
  57 int parse_update_recurse_submodules_arg(const char *opt, const char *arg);
  58 int parse_push_recurse_submodules_arg(const char *opt, const char *arg);
  59 void repo_read_gitmodules(struct repository *repo, int skip_if_read);
  60 void gitmodules_config_oid(const struct object_id *commit_oid);
  61
  62 /**
  63  * Same as submodule_from_path but lookup by name.
  64  */
  65 const struct submodule *submodule_from_name(struct repository *r,
  66                                             const struct object_id *commit_or_tree,
  67                                             const char *name);
  68
  69 /**
  70  * Given a tree-ish in the superproject and a path, return the submodule that
  71  * is bound at the path in the named tree.
  72  */
  73 const struct submodule *submodule_from_path(struct repository *r,
  74                                             const struct object_id *commit_or_tree,
  75                                             const char *path);
  76
  77 /**
  78  * Use these to free the internally cached values.
  79  */
  80 void submodule_free(struct repository *r);
  81
  82 int print_config_from_gitmodules(struct repository *repo, const char *key);
  83 int config_set_in_gitmodules_file_gently(const char *key, const char *value);
  84
  85 /*
  86  * Returns 0 if the name is syntactically acceptable as a submodule "name"
  87  * (e.g., that may be found in the subsection of a .gitmodules file) and -1
  88  * otherwise.
  89  */
  90 int check_submodule_name(const char *name);
  91
  92 /* Returns 0 if the URL valid per RFC3986 and -1 otherwise. */
  93 int check_submodule_url(const char *url);
  94
  95 /*
  96  * Note: these helper functions exist solely to maintain backward
  97  * compatibility with 'fetch' and 'update_clone' storing configuration in
  98  * '.gitmodules'.
  99  *
 100  * New helpers to retrieve arbitrary configuration from the '.gitmodules' file
 101  * should NOT be added.
 102  */
 103 void fetch_config_from_gitmodules(int *max_children, int *recurse_submodules);
 104 void update_clone_config_from_gitmodules(int *max_jobs);
 105
 106 /*
 107  * Submodule entry that contains relevant information about a
 108  * submodule in a tree.
 109  */
 110 struct submodule_tree_entry {
 111         /* The submodule's tree entry. */
 112         struct name_entry *name_entry;
 113         /*
 114          * A struct repository corresponding to the submodule. May be
 115          * NULL if the submodule has not been updated.
 116          */
 117         struct repository *repo;
 118         /*
 119          * A struct submodule containing the submodule config in the
 120          * tree's .gitmodules.
 121          */
 122         const struct submodule *submodule;
 123 };
 124
 125 struct submodule_entry_list {
 126         struct submodule_tree_entry *entries;
 127         int entry_nr;
 128         int entry_alloc;
 129 };
 130
 131 /**
 132  * Given a treeish, return all submodules in the tree and its subtrees,
 133  * but excluding nested submodules. Callers that require nested
 134  * submodules are expected to recurse into the submodules themselves.
 135  */
 136 void submodules_of_tree(struct repository *r,
 137                         const struct object_id *treeish_name,
 138                         struct submodule_entry_list *ret);
 139
 140 void submodule_entry_list_release(struct submodule_entry_list *list);
 141
 142 #endif /* SUBMODULE_CONFIG_H */