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