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 0 or 1 - see gitmodules(5) fetchRecurseSubmodules.
  64  *
  65  * - `repo` is the parent repository that contains this submodule.
  66  * - `flags` after for internal use, tracking where this submodule has been
  67  *   found (head, index, config, workdir) and known status info, etc.
  68  * - `head_oid` is the SHA1 for the submodule path in the repo HEAD.
  69  * - `index_oid` is the SHA1 for the submodule recorded in the index.
  70  * - `wd_oid` is the SHA1 for the HEAD of the checked out submodule.
  71  *
  72  * If the submodule has been added to .gitmodules but not yet git added,
  73  * then the `index_oid` will be zero but still marked valid.  If the
  74  * submodule has been deleted, but the delete has not been committed yet,
  75  * then the `index_oid` will be set, but the `url` will be NULL.
  76  */
  77 struct git_submodule {
  78         git_refcount rc;
  79
  80         /* information from config */
  81         char *name;
  82         char *path; /* important: may just point to "name" string */
  83         char *url;
  84         git_submodule_update_t update;
  85         git_submodule_update_t update_default;
  86         git_submodule_ignore_t ignore;
  87         git_submodule_ignore_t ignore_default;
  88         int fetch_recurse;
  89
  90         /* internal information */
  91         git_repository *repo;
  92         uint32_t flags;
  93         git_oid head_oid;
  94         git_oid index_oid;
  95         git_oid wd_oid;
  96 };
  97
  98 /* Additional flags on top of public GIT_SUBMODULE_STATUS values */
  99 enum {
 100         GIT_SUBMODULE_STATUS__WD_SCANNED          = (1u << 20),
 101         GIT_SUBMODULE_STATUS__HEAD_OID_VALID      = (1u << 21),
 102         GIT_SUBMODULE_STATUS__INDEX_OID_VALID     = (1u << 22),
 103         GIT_SUBMODULE_STATUS__WD_OID_VALID        = (1u << 23),
 104         GIT_SUBMODULE_STATUS__HEAD_NOT_SUBMODULE  = (1u << 24),
 105         GIT_SUBMODULE_STATUS__INDEX_NOT_SUBMODULE = (1u << 25),
 106         GIT_SUBMODULE_STATUS__WD_NOT_SUBMODULE    = (1u << 26),
 107         GIT_SUBMODULE_STATUS__INDEX_MULTIPLE_ENTRIES = (1u << 27),
 108 };
 109
 110 #define GIT_SUBMODULE_STATUS__CLEAR_INTERNAL(S) \
 111         ((S) & ~(0xFFFFFFFFu << 20))
 112
 113 /* Internal status fn returns status and optionally the various OIDs */
 114 extern int git_submodule__status(
 115         unsigned int *out_status,
 116         git_oid *out_head_id,
 117         git_oid *out_index_id,
 118         git_oid *out_wd_id,
 119         git_submodule *sm,
 120         git_submodule_ignore_t ign);
 121
 122 /* Open submodule repository as bare repo for quick HEAD check, etc. */
 123 extern int git_submodule_open_bare(
 124         git_repository **repo,
 125         git_submodule *submodule);
 126
 127 /* Release reference to submodule object - not currently for external use */
 128 extern void git_submodule_free(git_submodule *sm);
 129
 130 #endif