src/submodule.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_submodule_h__
   8 #define INCLUDE_submodule_h__
   9
  10 #include "git2/submodule.h"
  11 #include "git2/repository.h"
  12 #include "fileops.h"
  13
  14 /* Notes:
  15  *
  16  * Submodule information can be in four places: the index, the config files
  17  * (both .git/config and .gitmodules), the HEAD tree, and the working
  18  * directory.
  19  *
  20  * In the index:
  21  * - submodule is found by path
  22  * - may be missing, present, or of the wrong type
  23  * - will have an oid if present
  24  *
  25  * In the HEAD tree:
  26  * - submodule is found by path
  27  * - may be missing, present, or of the wrong type
  28  * - will have an oid if present
  29  *
  30  * In the config files:
  31  * - submodule is found by submodule "name" which is usually the path
  32  * - may be missing or present
  33  * - will have a name, path, url, and other properties
  34  *
  35  * In the working directory:
  36  * - submodule is found by path
  37  * - may be missing, an empty directory, a checked out directory,
  38  *   or of the wrong type
  39  * - if checked out, will have a HEAD oid
  40  * - if checked out, will have git history that can be used to compare oids
  41  * - if checked out, may have modified files and/or untracked files
  42  */
  43
  44 /**
  45  * Description of submodule
  46  *
  47  * This record describes a submodule found in a repository.  There should be
  48  * an entry for every submodule found in the HEAD and index, and for every
  49  * submodule described in .gitmodules.  The fields are as follows:
  50  *
  51  * - `rc` tracks the refcount of how many hash table entries in the
  52  *   git_submodule_cache there are for this submodule.  It only comes into
  53  *   play if the name and path of the submodule differ.
  54  *
  55  * - `name` is the name of the submodule from .gitmodules.
  56  * - `path` is the path to the submodule from the repo root.  It is almost
  57  *    always the same as `name`.
  58  * - `url` is the url for the submodule.
  59  * - `update` is a git_submodule_update_t value - see gitmodules(5) update.
  60  * - `update_default` is the update value from the config
  61  * - `ignore` is a git_submodule_ignore_t value - see gitmodules(5) ignore.
  62  * - `ignore_default` is the ignore value from the config
  63  * - `fetch_recurse` is a git_submodule_recurse_t value - see gitmodules(5)
  64  *    fetchRecurseSubmodules.
  65  * - `fetch_recurse_default` is the recurse value from the config
  66  *
  67  * - `repo` is the parent repository that contains this submodule.
  68  * - `flags` after for internal use, tracking where this submodule has been
  69  *   found (head, index, config, workdir) and known status info, etc.
  70  * - `head_oid` is the SHA1 for the submodule path in the repo HEAD.
  71  * - `index_oid` is the SHA1 for the submodule recorded in the index.
  72  * - `wd_oid` is the SHA1 for the HEAD of the checked out submodule.
  73  *
  74  * If the submodule has been added to .gitmodules but not yet git added,
  75  * then the `index_oid` will be zero but still marked valid.  If the
  76  * submodule has been deleted, but the delete has not been committed yet,
  77  * then the `index_oid` will be set, but the `url` will be NULL.
  78  */
  79 struct git_submodule {
  80         git_refcount rc;
  81
  82         /* information from config */
  83         char *name;
  84         char *path; /* important: may just point to "name" string */
  85         char *url;
  86         char *branch;
  87         git_submodule_update_t update;
  88         git_submodule_update_t update_default;
  89         git_submodule_ignore_t ignore;
  90         git_submodule_ignore_t ignore_default;
  91         git_submodule_recurse_t fetch_recurse;
  92         git_submodule_recurse_t fetch_recurse_default;
  93
  94         /* internal information */
  95         git_repository *repo;
  96         uint32_t flags;
  97         git_oid head_oid;
  98         git_oid index_oid;
  99         git_oid wd_oid;
 100 };
 101
 102 /* Force revalidation of submodule data cache (alloc as needed) */
 103 extern int git_submodule_cache_refresh(git_repository *repo);
 104
 105 /* Release all submodules */
 106 extern void git_submodule_cache_free(git_repository *repo);
 107
 108 /* Additional flags on top of public GIT_SUBMODULE_STATUS values */
 109 enum {
 110         GIT_SUBMODULE_STATUS__WD_SCANNED          = (1u << 20),
 111         GIT_SUBMODULE_STATUS__HEAD_OID_VALID      = (1u << 21),
 112         GIT_SUBMODULE_STATUS__INDEX_OID_VALID     = (1u << 22),
 113         GIT_SUBMODULE_STATUS__WD_OID_VALID        = (1u << 23),
 114         GIT_SUBMODULE_STATUS__HEAD_NOT_SUBMODULE  = (1u << 24),
 115         GIT_SUBMODULE_STATUS__INDEX_NOT_SUBMODULE = (1u << 25),
 116         GIT_SUBMODULE_STATUS__WD_NOT_SUBMODULE    = (1u << 26),
 117         GIT_SUBMODULE_STATUS__INDEX_MULTIPLE_ENTRIES = (1u << 27),
 118 };
 119
 120 #define GIT_SUBMODULE_STATUS__CLEAR_INTERNAL(S) \
 121         ((S) & ~(0xFFFFFFFFu << 20))
 122
 123 /* Internal lookup does not attempt to refresh cached data */
 124 extern int git_submodule__lookup(
 125         git_submodule **out, git_repository *repo, const char *path);
 126
 127 /* Internal status fn returns status and optionally the various OIDs */
 128 extern int git_submodule__status(
 129         unsigned int *out_status,
 130         git_oid *out_head_id,
 131         git_oid *out_index_id,
 132         git_oid *out_wd_id,
 133         git_submodule *sm,
 134         git_submodule_ignore_t ign);
 135
 136 /* Open submodule repository as bare repo for quick HEAD check, etc. */
 137 extern int git_submodule_open_bare(
 138         git_repository **repo,
 139         git_submodule *submodule);
 140
 141 extern int git_submodule_parse_ignore(
 142         git_submodule_ignore_t *out, const char *value);
 143 extern int git_submodule_parse_update(
 144         git_submodule_update_t *out, const char *value);
 145
 146 extern int git_submodule__map(
 147         git_repository *repo,
 148         git_strmap *map);
 149 #endif