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_git_submodule_h__ 8 #define INCLUDE_git_submodule_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "remote.h" 14 #include "checkout.h" 15 16 /** 17 * @file git2/submodule.h 18 * @brief Git submodule management utilities 19 * 20 * Submodule support in libgit2 builds a list of known submodules and keeps 21 * it in the repository. The list is built from the .gitmodules file, the 22 * .git/config file, the index, and the HEAD tree. Items in the working 23 * directory that look like submodules (i.e. a git repo) but are not 24 * mentioned in those places won't be tracked. 25 * 26 * @defgroup git_submodule Git submodule management routines 27 * @ingroup Git 28 * @{ 29 */ 30 GIT_BEGIN_DECL 31 32 /** 33 * Return codes for submodule status. 34 * 35 * A combination of these flags will be returned to describe the status of a 36 * submodule. Depending on the "ignore" property of the submodule, some of 37 * the flags may never be returned because they indicate changes that are 38 * supposed to be ignored. 39 * 40 * Submodule info is contained in 4 places: the HEAD tree, the index, config 41 * files (both .git/config and .gitmodules), and the working directory. Any 42 * or all of those places might be missing information about the submodule 43 * depending on what state the repo is in. We consider all four places to 44 * build the combination of status flags. 45 * 46 * There are four values that are not really status, but give basic info 47 * about what sources of submodule data are available. These will be 48 * returned even if ignore is set to "ALL". 49 * 50 * * IN_HEAD - superproject head contains submodule 51 * * IN_INDEX - superproject index contains submodule 52 * * IN_CONFIG - superproject gitmodules has submodule 53 * * IN_WD - superproject workdir has submodule 54 * 55 * The following values will be returned so long as ignore is not "ALL". 56 * 57 * * INDEX_ADDED - in index, not in head 58 * * INDEX_DELETED - in head, not in index 59 * * INDEX_MODIFIED - index and head don't match 60 * * WD_UNINITIALIZED - workdir contains empty directory 61 * * WD_ADDED - in workdir, not index 62 * * WD_DELETED - in index, not workdir 63 * * WD_MODIFIED - index and workdir head don't match 64 * 65 * The following can only be returned if ignore is "NONE" or "UNTRACKED". 66 * 67 * * WD_INDEX_MODIFIED - submodule workdir index is dirty 68 * * WD_WD_MODIFIED - submodule workdir has modified files 69 * 70 * Lastly, the following will only be returned for ignore "NONE". 71 * 72 * * WD_UNTRACKED - wd contains untracked files 73 */ 74 typedef enum { 75 GIT_SUBMODULE_STATUS_IN_HEAD = (1u << 0), 76 GIT_SUBMODULE_STATUS_IN_INDEX = (1u << 1), 77 GIT_SUBMODULE_STATUS_IN_CONFIG = (1u << 2), 78 GIT_SUBMODULE_STATUS_IN_WD = (1u << 3), 79 GIT_SUBMODULE_STATUS_INDEX_ADDED = (1u << 4), 80 GIT_SUBMODULE_STATUS_INDEX_DELETED = (1u << 5), 81 GIT_SUBMODULE_STATUS_INDEX_MODIFIED = (1u << 6), 82 GIT_SUBMODULE_STATUS_WD_UNINITIALIZED = (1u << 7), 83 GIT_SUBMODULE_STATUS_WD_ADDED = (1u << 8), 84 GIT_SUBMODULE_STATUS_WD_DELETED = (1u << 9), 85 GIT_SUBMODULE_STATUS_WD_MODIFIED = (1u << 10), 86 GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED = (1u << 11), 87 GIT_SUBMODULE_STATUS_WD_WD_MODIFIED = (1u << 12), 88 GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13), 89 } git_submodule_status_t; 90 91 #define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu 92 #define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u 93 #define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u 94 95 #define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ 96 (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) 97 98 #define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \ 99 (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0) 100 101 #define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \ 102 (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \ 103 ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0) 104 105 #define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \ 106 (((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \ 107 GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \ 108 GIT_SUBMODULE_STATUS_WD_UNTRACKED)) != 0) 109 110 /** 111 * Function pointer to receive each submodule 112 * 113 * @param sm git_submodule currently being visited 114 * @param name name of the submodule 115 * @param payload value you passed to the foreach function as payload 116 * @return 0 on success or error code 117 */ 118 typedef int GIT_CALLBACK(git_submodule_cb)( 119 git_submodule *sm, const char *name, void *payload); 120 121 /** 122 * Submodule update options structure 123 * 124 * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can 125 * use `git_submodule_update_options_init`. 126 * 127 */ 128 typedef struct git_submodule_update_options { 129 unsigned int version; 130 131 /** 132 * These options are passed to the checkout step. To disable 133 * checkout, set the `checkout_strategy` to 134 * `GIT_CHECKOUT_NONE`. Generally you will want the use 135 * GIT_CHECKOUT_SAFE to update files in the working 136 * directory. 137 */ 138 git_checkout_options checkout_opts; 139 140 /** 141 * Options which control the fetch, including callbacks. 142 * 143 * The callbacks to use for reporting fetch progress, and for acquiring 144 * credentials in the event they are needed. 145 */ 146 git_fetch_options fetch_opts; 147 148 /** 149 * Allow fetching from the submodule's default remote if the target 150 * commit isn't found. Enabled by default. 151 */ 152 int allow_fetch; 153 } git_submodule_update_options; 154 155 #define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1 156 #define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \ 157 { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \ 158 { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ 159 GIT_FETCH_OPTIONS_INIT, 1 } 160 161 /** 162 * Initialize git_submodule_update_options structure 163 * 164 * Initializes a `git_submodule_update_options` with default values. Equivalent to 165 * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. 166 * 167 * @param opts The `git_submodule_update_options` struct to initialize. 168 * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`. 169 * @return Zero on success; -1 on failure. 170 */ 171 GIT_EXTERN(int) git_submodule_update_options_init( 172 git_submodule_update_options *opts, unsigned int version); 173 174 /** 175 * Update a submodule. This will clone a missing submodule and 176 * checkout the subrepository to the commit specified in the index of 177 * the containing repository. If the submodule repository doesn't contain 178 * the target commit (e.g. because fetchRecurseSubmodules isn't set), then 179 * the submodule is fetched using the fetch options supplied in options. 180 * 181 * @param submodule Submodule object 182 * @param init If the submodule is not initialized, setting this flag to true 183 * will initialize the submodule before updating. Otherwise, this will 184 * return an error if attempting to update an uninitialzed repository. 185 * but setting this to true forces them to be updated. 186 * @param options configuration options for the update. If NULL, the 187 * function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed. 188 * @return 0 on success, any non-zero return value from a callback 189 * function, or a negative value to indicate an error (use 190 * `git_error_last` for a detailed error message). 191 */ 192 GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options); 193 194 /** 195 * Lookup submodule information by name or path. 196 * 197 * Given either the submodule name or path (they are usually the same), this 198 * returns a structure describing the submodule. 199 * 200 * There are two expected error scenarios: 201 * 202 * - The submodule is not mentioned in the HEAD, the index, and the config, 203 * but does "exist" in the working directory (i.e. there is a subdirectory 204 * that appears to be a Git repository). In this case, this function 205 * returns GIT_EEXISTS to indicate a sub-repository exists but not in a 206 * state where a git_submodule can be instantiated. 207 * - The submodule is not mentioned in the HEAD, index, or config and the 208 * working directory doesn't contain a value git repo at that path. 209 * There may or may not be anything else at that path, but nothing that 210 * looks like a submodule. In this case, this returns GIT_ENOTFOUND. 211 * 212 * You must call `git_submodule_free` when done with the submodule. 213 * 214 * @param out Output ptr to submodule; pass NULL to just get return code 215 * @param repo The parent repository 216 * @param name The name of or path to the submodule; trailing slashes okay 217 * @return 0 on success, GIT_ENOTFOUND if submodule does not exist, 218 * GIT_EEXISTS if a repository is found in working directory only, 219 * -1 on other errors. 220 */ 221 GIT_EXTERN(int) git_submodule_lookup( 222 git_submodule **out, 223 git_repository *repo, 224 const char *name); 225 226 /** 227 * Create an in-memory copy of a submodule. The copy must be explicitly 228 * free'd or it will leak. 229 * 230 * @param out Pointer to store the copy of the submodule. 231 * @param source Original submodule to copy. 232 */ 233 GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source); 234 235 /** 236 * Release a submodule 237 * 238 * @param submodule Submodule object 239 */ 240 GIT_EXTERN(void) git_submodule_free(git_submodule *submodule); 241 242 /** 243 * Iterate over all tracked submodules of a repository. 244 * 245 * See the note on `git_submodule` above. This iterates over the tracked 246 * submodules as described therein. 247 * 248 * If you are concerned about items in the working directory that look like 249 * submodules but are not tracked, the diff API will generate a diff record 250 * for workdir items that look like submodules but are not tracked, showing 251 * them as added in the workdir. Also, the status API will treat the entire 252 * subdirectory of a contained git repo as a single GIT_STATUS_WT_NEW item. 253 * 254 * @param repo The repository 255 * @param callback Function to be called with the name of each submodule. 256 * Return a non-zero value to terminate the iteration. 257 * @param payload Extra data to pass to callback 258 * @return 0 on success, -1 on error, or non-zero return value of callback 259 */ 260 GIT_EXTERN(int) git_submodule_foreach( 261 git_repository *repo, 262 git_submodule_cb callback, 263 void *payload); 264 265 /** 266 * Set up a new git submodule for checkout. 267 * 268 * This does "git submodule add" up to the fetch and checkout of the 269 * submodule contents. It preps a new submodule, creates an entry in 270 * .gitmodules and creates an empty initialized repository either at the 271 * given path in the working directory or in .git/modules with a gitlink 272 * from the working directory to the new repo. 273 * 274 * To fully emulate "git submodule add" call this function, then open the 275 * submodule repo and perform the clone step as needed (if you don't need 276 * anything custom see `git_submodule_add_clone()`). Lastly, call 277 * `git_submodule_add_finalize()` to wrap up adding the new submodule and 278 * .gitmodules to the index to be ready to commit. 279 * 280 * You must call `git_submodule_free` on the submodule object when done. 281 * 282 * @param out The newly created submodule ready to open for clone 283 * @param repo The repository in which you want to create the submodule 284 * @param url URL for the submodule's remote 285 * @param path Path at which the submodule should be created 286 * @param use_gitlink Should workdir contain a gitlink to the repo in 287 * .git/modules vs. repo directly in workdir. 288 * @return 0 on success, GIT_EEXISTS if submodule already exists, 289 * -1 on other errors. 290 */ 291 GIT_EXTERN(int) git_submodule_add_setup( 292 git_submodule **out, 293 git_repository *repo, 294 const char *url, 295 const char *path, 296 int use_gitlink); 297 298 /** 299 * Perform the clone step for a newly created submodule. 300 * 301 * This performs the necessary `git_clone` to setup a newly-created submodule. 302 * 303 * @param out The newly created repository object. Optional. 304 * @param submodule The submodule currently waiting for its clone. 305 * @param opts The options to use. 306 * 307 * @return 0 on success, -1 on other errors (see git_clone). 308 */ 309 GIT_EXTERN(int) git_submodule_clone( 310 git_repository **out, 311 git_submodule *submodule, 312 const git_submodule_update_options *opts); 313 314 /** 315 * Resolve the setup of a new git submodule. 316 * 317 * This should be called on a submodule once you have called add setup 318 * and done the clone of the submodule. This adds the .gitmodules file 319 * and the newly cloned submodule to the index to be ready to be committed 320 * (but doesn't actually do the commit). 321 * 322 * @param submodule The submodule to finish adding. 323 */ 324 GIT_EXTERN(int) git_submodule_add_finalize(git_submodule *submodule); 325 326 /** 327 * Add current submodule HEAD commit to index of superproject. 328 * 329 * @param submodule The submodule to add to the index 330 * @param write_index Boolean if this should immediately write the index 331 * file. If you pass this as false, you will have to get the 332 * git_index and explicitly call `git_index_write()` on it to 333 * save the change. 334 * @return 0 on success, <0 on failure 335 */ 336 GIT_EXTERN(int) git_submodule_add_to_index( 337 git_submodule *submodule, 338 int write_index); 339 340 /** 341 * Get the containing repository for a submodule. 342 * 343 * This returns a pointer to the repository that contains the submodule. 344 * This is a just a reference to the repository that was passed to the 345 * original `git_submodule_lookup()` call, so if that repository has been 346 * freed, then this may be a dangling reference. 347 * 348 * @param submodule Pointer to submodule object 349 * @return Pointer to `git_repository` 350 */ 351 GIT_EXTERN(git_repository *) git_submodule_owner(git_submodule *submodule); 352 353 /** 354 * Get the name of submodule. 355 * 356 * @param submodule Pointer to submodule object 357 * @return Pointer to the submodule name 358 */ 359 GIT_EXTERN(const char *) git_submodule_name(git_submodule *submodule); 360 361 /** 362 * Get the path to the submodule. 363 * 364 * The path is almost always the same as the submodule name, but the 365 * two are actually not required to match. 366 * 367 * @param submodule Pointer to submodule object 368 * @return Pointer to the submodule path 369 */ 370 GIT_EXTERN(const char *) git_submodule_path(git_submodule *submodule); 371 372 /** 373 * Get the URL for the submodule. 374 * 375 * @param submodule Pointer to submodule object 376 * @return Pointer to the submodule url 377 */ 378 GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule); 379 380 /** 381 * Resolve a submodule url relative to the given repository. 382 * 383 * @param out buffer to store the absolute submodule url in 384 * @param repo Pointer to repository object 385 * @param url Relative url 386 * @return 0 or an error code 387 */ 388 GIT_EXTERN(int) git_submodule_resolve_url(git_buf *out, git_repository *repo, const char *url); 389 390 /** 391 * Get the branch for the submodule. 392 * 393 * @param submodule Pointer to submodule object 394 * @return Pointer to the submodule branch 395 */ 396 GIT_EXTERN(const char *) git_submodule_branch(git_submodule *submodule); 397 398 /** 399 * Set the branch for the submodule in the configuration 400 * 401 * After calling this, you may wish to call `git_submodule_sync()` to 402 * write the changes to the checked out submodule repository. 403 * 404 * @param repo the repository to affect 405 * @param name the name of the submodule to configure 406 * @param branch Branch that should be used for the submodule 407 * @return 0 on success, <0 on failure 408 */ 409 GIT_EXTERN(int) git_submodule_set_branch(git_repository *repo, const char *name, const char *branch); 410 411 /** 412 * Set the URL for the submodule in the configuration 413 * 414 * 415 * After calling this, you may wish to call `git_submodule_sync()` to 416 * write the changes to the checked out submodule repository. 417 * 418 * @param repo the repository to affect 419 * @param name the name of the submodule to configure 420 * @param url URL that should be used for the submodule 421 * @return 0 on success, <0 on failure 422 */ 423 GIT_EXTERN(int) git_submodule_set_url(git_repository *repo, const char *name, const char *url); 424 425 /** 426 * Get the OID for the submodule in the index. 427 * 428 * @param submodule Pointer to submodule object 429 * @return Pointer to git_oid or NULL if submodule is not in index. 430 */ 431 GIT_EXTERN(const git_oid *) git_submodule_index_id(git_submodule *submodule); 432 433 /** 434 * Get the OID for the submodule in the current HEAD tree. 435 * 436 * @param submodule Pointer to submodule object 437 * @return Pointer to git_oid or NULL if submodule is not in the HEAD. 438 */ 439 GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); 440 441 /** 442 * Get the OID for the submodule in the current working directory. 443 * 444 * This returns the OID that corresponds to looking up 'HEAD' in the checked 445 * out submodule. If there are pending changes in the index or anything 446 * else, this won't notice that. You should call `git_submodule_status()` 447 * for a more complete picture about the state of the working directory. 448 * 449 * @param submodule Pointer to submodule object 450 * @return Pointer to git_oid or NULL if submodule is not checked out. 451 */ 452 GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); 453 454 /** 455 * Get the ignore rule that will be used for the submodule. 456 * 457 * These values control the behavior of `git_submodule_status()` for this 458 * submodule. There are four ignore values: 459 * 460 * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents 461 * of the submodule from a clean checkout to be dirty, including the 462 * addition of untracked files. This is the default if unspecified. 463 * - **GIT_SUBMODULE_IGNORE_UNTRACKED** examines the contents of the 464 * working tree (i.e. call `git_status_foreach()` on the submodule) but 465 * UNTRACKED files will not count as making the submodule dirty. 466 * - **GIT_SUBMODULE_IGNORE_DIRTY** means to only check if the HEAD of the 467 * submodule has moved for status. This is fast since it does not need to 468 * scan the working tree of the submodule at all. 469 * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo. 470 * The working directory will be consider clean so long as there is a 471 * checked out version present. 472 * 473 * @param submodule The submodule to check 474 * @return The current git_submodule_ignore_t valyue what will be used for 475 * this submodule. 476 */ 477 GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( 478 git_submodule *submodule); 479 480 /** 481 * Set the ignore rule for the submodule in the configuration 482 * 483 * This does not affect any currently-loaded instances. 484 * 485 * @param repo the repository to affect 486 * @param name the name of the submdule 487 * @param ignore The new value for the ignore rule 488 * @return 0 or an error code 489 */ 490 GIT_EXTERN(int) git_submodule_set_ignore( 491 git_repository *repo, 492 const char *name, 493 git_submodule_ignore_t ignore); 494 495 /** 496 * Get the update rule that will be used for the submodule. 497 * 498 * This value controls the behavior of the `git submodule update` command. 499 * There are four useful values documented with `git_submodule_update_t`. 500 * 501 * @param submodule The submodule to check 502 * @return The current git_submodule_update_t value that will be used 503 * for this submodule. 504 */ 505 GIT_EXTERN(git_submodule_update_t) git_submodule_update_strategy( 506 git_submodule *submodule); 507 508 /** 509 * Set the update rule for the submodule in the configuration 510 * 511 * This setting won't affect any existing instances. 512 * 513 * @param repo the repository to affect 514 * @param name the name of the submodule to configure 515 * @param update The new value to use 516 * @return 0 or an error code 517 */ 518 GIT_EXTERN(int) git_submodule_set_update( 519 git_repository *repo, 520 const char *name, 521 git_submodule_update_t update); 522 523 /** 524 * Read the fetchRecurseSubmodules rule for a submodule. 525 * 526 * This accesses the submodule.<name>.fetchRecurseSubmodules value for 527 * the submodule that controls fetching behavior for the submodule. 528 * 529 * Note that at this time, libgit2 does not honor this setting and the 530 * fetch functionality current ignores submodules. 531 * 532 * @return 0 if fetchRecurseSubmodules is false, 1 if true 533 */ 534 GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( 535 git_submodule *submodule); 536 537 /** 538 * Set the fetchRecurseSubmodules rule for a submodule in the configuration 539 * 540 * This setting won't affect any existing instances. 541 * 542 * @param repo the repository to affect 543 * @param name the submodule to configure 544 * @param fetch_recurse_submodules Boolean value 545 * @return old value for fetchRecurseSubmodules 546 */ 547 GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules( 548 git_repository *repo, 549 const char *name, 550 git_submodule_recurse_t fetch_recurse_submodules); 551 552 /** 553 * Copy submodule info into ".git/config" file. 554 * 555 * Just like "git submodule init", this copies information about the 556 * submodule into ".git/config". You can use the accessor functions 557 * above to alter the in-memory git_submodule object and control what 558 * is written to the config, overriding what is in .gitmodules. 559 * 560 * @param submodule The submodule to write into the superproject config 561 * @param overwrite By default, existing entries will not be overwritten, 562 * but setting this to true forces them to be updated. 563 * @return 0 on success, <0 on failure. 564 */ 565 GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite); 566 567 /** 568 * Set up the subrepository for a submodule in preparation for clone. 569 * 570 * This function can be called to init and set up a submodule 571 * repository from a submodule in preparation to clone it from 572 * its remote. 573 * 574 * @param out Output pointer to the created git repository. 575 * @param sm The submodule to create a new subrepository from. 576 * @param use_gitlink Should the workdir contain a gitlink to 577 * the repo in .git/modules vs. repo directly in workdir. 578 * @return 0 on success, <0 on failure. 579 */ 580 GIT_EXTERN(int) git_submodule_repo_init( 581 git_repository **out, 582 const git_submodule *sm, 583 int use_gitlink); 584 585 /** 586 * Copy submodule remote info into submodule repo. 587 * 588 * This copies the information about the submodules URL into the checked out 589 * submodule config, acting like "git submodule sync". This is useful if 590 * you have altered the URL for the submodule (or it has been altered by a 591 * fetch of upstream changes) and you need to update your local repo. 592 */ 593 GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule); 594 595 /** 596 * Open the repository for a submodule. 597 * 598 * This is a newly opened repository object. The caller is responsible for 599 * calling `git_repository_free()` on it when done. Multiple calls to this 600 * function will return distinct `git_repository` objects. This will only 601 * work if the submodule is checked out into the working directory. 602 * 603 * @param repo Pointer to the submodule repo which was opened 604 * @param submodule Submodule to be opened 605 * @return 0 on success, <0 if submodule repo could not be opened. 606 */ 607 GIT_EXTERN(int) git_submodule_open( 608 git_repository **repo, 609 git_submodule *submodule); 610 611 /** 612 * Reread submodule info from config, index, and HEAD. 613 * 614 * Call this to reread cached submodule information for this submodule if 615 * you have reason to believe that it has changed. 616 * 617 * @param submodule The submodule to reload 618 * @param force Force reload even if the data doesn't seem out of date 619 * @return 0 on success, <0 on error 620 */ 621 GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule, int force); 622 623 /** 624 * Get the status for a submodule. 625 * 626 * This looks at a submodule and tries to determine the status. It 627 * will return a combination of the `GIT_SUBMODULE_STATUS` values above. 628 * How deeply it examines the working directory to do this will depend 629 * on the `git_submodule_ignore_t` value for the submodule. 630 * 631 * @param status Combination of `GIT_SUBMODULE_STATUS` flags 632 * @param repo the repository in which to look 633 * @param name name of the submodule 634 * @param ignore the ignore rules to follow 635 * @return 0 on success, <0 on error 636 */ 637 GIT_EXTERN(int) git_submodule_status( 638 unsigned int *status, 639 git_repository *repo, 640 const char *name, 641 git_submodule_ignore_t ignore); 642 643 /** 644 * Get the locations of submodule information. 645 * 646 * This is a bit like a very lightweight version of `git_submodule_status`. 647 * It just returns a made of the first four submodule status values (i.e. 648 * the ones like GIT_SUBMODULE_STATUS_IN_HEAD, etc) that tell you where the 649 * submodule data comes from (i.e. the HEAD commit, gitmodules file, etc.). 650 * This can be useful if you want to know if the submodule is present in the 651 * working directory at this point in time, etc. 652 * 653 * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags 654 * @param submodule Submodule for which to get status 655 * @return 0 on success, <0 on error 656 */ 657 GIT_EXTERN(int) git_submodule_location( 658 unsigned int *location_status, 659 git_submodule *submodule); 660 661 /** @} */ 662 GIT_END_DECL 663 #endif 664